Configuring Lightweight Directory Access Protocol user registries

To access a user registry using the Lightweight Directory Access Protocol (LDAP), you must know a valid user name (ID) and password, the server host and port of the registry server, the base distinguished name (DN) and, if necessary, the bind DN and the bind password. You can choose any valid user in the user registry that is searchable. You can use any user ID that has the administrative role to log in.

Before you begin

Note: This topic references one or more of the application server log files. As a recommended alternative, you can configure the server to use the High Performance Extensible Logging (HPEL) log and trace infrastructure instead of using SystemOut.log , SystemErr.log, trace.log, and activity.log files on distributed and IBM® i systems. You can also use HPEL in conjunction with your native z/OS® logging facilities. If you are using HPEL, you can access all of your log and trace information using the LogViewer command-line tool from your server profile bin directory. See the information about using HPEL to troubleshoot applications for more information on using HPEL.

There are two different identities that are used for security purposes: the user ID for administrative functions and the server identity. When administrative security is enabled, the user ID and password for administrative functions is authenticated with the registry. If authentication fails, access to the administrative console is not granted or tasks with wsadmin scripts are not completed. It is important to choose an ID and password that do not expire or change often. If this user ID or password need to change in the registry, make sure that the changes are performed when all the application servers are up and running. When changes are to be made in the registry, review the article on Standalone Lightweight Directory Access Protocol registries (LDAP) before beginning this task.

The server identity is used for internal process communication. As part of this task, you can change the server identity from the default automatically generated ID to a server ID and password from the LDAP repository.

