Configure LDAP directories


A filter that uses an LDAP directory to authenticate a user or retrieve attributes for a user must have an LDAP directory associated with it. You can use the Configure LDAP Server dialog to configure connection details of the LDAP directory. Both LDAP and LDAPS (LDAP over SSL) are supported.

When a filter that uses an LDAP directory is run for the first time after a server refresh/restart, the server binds to the LDAP directory using the connection details configured on the Configure LDAP Server dialog. Usually, the connection details include the user name and password of an administrator user who has read access to all users in the LDAP directory for whom you wish to retrieve attributes or authenticate.

General configuration

Configure the following general LDAP connection settings:

Enter or select a name for the LDAP filter in the drop-down list.

Enter the URL location of the LDAP directory. The URL is a combination of the protocol (LDAP or LDAPS), the IP address of the host machine, and the port number for the LDAP service. By default, port 389 is reserved for LDAP connections, while port 636 is reserved for LDAPS connections. For example, the following are valid LDAP directory URLs:


Cache Timeout:
Specifies the timeout for cached LDAP connections. Any cached connection that is not used in this time period is discarded. Defaults to 300000 milliseconds (5 minutes). A cache timeout of 0 means that the LDAP connection is cached indefinitely and never times out.

Cache Size:
Specifies the number of cached LDAP connections. Defaults to 8 connections. A cache size of 0 means that no caching is performed.

Authentication configuration

If the configured LDAP directory requires clients to authenticate to it, you must select the appropriate authentication method in the Authentication Type field. When the API Gateway connects to the LDAP directory, it is authenticated using the selected method. Choose one of the following authentication methods:

Note   If any of the following authentication methods connect to the LDAP server over SSL, that server's SSL certificate must be imported into the API Gateway certificate store.


No authentication credentials need to be submitted to the LDAP server for this method. In other words, the client connects anonymously to the server. Typically, a client is only allowed to perform read operations when connected anonymously to the LDAP server. It is not necessary to enter any details for this authentication method.


Simple authentication involves sending a user name and corresponding password in clear text to the LDAP server. Because the password is passed in clear text to the LDAP server, it is recommended to connect to the server over an encrypted channel (for example, over SSL).

It is not necessary to specify a Realm for the Simple authentication method. The realm is only used when a hash of the password is supplied (for Digest-MD5). However, in cases where the LDAP server contains multiple realms, and the specified user name is present in more than one of these realms, it is at the discretion of the specific LDAP server as to which user name binds to it.

Select the SSL Enabled checkbox to force the API Gateway to connect to the LDAP directory over SSL.

To successfully establish SSL connections with the LDAP directory, you must import the directory's certificate into the API Gateway's certificate store. You can do this using the global Certificates window (see Manage X.509 certificates and keys). For LDAPS (LDAP over SSL) connections, the LDAP server's certificate must be imported into the Policy Studio JRE trusted store. For more details, see Test the LDAP connection.


With Digest-MD5 authentication, the server generates some data and sends it to the client. The client encrypts this data with its password according to the MD5 algorithm. The LDAP server then uses the client's stored password to decrypt the data and hence authenticate the user.

The Realm field is optional, but may be necessary in cases where the LDAP server contains multiple realms. If a realm is specified, the LDAP server attempts to authenticate the user for the specified realm only.


External authentication enables you to use client certificate-based authentication when connecting to an LDAP directory. When this option is selected, you must select a client certificate from the API Gateway certificate store. The SSL Enabled checkbox is selected automatically. Click the Signing Key button to select the client certificate to use to mutually authenticate to the LDAP server.

Note   This means that you must specify the URL field using LDAPS (for example, ldaps:// The user name, password, and realm fields are not required for external authentication.

Test the LDAP connection

When you have specified all the LDAP connection details, you can click the Test Connection button to verify that the connection to the LDAP directory is configured successfully. This enables you to detect any configuration errors at design time, rather than at runtime.

For LDAPS (LDAP over SSL) connections, the LDAP server's certificate must be imported into the Policy Studio JRE trusted store. You can do this by performing the following steps in Policy Studio:

  1. Select the Environment ConfigurationCertificates and Keys > Certificates node in the Policy Studio tree.
  2. In the Certificates panel on the right, click Create/Import, and click Import Certificate.
  3. Browse to the LDAP server's certificate file, and click Open.
  4. Click Use Subject on the right of the Alias Name field, and click OK. The LDAP server's certificate is now imported into the Certificate Store, and must be added to the Java keystore.
  5. In the Certificates panel, select the certificates that you wish the JRE to trust.
  6. Click Export to Keystore, and browse to the cacerts file in the following directory:
  7. INSTALL_DIR\policystudio\Win32\jre\lib\security\cacerts
  8. Select the cacerts file.
  9. Click Save.
  10. You are prompted for a password.
  11. Click OK.
  12. Restart Policy Studio.
  13. You can now click Test Connection to test the connection to the LDAP directory server over SSL.

Additional JNDI properties

You can also specify optional JNDI properties as simple name-value pairs. Click the Add button to specify properties in the dialog.

Related Links