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
When security is enabled in the
product, the primary administrative user name and password are authenticated
with the registry during the product startup. If authentication fails,
the server does not start. It is important to choose an ID and password
that do not expire or change often. If the product server user ID
or password need to change in the registry, make sure that the changes
are performed when all the product servers are up and running. When
changes are to be made in the registry, review the article on Lightweight Directory Access Protocol user registries (LDAP)
before beginning this task.
- In the administrative console, click Security
> Global security.
- Under User registries, click LDAP.
- Enter a valid user name in the Server
user ID field. You can either enter the complete distinguished
name (DN) of the user or the short name of the user, as defined by
the user filter in the Advanced LDAP settings panel. For example,
enter the user ID for Netscape browsers. This ID is the security server
ID, which is only used for WebSphere Application Server security and
is not associated with the system process that runs the server. The
server calls the local OS registry to authenticate and obtain privilege
information about users by calling the native application programming
interfaces (API) in that particular registry.
- Enter the password of the user in
the Server user password field.
- 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. For a list of supported
LDAP servers, see the Supported hardware, software, and APIs Web
site.
- 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.
- 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 com.ibm.websphere.security.ldap.logicRealm 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.
- 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 or o=IBM c=us or 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 5 and later versions,
you must enter a normalized base distinguished name in the Base
Distinguished Name field. In WebSphere Application Server, Version
5.0.1 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.
- 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.
- Optional: Enter the password corresponding
to the bind DN in the Bind password field.
- 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.
- 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.
- 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.
- 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, select the appropriate SSL alias configuration
from the list in the SSL configuration field. For more information
on setting up LDAP for SSL, see Configuring Secure Sockets Layer for the Lightweight Directory Access Protocol client.
- Optional: In the SSL
configuration field, select the Secure Sockets Layer configuration
to use for the LDAP connection. This configuration is used
only when SSL is enabled for LDAP. The default is DefaultSSLSettings.
To modify or create a new SSL configuration, click Security > SSL.
- Click OK. The
validation of the user, password, and the setup do not take place
in this panel. Validation is only done when you click OK or Apply in
the Global Security panel.
- If you are enabling security for the first time, complete the
remaining steps and go to the Global Security panel. Select LDAP as
the active user registry.
- If security is already enabled, but information on this panel
changes, go to the Global Security panel and click OK or Apply to
validate your changes. If your changes are not validated, the server
might not start.