Configure LDAP search filters

Lightweight Directory Access Protocol (LDAP) filters are used by the WebSphere Application Server to search and obtain information about users and groups from a LDAP directory server. A default set of filters are provided for each LDAP server that the product supports. These filters can be modified to fit your LDAP configuration. Once the filters are modified (and OK or Apply is clicked) the directory type in the LDAP registry panel changes to custom, which indicates that custom filters are being used. Also, you can develop filters to support any additional type of LDAP server. The effort to support additional LDAP directories is optional, and IBM does not provide support for other LDAP directory types.

To configure search filters for LDAP, perform these steps in the administrative console:

1. Click Security --> User Registries --> LDAP. Under Additional Properties, click Advanced LDAP Settings.

2. Modify the user filter, if necessary.

   The user filter is used for searching the registry for users. It is typically used for Security Role to User assignment. It is also used to authenticate a user using the attribute specified in the filter. It specifies the property for which to look up users in the directory service. For example, to look up users based on their user IDs and using the object class inetOrgPerson, specify this property:

     (&(uid=%v)(objectclass=inetOrgPerson)

   where %v is replaced by the security run time with the uid attribute of the user. The user's uid attribute must be a unique key. This means that two LDAP entries with the same object class cannot have the same uid.

   For more information about this syntax, see your LDAP directory service documentation.

3. Modify the group filter if necessary.

   The group filter is used for searching the registry for groups. It is typically used for Security Role to Group assignment. It specifies the property by which to look up groups in the directory service. For example, to look up groups based on their common names (CN) and using the object class of either groupOfNames or groupOfUniqueNames, specify this property:

     (&(cn=%v)(|(objectclass=groupOfNames)(objectclass=groupOfUniqueNames)))

   For more information about this syntax, see your LDAP directory service documentation.

4. Modify the User ID Map filter if necessary.

   This filter maps the short name of a user to an LDAP entry. This specifies the piece of information that should represent users when users are displayed using their short names. For example, to display entries of the type 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 getCallerPrincipal() and getUserPrincipal(), the short name that is obtained by using this filter is used. For example the user CN=Bob Smith, ou=austin.ibm.com, o=IBM, c=US can log in using any attributes that were defined for him (for example, e-mail address, social security number, and so on) but when the above methods are called, the user ID bob is returned no matter how he logs in.

5. Modify the Group ID Map filter, if necessary.

   This filter maps the short name of a group to an LDAP entry. This specifies the piece of information that should represent groups when groups are displayed. 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 (;).

6. Modify the Group Member ID Map if necessary.

   This filter identifies User to Group memberships. For SecureWay, Netscape, and Domino directory types, this field is used to query all the groups that match the specified object class or classes to find if the user is contained in the attribute specified. For example, to get all the users belonging to groups whose object class is groupOfNames and the users are contained in the member attributes, specify groupOfNames:member. This specifies which property of an objectclass stores the list of members belonging to the group represented by the objectclass.

   This field takes multiple objectclass:property pairs delimited by a semicolon (;). For more information about this syntax, see your LDAP directory service documentation. For the IBM Directory Server, iPlanet, and Active Directory, this is used to query all users in a group by using the information stored in the user object (instead of querying all the groups individually to find if the user exists in that group). For example, the filter memberof:member (for Active Directory) is used to get the memberof attribute of the user object to get all the groups that the user belongs to. The member attribute is used to get all the users in a group using the group object. Using the user object to obtain the group information is expected to improve performance.

7. Modify the Certificate Map Mode, if necessary.

   The X.590 certificates can be used for user authentication when LDAP is selected as the user registry. The possible values are as follows:

   • EXACT_DN
     Map by exact distinguished name (DN). This approach attempts to map the distinguished name (DN) associated with the Subject field in the certificate to an entry in the LDAP directory. If the mapping is successful, the user is authenticated and is authorized according to the privileges granted to the identity in the LDAP directory.

     If EXACT_DN is selected, the distinguished name in the certificate should exactly match the user entry in the LDAP server (including case and spaces). If a match is found, authentication succeeds; if no match is found, authentication fails.

     Note: Use the Ignore Case field in the LDAP settings to make the authorization case insensitive.

   • CERTIFICATE_FILTER
     Map by filtering certificate attributes. This approach maps certificate attributes to attributes of entries in an LDAP directory. For example, you can specify that the common name (CN) attribute of the Subject field in the certificate must match the uid attribute of your LDAP entry. If the mapping is successful, the user is authenticated and is authorized according to the privileges granted to the identity in the LDAP directory.

     If you are matching the Subject CN field in the certificate to the uid attribute of the LDAP entry, a certificate with the Subject DN cn=Smith, ou=NewUnit, o=NewCompany, c=us matches an LDAP user entry with uid=Smith.

     If CERTIFICATE_FILTER is selected, fill in the appropriate certificate filter (in the next field) that should be used for mapping the certificate to a user in the LDAP.

8. If you specified the filter certificate mapping option, use the Certificate Filter property to specify the LDAP filter to use to map attributes in the client certificate to entries in LDAP.

   If more than one LDAP entry matches the filter specification at run time, then authentication fails because it results in an ambiguous match. The syntax or structure of this filter is:

     LDAP attribute=${Client certificate attribute}

   where attribute an LDAP attribute that depends on the schema that your LDAP server is configured to use, and Client certificate attribute is one of the public attributes in your client certificate. For example, uid=${SubjectCN}). Note that the client certificate attribute side must start with ${ and end with }.

   Here is a list of client certificate attribute values. The case of the strings is important.

   • ${UniqueKey}
   • ${PublicKey}
   • ${Issuer}
   • ${NotAfter}
   • ${NotBefore}
   • ${SerialNumber}
   • ${SigAlgName}
   • ${SigAlgOID}
   • ${SigAlgParams}
   • ${SubjectDN}
   • ${Version}

   To enable this field, select CERTIFICATE_FILTER for the certificate mapping.

9. Click OK.

   The validation of the changes (if any) does not take place in this panel. Validation is only done when the OK or Apply buttons are pressed in 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 LDAP as the Active User Registry. If security was already enabled and any information on this panel is changed, make sure to go to the Global Security panel and click OK or Apply to validate your changes. If your changes are not validated the server may not be able to start.