Validate Username Token (validate-usernametoken)

Use the Validate Username Token policy to validate a Web Services Security (WS-Security) UsernameToken in a SOAP payload before allowing access to the protected resource.

Restriction: The Validate Username Token policy can be used only with the DataPower® Gateway.

About

A WS-Security UsernameToken enables a user identity to be passed securely over a multi-point message path. The Validate Username Token policy extracts the UsernameToken element from the request payload, authenticates the extracted username and password, and provides access to the protected resource based on the authentication result. The policy has two authentication methods: Lightweight Directory Access Protocol (LDAP) user registry, or Authentication URL.

The Validate Username Token policy supports both passwordText and passwordDigest types of password. When the authentication method is Authentication URL with a passwordDigest, a basic authentication header that contains a Base64 encoded username and passwordDigest is sent to the URL. In addition, a custom header named X-IBM-PasswordType is set with a value of digest. The following table shows the authentication process based on password type:

Table 1. Authentication URL process by password type
passwordText	passwordDigest
Authentication: Basic base64(username:password)	Authentication: Basic base64(username:passwordDigest) X-IBM-PasswordType: 'digest'

You can attach this policy to the following API flows:

REST
SOAP

Position this policy where required in the assembly flow as follows:

To validate the original input, position a Validate Username Token policy at the start of your flow.
To validate an intermediate response that is returned from other invoke actions or tasks, position a Validate Username Token policy after those actions or tasks.
To validate the response that is returned to the client application, position a Validate Username Token policy after the task that collates the response.

Important: If you are using IBM® API Connect for IBM Cloud (the SaaS offering), any LDAP registry that you use must be visible on the internet, it must not be accessible only from within your corporate intranet.

Properties

The following table lists the policy properties, indicates whether a property is required, specifies the valid and default values for input, and specifies the data type of the values.

Table 2. Validate Username Token policy properties
Property label	Property name	Required	Description	Data type
Title	title	Yes	The title of the policy. The default value is `validate-usernametoken`.	string
Description	description	No	A description of the policy.	string
Authentication type	auth-type	Yes	The authentication type to use to validate the UsernameToken. Valid values: `Authentication URL`: Select this value to validate the user credentials against an authentication URL. `LDAP registry`: Select this value to validate the user credentials against an LDAP user registry. The default value is: `Authentication URL`.	string
Authentication URL	auth-url	Yes	The authentication URL to use to validate the UsernameToken user credentials against. Note: This property is required only if Authentication type is set to `Authentication URL`.	string
TLS profile	tls-profile	No	The TLS profile to use for the secure transmission of data to the authentication URL. Note: This property is available only if Authentication type is set to `Authentication URL`.	string
LDAP registry name	ldap-registry	Yes	The name of the LDAP user registry to validate the UsernameToken user credentials against. You can select a name from the drop-down list, or type a name manually. Note: This property is required only if Authentication type is set to `LDAP registry`.	string
LDAP search attribute¹	ldap-search-attribute	Yes	The name of the LDAP user password attribute. Note: This property is required only if Authentication type is set to `LDAP registry`.	string

Examples

The following example shows an LDAP user registry authentication:

- validate-usernametoken:
    title: "validate-usernametoken"
    auth-type: "LDAP Registry"
    ldap-registry: "wstest"
    ldap-search-attribute: "userPassword"

The following example shows an Authentication URL definition:

- validate-usernametoken:
    title: "validate-usernametoken"
    auth-type: "Authentication URL"
    auth-url: "https://www.google.com"
    tls-profile: "default-ssl-profile"

Errors

The policy returns an HTTP 200 status code when successful, and the input payload is copied to the output flow. For all failure types the policy returns an HTTP 500 status code, and the output contains the SOAP fault.

Tip: If there are authentication failures, try verifying the LDAP user registry configuration as follows:

Ensure Search (DN) is set as the communication method.
Ensure Authenticated Bind is set so that specific permissions are required to search the registry.
Ensure the Admin DN and Password fields are correctly completed for the Distinguished Name (DN) of a user authorized to carry out searches in the LDAP directory.
Ensure that a combination of Base DN, Prefix, and Suffix are set, such that they fully describe the user DN. For example:
- For a user named: cn=alice, dc=ibm, dc=com
```
BaseDN: dc=ibm
Prefix: cn=alice
Suffix: dc=com
```
  where the user DN is calculated as: Prefix + BaseDN + Suffix.

¹ When authenticating with LDAP and passwordText, the policy uses the username and password as LDAP bind credentials. However, when authenticating with LDAP and passwordDigest, the digest itself cannot be used for authentication. Instead, an LDAP search for the username is performed by using the administrator's distinguished name (DN) and password, and an attribute corresponding to the contents of the ldap-search-attribute is retrieved. A hash of the contents of this attribute (along with the Nonce and Created attributes, as in the WS-Security UsernameToken profile specification) is then compared to the passwordDigest.