HTTP Digest Authentication


A client can authenticate to the API Gateway with a username and password digest using HTTP Digest Authentication. When an HTTP Digest Authentication filter is configured, the API Gateway requests the client to present a username and password digest as part of the HTTP Digest challenge-response mechanism. The API Gateway can then authenticate this user against a user profile stored in the API Gateway database.

The realm presented in the challenge for HTTP Digest Authentication is the realm currently specified in the system settings. For more details, see the Default Settings topic.


The information specified on this screen informs the API Gateway where it can find user profiles for authentication purposes. The API Gateway can lookup user profiles in the API Gateway's local repository, in a database, or in an LDAP directory. Users can be added to the local repository using the Users interface. For more details, see the API Gateway Users tutorial.

To configure the HTTP Digest Authentication filter, complete the following settings:


Enter an appropriate name for the filter.

Credential Format

The username presented to the API Gateway during the HTTP Digest handshake can be of many formats, usually username or Distinguished Name (DName). Because the API Gateway has no way of inherently telling one format from the other (for example, the client's username could be a DName), it is necessary to specify the format of the credential presented by the client. This format is then used internally by the API Gateway when performing authorization lookups against third party Identity Management servers.

Session Timeout

As part of the HTTP Digest Authentication protocol, the API Gateway must generate a nonce (number used once) value, and send it to the client. The client uses this nonce to create the digest of the username and password. However, it should only be allowed a certain amount of time to do so. The Session Timeout field specifies the length of time (in milliseconds) for which the nonce is valid.

Allow Retries

Select this option to allow the user to retry their username/password in the browser when an HTTP 401 response code is received (for example, if authentication fails, or is not yet provided). The number of times that the browser displays the username/password dialog when an HTTP 401 is received is controlled by the browser (usually three times). This setting is not selected by default.

Remove HTTP Authentication Header

Select this option to remove the HTTP Authorization header from the downstream message. If this option is not selected, the incoming Authorization header is forwarded on to the destination Web Service.

Repository Name

This specifies the name of the Authentication Repository where all user profiles are stored. This can be in the API Gateway's local repository, in a database, or in an LDAP directory. Select a pre-configured Repository Name from the drop-down list. You can add a new repository in the tree under the External Connections node. Right-click the appropriate node under Authentication Repository Profiles (for example, Database Repositories), and select Add a new Repository. For more details, see Authentication Repository.