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
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.
Procedure
- In the administrative console, click Security
> Secure administration, applications, and infrastructure.
- Under User account repository, click the Available
realm definitions drop-down list, select Standalone LDAP registry,
and click Configure.
- Enter a valid user name in the Primary
administrative user name 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 operating system registry
to authenticate and obtain privilege information about users by calling
the native application programming interfaces (API) in that particular
registry.
- Optional: If you want to use
the server ID that is stored in the repository, complete the following
substeps:
- Select Automatically generated server identity to
enable the application server to generate the server identity that
is used for internal process communication. You can change this server
identity on the Authentication mechanisms and expiration panel. To
access the Authentication mechanisms and expiration panel, click Security
> Secure administration, applications, and infrastructure > Authentication
mechanisms and expiration. Change the value of the Internal
server ID field.
- Alternatively, specify a user identity in the repository
that is used for internal process communication in the Server identity
that is stored in the repository field.
- Alternatively, specify the user ID that is used to run
the application server for security purposes in the Server user
ID or administrative user on a Version 6.0.x node 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.
Attention: IBM SecureWay
Directory Server has been renamed to IBM Tivoli Directory Server in
WebSphere Application Server version 6.1.
- 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, 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:
- Click Security > SSL certificate and key management > Manage
endpoint security configurations and trust zones.
- 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 below the option.
This
configuration is used only when SSL is enabled for LDAP. The default
is
DefaultSSLSettings. You can modify or create a new SSL configuration.
To create a new SSL configuration, complete the following
steps:
- Click Security > SSL certificate and key management.
- Under Configuration settings, click Manage endpoint security
configurations.
- Select a Secure Sockets Layer (SSL) configuration_name for
selected scopes, such as a cell, node, server, or cluster.
- Under Related items, click SSL configurations.
- Click New.
- Click OK and either Apply or Save until
you return to the Secure administration, applications, and infrastructure
panel.
Results
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
- If you are enabling security, complete the remaining steps as
specified in Enabling security for the realm.
- 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.