How to authenticate users in IBM DataPower API Gateway

Introduction

In enterprise environments, authentication, authorization, and auditing (AAA) are crucial for securing APIs and services. IBM DataPower Gateway provides a powerful AAA Policy that allows integration with various identity providers, including LDAP servers.

In this guide, we will configure an AAA policy in IBM DataPower Gateway to authenticate users via an LDAP server using HTTP authentication headers and the Password-carrying UsernameToken element from the WS-Security header (SOAP).

Step 1: Create a New AAA Policy

Navigate to the IBM DataPower WebGUI and follow these steps:

1. Search AAA Policies.
2. Click Add to create a new AAA Policy.
3. Name it “aaa-acp”.

Step 2: Identity Extraction

The first step in the AAA policy is identity extraction:

1. In the Identity Extraction tab, select “HTTP Authentication Header” as the method.
2. This ensures that user credentials are extracted from the HTTP request sent by the client.

Step 3: Authentication

Now, configure authentication to validate the user against an LDAP server:

1. Navigate to the Authentication tab.
2. Select “Bind to LDAP server” as the authentication method, and fill the required field as shown below.

Note: The exact configuration values will vary based on your LDAP server setup.

I have created a LDAP entry in LDAP server as shown below.

Step 4: Resource Extraction

Next, configure resource extraction, which determines the resource being requested by the client:

1. In the Resource Extraction tab, select “URL Sent by Client”.
2. This will extract the requested URL for authorization purposes.

Step 5: Authorization

Set up authorization to control access based on authentication status:

1. Navigate to the Authorization tab.
2. Select “Allow Any Authenticated User”.
3. This ensures that any user who successfully authenticates via LDAP is granted access.

Step 6: Leave Other Tabs Unchanged

For now, keep other tabs (like Mapping Rules, Post-Processing etc.) as default. These can be customized later based on business requirements.

Step 7: Create an XML Firewall and Apply the AAA Policy

After setting up the AAA policy, we will now create an XML Firewall as loopback, means whatever request we will send to XMLF we will got same response if we are authenticated successfully.

1. Navigate to XML Firewalls in the IBM DataPower WebGUI.
2. Click Add to create a new XML Firewall.
3. Name it “aaa-xmlfw”.
4. Select “Loopback” type.

5. In the Processing Policy section, create a new rule aaa-xmlfw_request to apply AAA policy. drag AAA action on line and select AAA policy that we have created earlier.

Save and apply the configuration.

Now, any requests passing through the “aaa-xmlfw” XML Firewall will be authenticated using the configured AAA policy.

Finalizing and Testing

1. Test the authentication by sending an HTTP request with Valid credentials in the authentication header. I configured username as Ishfaq Ahmad and password is 12345 in LDAP server for testing purpose.
2. Request Message for Basic Authentication:

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:web="http://www.oorsprong.org/websamples.countryinfo" xmlns:wsse="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd">
    <soapenv:Header/>
    <soapenv:Body>
        <web:CapitalCity>
            <web:sCountryISOCode>PK</web:sCountryISOCode>
        </web:CapitalCity>
    </soapenv:Body>
</soapenv:Envelope>

With valid username and password we got the request payload in response as expected.

When username is invalid we got 401 unauthorized

LDAP error log when an incorrect username (e.g., ‘Ishfaq Ahmad5’) is entered.

Authentication with UsernameToken element (Method 2).

Select Password-carrying UsernameToken in Identity extraction.

1. Request Message for Usernametoken element:

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:web="http://www.oorsprong.org/websamples.countryinfo" xmlns:wsse="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd">
    <soapenv:Header>
        <wsse:Security>
            <wsse:UsernameToken>
                <wsse:Username>Ishfaq Ahmad</wsse:Username>
                <wsse:Password>12345</wsse:Password>
            </wsse:UsernameToken>
        </wsse:Security>
    </soapenv:Header>
    <soapenv:Body>
        <web:CapitalCity>
            <web:sCountryISOCode>PK</web:sCountryISOCode>
        </web:CapitalCity>
    </soapenv:Body>
</soapenv:Envelope>

Now, we will test authentication by including the username and password in the SOAP request header using the WS-Security standard. with the right user and password we got the request payload in response as expected.

When username is invalid we got 401 unauthorized.

LDAP error log when an incorrect username (e.g., ‘Ishfaq Ahmad2’) is entered.

DataPower error log snap when an incorrect username (e.g., ‘Ishfaq Ahmad2’) is entered.

Conclusion

Implementing LDAP-based authentication in IBM DataPower Gateway enhances security by ensuring that only authenticated users can access protected resources. By leveraging the AAA Policy, organizations can seamlessly integrate LDAP authentication, enforce access controls, and maintain a robust security posture.

We have tested with LDAP, but many other authentication methods exist, such as DataPower’s built-in AAA information file, verified JWT, access token, or ID token. These alternatives provide additional flexibility and security options based on organizational needs.

---

https://www.ibm.com/docs/en/datapower-gateway/10.6.0?topic=processing-aaa-policies