HTTP Basic Authentication


A client can authenticate to the API Gateway with a username and password combination using HTTP Basic Authentication. When an HTTP Basic Authentication filter is configured, the API Gateway requests the client to present a username and password combination as part of the HTTP Basic challenge-response mechanism.

With HTTP Basic Authentication, the client's username and password are concatenated, base64-encoded, and passed in the Authorization HTTP header as follows:

Authorization: Basic dm9yZGVsOnZvcmRlbA==

The API Gateway can then authenticate this user against a user profile stored in the API Gateway's local repository, a database, or an LDAP directory. The realm presented in the challenge for HTTP Basic Authentication is the realm currently specified in the system settings. See the Default Settings topic for more information.


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

To configure the HTTP Basic 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 Basic 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 another (for example, the client's username could be a DName), you must 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.

Allow Client Challenge

HTTP Basic Authentication can use the following approaches:

  • Direct Authentication

    The client sends up the Authorization HTTP Basic Authentication header in its first request to the server.

  • Challenge-Response Handshake

    The client does not send the Authorization header when sending its request to the server (it does not know that the server requires HTTP Basic Authentication). The server responds with an HTTP 401 response code, instructing the client to authenticate to the server by sending the Authorization header. The client then sends a second request, this time including the Authorization header and the relevant username and password.

The first case is used mainly for machine-to-machine transactions in which there is no human intervention. The second case is typical of situations where a browser is talking to a Web server. When the browser receives the HTTP 401 response to its initial request, it displays a dialog to enable the user to enter the username and password combination.

If you wish to force clients to always send the HTTP Basic Authorization header to the API Gateway, deselect the Allow client challenge checkbox. If you wish to allow clients to engage in the HTTP Basic Authentication challenge-response handshake with the API Gateway, ensure this feature is enabled by selecting this option.

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 the API Gateway's local repository, a database, or an LDAP directory. Select a pre-configured Repository Name from the drop-down list.

You can add a new repository in the tree on the left 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 the Authentication Repository tutorial.