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.
- Click Security > Global security.
- 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 your 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, e-mail
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, selectStandalone 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}).
The left side of the filter specification is an LDAP attribute
that depends on the schema that your LDAP server is configured to
use. The right side of the filter specification is one of the public
attributes in your client certificate. Note that the right side must
begin with a dollar sign ($), open bracket ({), and end with a close
bracket (}). Use the following certificate attribute values on the
right side of the filter specification. 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.
- ${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.
gotcha
- 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 Standalone 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.