You can test LDAP server connections and search filters before you configure them.


  1. In the administrative console, click Security > Global security.
  2. Under User account repository, click the Available realm definitions drop-down list, select Standalone LDAP registry, and click Configure.
  3. Enter a valid user name in the Primary administrative user name field.
    Typically, the user name is the short name of the user and is defined by the user filter in the Advanced LDAP settings panel.
  4. Determine whether to specify the user identity that is used for internal process communication.
    Cells that contain Version 5.1 or 6.x nodes require a server user identity that is defined in the active user repository. By default, the Automatically generated server identity option is enabled, and the application server generates the server identity. However, you can select the Server identity that is stored in the repository option to specify both the server identity and its associated password.
  5. Select the type of LDAP server to use from the Type list.
    The type of LDAP server determines the default filters that are used by WebSphere® Application Server. These default filters change the Type field to Custom, which indicates that custom filters are used. This action occurs after you click OK or Apply in the Advanced LDAP settings panel. Choose the Custom type from the list and modify the user and group filters to use other LDAP servers, if required.

    IBM Tivoli® Directory Server users can choose IBM Tivoli Directory Server as the directory type. Use the IBM Tivoli Directory Server directory type for better performance.

    Attention: IBM SecureWay Directory Server has been renamed to IBM Tivoli Directory Server in WebSphere Application Server version 6.1.
  6. Enter the fully qualified host name of the LDAP server in the Host field.
    You can enter either the IP address or domain name system (DNS) name.
  7. Enter the LDAP server port number in the Port field.
    The host name and the port number represent the realm for this LDAP server in the WebSphere Application Server cell. So, if servers in different cells are communicating with each other using Lightweight Third Party Authentication (LTPA) tokens, these realms must match exactly in all the cells.

    The default value is 389. If multiple WebSphere Application Servers are installed and configured to run in the same single sign-on domain, or if the WebSphere Application Server interoperates with a previous version of the WebSphere Application Server, then it is important that the port number match all configurations. For example, if the LDAP port is explicitly specified as 389 in a version 5.x configuration, and a WebSphere Application Server at version 6.0.x is going to interoperate with the version 5.x server, then verify that port 389 is specified explicitly for the version 6.0.x server.

    You can set the custom property to change the value of the realm name that is placed in the token. For more information, see the security custom properties topic.

  8. Enter the base distinguished name (DN) in the Base distinguished name field.
    The base DN indicates the starting point for searches in this LDAP directory server. For example, for a user with a DN of cn=John Doe, ou=Rochester, o=IBM, c=US, specify the base DN as any of the following options, assuming a suffix of c=us:
    • ou=Rochester, o=IBM, c=us
    • o=IBM, c=us
    • c=us
    For authorization purposes, this field is case sensitive by default. Match the case in your directory server. If a token is received (for example, from another cell or Lotus® Domino®) the base DN in the server must match exactly the base DN from the other cell or Domino. If case sensitivity is not a consideration for authorization, enable the Ignore case for authorization option.

    In WebSphere Application Server, the distinguished name is normalized according to the Lightweight Directory Access Protocol (LDAP) specification. Normalization consists of removing spaces in the base distinguished name before or after commas and equal symbols. An example of a non-normalized base distinguished name is o = ibm, c = us or o=ibm, c=us. An example of a normalized base distinguished name is o=ibm,c=us.

    To interoperate between WebSphere Application Server Version 6.0 and later versions, you must enter a normalized base distinguished name in the Base Distinguished Name field. In WebSphere Application Server, Version 6.0 or later, the normalization occurs automatically during runtime.

    This field is required for all LDAP directories except the Lotus Domino Directory. The Base Distinguished Name field is optional for the Domino server.

  9. Optional: Enter the bind DN name in the Bind distinguished name field.
    The bind DN is required if anonymous binds are not possible on the LDAP server to obtain user and group information. If the LDAP server is set up to use anonymous binds, leave this field blank. If a name is not specified, the application server binds anonymously. See the Base Distinguished Name field description for examples of distinguished names.
  10. Optional: Enter the password corresponding to the bind DN in the Bind password field.
  11. Optional: Modify the Search time out value.
    This timeout value is the maximum amount of time that the LDAP server waits to send a response to the product client before stopping the request. The default is 120 seconds.
  12. Ensure that the Reuse connection option is selected.
    This option specifies that the server should reuse the LDAP connection. Clear this option only in rare situations where a router is used to send requests to multiple LDAP servers and when the router does not support affinity. Leave this option selected for all other situations.
  13. Optional: Verify that the Ignore case for authorization option is enabled.
    When you enable this option, the authorization check is case insensitive. Normally, an authorization check involves checking the complete DN of a user, which is unique in the LDAP server and is case sensitive. However, when you use either the IBM Directory Server or the Sun ONE (formerly iPlanet) Directory Server LDAP servers, you must enable this option because the group information that is obtained from the LDAP servers is not consistent in case. This inconsistency affects the authorization check only. Otherwise, this field is optional and can be enabled when a case sensitive authorization check is required. For example, you might select this option when you use certificates and the certificate contents do not match the case of the entry in the LDAP server.

    You can also enable the Ignore case for authorization option when you are using single sign-on (SSO) between the product and Lotus Domino. The default is enabled.

  14. Optional: Select the SSL enabled option if you want to use Secure Sockets Layer communications with the LDAP server.
    Important: This step will only be successful provided that the Signer certificate for the LDAP is first added to the truststore that will be eventually used. If the Signer certificate from the LDAP is not added to the truststore, then
    • An error will be issued by the Administrative console.
    • the deployment manager (DMGR) systemout.log will show the CWPKI0022E: SSL HANDSHAKE FAILURE message indicating that the Signer certificate needs to be added to the truststore.

    To ensure an error free operation for this step, You need to first extract to a file the Signer certificate of the LDAP and send that file to the WebSphere Application Server machine. You can then add the certificate to the truststore being defined for the LDAP. In this way, you are assured that the remaining actions for this step will be successful.

    If you select the SSL enabled option, you can select either the Centrally managed or the Use specific SSL alias option.
    Centrally managed
    Enables you to specify an SSL configuration for particular scope such as the cell, node, server, or cluster in one location. To use the Centrally managed option, you must specify the SSL configuration for the particular set of endpoints. The Manage endpoint security configurations and trust zones panel displays all of the inbound and outbound endpoints that use the SSL protocol. If you expand the Inbound or Outbound section of the panel and click the name of a node, you can specify an SSL configuration that is used for every endpoint on that node. For an LDAP registry, you can override the inherited SSL configuration by specifying an SSL configuration for LDAP. To specify an SSL configuration for LDAP, complete the following steps:
    1. Click Security > SSL certificate and key management > Manage endpoint security configurations and trust zones.
    2. Expand Outbound > cell_name > Nodes > node_name > Servers > server_name > LDAP.
    Use specific SSL alias
    Select the Use specific SSL alias option if you intend to select one of the SSL configurations in the menu.
    This configuration is used only when SSL is enabled for LDAP. The default is DefaultSSLSettings. You can click the name of an existing configuration to modify it or complete the following steps to create a new SSL configuration:
    1. Click Security > SSL certificate and key management.
    2. Under Configuration settings, click Manage endpoint security configurations.
    3. Select a Secure Sockets Layer (SSL) configuration_name for selected scopes, such as a cell, node, server, or cluster.
    4. Under Related items, click SSL configurations.
    5. Click New.
  15. Click OK or Apply until you return to the Global security panel, and on the Global Security page click Save, to make sure the LDAP configuration is saved.
  16. Check if Available realm definitions is set to Standalone LDAP registry. If it is not, select it from the pull down, and Set as current, then press Apply.


This set of steps is required to set up the LDAP user registry. This step is required as part of enabling security in the WebSphere Application Server.

What to do next

  1. If you are enabling security, complete the remaining steps as specified in Enabling security for the realm.
  2. [z/OS]If you want to use System Authorization Facility (SAF) authorization with your LDAP registry, then read about System Authorization Facility considerations for the operating system and application levels for more information.
  3. Save, stop, and restart all the product servers (deployment managers, nodes and Application Servers) for changes in this panel to take effect. If the server comes up without any problems the setup is correct.