Use this topic to configure the LDAP search filters. These steps are required to modify
existing user and group filters for a particular LDAP directory type, and also to set up certificate
filters to map certificates to entries in the LDAP server.
Before you begin
WebSphere®
Application Server uses Lightweight Directory Access Protocol (LDAP) filters to search and obtain
information about users and groups from an LDAP directory server. A default set of filters is
provided for each LDAP server that the product supports. You can modify these filters to fit your
LDAP configuration. After the filters are modified and you click OK or
Apply the directory type in the Standalone LDAP registry panel changes to
custom
, which indicates that custom filters are used. Also, you can develop filters to
support any additional type of LDAP server. The effort to support additional LDAP directories is
optional and other LDAP directory types are not supported. Complete the following steps in the
administrative console.
Procedure
-
Click .
-
Under User account repository, select Standalone LDAP registry and click
Configure.
-
Under Additional properties, click Advanced Lightweight Directory Access Protocol
(LDAP) user registry settings.
-
Modify the user filter, if necessary.
The user filter is used for searching the registry for users and is typically used for the
security role-to-user assignment. The filter is also used to authenticate a user with the attribute
that is specified in the filter. The filter specifies the property that is used to look up users in
the directory service.
In the following example, the property that is assigned to %v
,
which is the short name of the user, must be a unique key. Two LDAP entries with the same object
class cannot have the same short name. To look up users based on their user IDs (uid) and to use the
inetOrgPerson object class, specify the following syntax:
(&(uid=%v)(objectclass=inetOrgPerson)
For more information about
this syntax, see the Using specific directory servers as the LDAP server documentation.
-
Modify the Kerberos user filter, if necessary.
The Kerberos user filter name is used for searching the registry for the Kerberos principal
name. Specify the LDAP attribute that holds the Kerberos principal name.
- IBM Lotus Domino default krbuser filter:
- (&(krbPrincipalName=%v)(objectcategory=Person))
- IBM SecureWay Directory Server default krbuser filter:
- (&(krbPrincipalName=%v)(objectcategory=ePerson))
- Microsoft Active Directory default krbuser filter:
- (&(userprincipalname=%v)(objectcategory=user))
- Sun Java System Directory Server default krbuser filter:
- (&(krbPrincipalName=%v)(objectcategory=inetOrgPerson))
- Novell eDirectory default krbuser filter:
- (&(krbPrincipalName=%v)(objectcategory=Person))
- Optional:
If you are using Federated Repositories, modify the Kerberos attribute name if necessary.
The Kerberos attribute name is used for searching the registry for Kerberos principal. Specify
the LDAP attribute that holds the Kerberos principal name.
- IBM Lotus Domino default krbuser filter:
- krbPrincipalName
- IBM SecureWay Directory Server default krbuser filter:
- krbPrincipalName
- Microsoft Active Directory default krbuser filter:
- userprincipalname
- Sun Java System Directory Server default krbuser filter:
- krbPrincipalName
- Novell eDirectory default krbuser filter:
- krbPrincipalName
-
Modify the group filter, if necessary.
The group filter is used in searching the registry for groups and is typically used for the
security role-to-group assignment. Also, the filter is used to specify the property by which to look
up groups in the directory service.
In the following example, the property that is assigned to
%v
, which is the short name of the group, must be a unique key. Two LDAP entries with the
same object class cannot have the same short name. To look up groups based on their common names
(CN) and to use either the groupOfNames object class or the groupOfUniqueNames object class, specify
the following
syntax:
(&(cn=%v)(|(objectclass=groupOfNames)(objectclass=groupOfUniqueNames)))
For
more information about this syntax, see the Using specific directory servers as the LDAP server documentation.
-
Modify the user ID map, if necessary.
This filter maps the short name of a user to an LDAP entry and specifies the piece of
information that represents users when these users are displayed with their short names. For
example, to display entries of
object class = inetOrgPerson
by their IDs, specify
inetOrgPerson:uid
. This field takes multiple objectclass:property pairs, delimited by a
semicolon (;). To provide a consistent value for methods like the getCallerPrincipal method and the
getUserPrincipal method, the short name that is obtained by using this filter is used. For example,
the
CN=Bob Smith, ou=austin.ibm.com, o=IBM, c=US
user can log in using any attributes that
are defined, for example, email address, social security number, and so on, but when these methods
are called, the
bob
user ID is returned no matter how the user logs in.
Note: Only the getUserDisplayName API honors the user ID map.
-
Modify the group ID map filter, if necessary.
This filter maps the short name of a group to an LDAP entry and specifies the piece of
information that represents groups when groups display. For example, to display groups by their
names, specify *:cn
. The asterisk (*) is a wildcard character that searches on any object
class in this case. This field takes multiple objectclass:property pairs, delimited by a semicolon
(;).
-
Modify the group member ID map filter, if necessary.
This filter identifies user-to-group memberships. For SecureWay, and Domino® directory types, this field is
used to query all the groups that match the specified object classes to see if the user is contained
in the specified attribute. For example, to get all the users that belong to groups with the
groupOfNames object class and the users that are contained in the member attributes, specify
groupOfNames:member
. This syntax, which is a property of an object class, stores the list
of members that belong to the group that is represented by the object class. This field takes
multiple objectclass:property pairs that are delimited by a semicolon (;). For more information
about this syntax, see the
Using specific directory servers as the LDAP server.
For the IBM®
Tivoli® Directory
Server, Sun ONE, and Active Directory, this field is used to query all users in a group with the
information that is stored in the user object. For example, the memberof:member filter (for Active
Directory) is used to get the memberof attribute of the user object to obtain all the groups to
which the user belongs. The member attribute is used to get all the users in a group that use the
Group object. Using the User object to obtain the group information improves performance.
-
Select the Perform a nested group search option if your LDAP server does
not support recursive server-side searches.
-
Modify the Certificate map mode, if necessary.
You can use the X.590 certificates for user authentication when LDAP is selected as the
registry. This field is used to indicate whether to map the X.509 certificates into an LDAP
directory user by
EXACT_DN or
CERTIFICATE_FILTER. If
EXACT_DN is selected, the DN in the certificate must exactly match the user
entry in the LDAP server, including case and spaces.
Select the
Ignore case for
authorization option on the Standalone LDAP registry settings to make the authorization
case insensitive. To access the Standalone LDAP registry settings panel, complete the following steps:
- Click Security > Global security.
- Under User account repository, click the Available realm definitions
drop-down list, select Standalone LDAP registry.
-
If you select CERTIFICATE_FILTER, specify the LDAP filter for mapping
attributes in the client certificate to entries in LDAP.
If more than one LDAP entry matches the filter specification at run time, authentication fails
because an ambiguous match results. The syntax or structure of this filter is:
LDAP
attribute=${Client certificate attribute}
(for example,
uid=${SubjectCN}
).
One side
of the filter specification is an LDAP attribute that depends on the schema that your LDAP server is
configured to use. The other side of the filter specification is one of the public attributes in
your client certificate. Note that the filter specification that is one of the public attributes in
your client certificate must begin with a dollar sign ($), open bracket ({), and end with a close
bracket (}). Use the following certificate attribute values on the side of the filter specification
that is one of the public attributes in your client certificate. The case of the strings is
important.
${UniqueKey}
${PublicKey}
${IssuerDN}
${Issuer<xx>}
where <xx> is replaced by the characters that represent any valid component of the
Issuer Distinguished Name. For example, you might use ${IssuerCN}
for the Issuer
Common Name.
${NotAfter}
${NotBefore}
${SerialNumber}
${SigAlgName}
${SigAlgOID}
${SigAlgParams}
${SubjectDN}
${Subject<xx>}
where <xx> is replaced
by the characters that represent any valid component of the Subject Distinguished Name. For example,
you might use ${SubjectCN
} for the Subject Common Name.
If the certificate
includes a multi-valued relative distinguished name (RDN) that is separated by a plus sign character
(
+
), as described in
RFC 4514 section 2.2, you must specify the
security.registry.ldap.compoundRDNParsingEnabled
custom property. To specify this
property, complete the following steps:
- Click .
- In the custom property field after the Ignore case for
authorization checkbox, set the
security.registry.ldap.compoundRDNParsingEnabled
custom property to
true
.
- Restart the server.
${Version}
To enable this field, select CERTIFICATE_FILTER for the certificate
mapping.
Avoid trouble: Subject alternative names (SANs) are not
supported as certificate filter items.
-
Click Apply.
When any LDAP user or group filter is modified in the Advanced LDAP Settings panel click
Apply. Clicking
OK navigates you to the Standalone LDAP registry panel, which contains
the previous LDAP directory type, rather than the custom LDAP directory type. Clicking
OK or
Apply in the Standalone LDAP registry panel saves the back-level LDAP directory type and the
default filters of that directory. This action overwrites any changes to the filters that you made.
To avoid overwriting changes, you can take either of the following actions:
- Click Apply in the Advanced Lightweight Directory Access Protocol (LDAP) user registry
settings panel. Click Security > Global security and change the User account repository
type to
Stand-alone custom registry
.
- Select Custom type from the Standalone LDAP registry panel. Click Apply and then
change the filters by clicking the Advanced Lightweight Directory Access Protocol (LDAP) user
registry settings panel. After you complete your changes, click Apply or OK.
The validation of the changes does not take place in this panel. Validation is done when you
click OK or Apply on the Global security panel. If you are in the process of enabling
security for the first time, complete the remaining steps and go to the Global security panel.
Select Standalone LDAP registry as the user account repository. If security is already
enabled and any 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.
Results
These steps result in the configuration of the LDAP search filters. These steps are required
to modify existing user and group filters for a particular LDAP directory type. The steps are also
used to set up certificate filters to map certificates to entries in the LDAP server.
What to do next
- Validate this setup by clicking OK or Apply on the
Global security panel.
- Save, stop, and start all the product servers, including the cell, nodes and all of the
application servers for any changes in this panel to become effective.
- After the server starts, go through all the security-related tasks (getting users, getting
groups, and so on) to verify that the changes to the filters function.