Troubleshooting LDAP configuration

Use the ldapsearch command line tool to troubleshoot your LDAP (Lightweight Directory Access Protocol) configuration.

Install ldapsearch

Install the ldapsearch program.

On Ubuntu, run the following command:

sudo apt-get install ldap-utils

On Red Hat Enterprise Linux (RHEL), run the following command:

sudo yum install openldap-clients

Test LDAP connection

To test your LDAP connection, run the following command:

ldapsearch -x -H "<LDAP_URL>" -b "<LDAP_BASEDN>" -D "<LDAP_BINDDN>" -w "<LDAP_BINDPASSWORD>" -s sub

Following are the parameter descriptions:

  • <LDAP_URL> is the URL of the LDAP server. For example, ldap://<LDAP server domain name or IP address>:<port> or ldaps://<LDAP server domain name>:<port>. The default port number is 389 for LDAP protocol and 636 for LDAP over Secure Sockets Layer (LDAPS) protocol.
  • <LDAP_BASEDN> is the LDAP distinguished name (DN) of the search base. For example, dc=abc,dc=com.
  • <LDAP_BINDDN> is the LDAP user who is allowed to search the base DN. For example, cn=admin,dc=abc,dc=com.
  • <LDAP_BINDPASSWORD> is the password of the user who is mentioned in the bind DN.

Example commands

ldapsearch -x -H "ldap://<hostname or IP address>:389" -b "o=abc.com" -s sub

ldapsearch -x -H "ldap://<hostname or IP address>:389" -b "dc=abc,dc=com" -D "cn=admin,dc=abc,dc=com" -w "password" -s sub

Validate LDAP filters

Create a search string based on the LDAP filters to retrieve data from your LDAP server. If the search results show one or more LDAP entries, then the LDAP filter configuration is correct. If the search results do not show any entry, then the LDAP filter is not correct or is not compatible with your LDAP server type.

ldapsearch -x -H "<LDAP_URL>" -b "<LDAP_BASEDN>" -D "<LDAP_BINDDN>" -w "<LDAP_BINDPASSWORD>" -s sub "<Search string>"

Following are the parameter descriptions:

  • <LDAP_URL> is the URL of the LDAP server. For example, ldap://<LDAP server domain name or IP address>:<port> or ldaps://<LDAP server domain name>:<port>. The default port number is 389 for LDAP protocol and 636 for LDAPS protocol.
  • <LDAP_BASEDN> is the LDAP DN of the search base. For example, dc=abc,dc=com.
  • <LDAP_BINDDN> is the LDAP user who is allowed to search the base DN. For example, cn=admin,dc=abc,dc=com.
  • <LDAP_BINDPASSWORD> is the password of the user who is mentioned in the bind DN.
  • <search string> is the search string that is used to search your LDAP server.

IBM Tivoli Directory Server LDAP filters

Table 1. IBM Tivoli Directory Server LDAP filters
Attribute name Default value
Group filter (&(cn=%v)(objectclass=groupOfUniqueNames))
Group ID map *:cn
Group Member ID map groupOfUniqueNames:uniqueMember
User filter (&(emailAddress=%v)(objectclass=person))
User ID map *:emailAddress
  • Example command to validate group filter
    ldapsearch -x -H "<LDAP_URL>" -b "<LDAP_BASEDN>" -D "<LDAP_BINDDN>" \
-w "<LDAP_BINDPASSWORD>" -s sub "(&(cn=*)(objectclass=groupOfUniqueNames))"
  • Example command to validate group ID map
    ldapsearch -x -H "<LDAP_URL>" -b "<LDAP_BASEDN>" -D "<LDAP_BINDDN>" \
-w "<LDAP_BINDPASSWORD>" -s sub "(&(objectclass=*)(cn=*))"
  • Example command to validate group member ID map
    ldapsearch -x -H "<LDAP_URL>" -b "<LDAP_BASEDN>" -D "<LDAP_BINDDN>" \
-w "<LDAP_BINDPASSWORD>" -s sub "(&(objectclass=groupOfUniqueNames)(uniqueMember=*))"
  • Example command to validate user filter
    ldapsearch -x -H "<LDAP_URL>" -b "<LDAP_BASEDN>" -D "<LDAP_BINDDN>" \
-w "<LDAP_BINDPASSWORD>" -s sub "(&(emailAddress=*)(objectclass=person))"
  • Example command to validate user ID map
    ldapsearch -x -H "<LDAP_URL>" -b "<LDAP_BASEDN>" -D "<LDAP_BINDDN>" \
-w "<LDAP_BINDPASSWORD>" -s sub "(&(objectclass=*)(emailAddress=*))"

Microsoft Active Directory LDAP filters

Table 2. Microsoft Active Directory LDAP filters
Attribute name Default value
Group filter (&(cn=%v)(objectcategory=group))
Group ID map *:cn
Group Member ID map memberOf:member
User filter (&(sAMAccountName=%v)(objectcategory=user))
User ID map user:sAMAccountName
  • Example command to validate group filter
    ldapsearch -x -H "<LDAP_URL>" -b "<LDAP_BASEDN>" -D "<LDAP_BINDDN>" \
-w "<LDAP_BINDPASSWORD>" -s sub "(&(cn=*)(objectcategory=group))"
  • Example command to validate group ID map
    ldapsearch -x -H "<LDAP_URL>" -b "<LDAP_BASEDN>" -D "<LDAP_BINDDN>" \
-w "<LDAP_BINDPASSWORD>" -s sub "(&(objectcategory=*)(cn=*))"
  • Example command to validate group member ID map
    ldapsearch -x -H "<LDAP_URL>" -b "<LDAP_BASEDN>" -D "<LDAP_BINDDN>" \
-w "<LDAP_BINDPASSWORD>" -s sub "(&(objectcategory=*)(member=*))"
  • Example command to validate user filter
    ldapsearch -x -H "<LDAP_URL>" -b "<LDAP_BASEDN>" -D "<LDAP_BINDDN>" \
-w "<LDAP_BINDPASSWORD>" -s sub "(&(sAMAccountName=*)(objectcategory=user))"
  • Example command to validate user ID map
    ldapsearch -x -H "<LDAP_URL>" -b "<LDAP_BASEDN>" -D "<LDAP_BINDDN>" \
-w "<LDAP_BINDPASSWORD>" -s sub "(&(objectcategory=user)(sAMAccountName=*))"

Custom (OpenLDAP) server LDAP filters

Table 3. Custom (OpenLDAP) server LDAP filters
Attribute name Default value
Group filter (&(cn=%v)(objectclass=groupOfUniqueNames))
Group ID map *:cn
Group Member ID map groupOfUniqueNames:uniqueMember
User filter (&(uid=%v)(objectclass=person))
User ID map *:uid
  • Example command to validate group filter
    ldapsearch -x -H "<LDAP_URL>" -b "<LDAP_BASEDN>" -D "<LDAP_BINDDN>" \
-w "<LDAP_BINDPASSWORD>" -s sub "(&(cn=*)(objectclass=groupOfUniqueNames))"
  • Example command to validate group ID map
    ldapsearch -x -H "<LDAP_URL>" -b "<LDAP_BASEDN>" -D "<LDAP_BINDDN>" \
-w "<LDAP_BINDPASSWORD>" -s sub "(&(objectclass=*)(cn=*))"
  • Example command to validate group member ID map
    ldapsearch -x -H "<LDAP_URL>" -b "<LDAP_BASEDN>" -D "<LDAP_BINDDN>" \
-w "<LDAP_BINDPASSWORD>" -s sub "(&(objectclass=groupOfUniqueNames)(uniqueMember=*))"
  • Example command to validate user filter
    ldapsearch -x -H "<LDAP_URL>" -b "<LDAP_BASEDN>" -D "<LDAP_BINDDN>" \
-w "<LDAP_BINDPASSWORD>" -s sub "(&(uid=*)(objectclass=person))"
  • Example command to validate user ID map
    ldapsearch -x -H "<LDAP_URL>" -b "<LDAP_BASEDN>" -D "<LDAP_BINDDN>" \
-w "<LDAP_BINDPASSWORD>" -s sub "(&(objectclass=*)(uid=*))"

Resolve common login issues

Unable to login to cp-console or cpd using LDAP authentication

The ClassCastException error is displayed if the ObjectClass or ObjectCategory attribute is not defined in the Liberty XML file. The following error is displayed in the logs of the auth-service pods:

Exception = java.lang.ClassCastException
Source = com.ibm.ws.security.oauth20.plugins.jose4j.OidcUserClaims
probeid = 178
Stack Dump = java.lang.ClassCastException: com.ibm.wsspi.security.wim.model.Entity incompatible with com.ibm.wsspi.security.wim.model.PersonAccount
	at com.ibm.ws.security.oauth20.plugins.jose4j.OidcUserClaims.getUserinfoFromRegistryMap(OidcUserClaims.java:136)
	at com.ibm.ws.security.oauth20.plugins.jose4j.OidcUserClaims.getUserinfoFromRegistry(OidcUserClaims.java:177)
	at com.ibm.ws.security.openidconnect.web.OidcEndpointServices.getUserinfoFromRegistry(OidcEndpointServices.java:1001)
	at com.ibm.ws.security.openidconnect.web.OidcEndpointServices.userinfo(OidcEndpointServices.java:922)
	at com.ibm.ws.security.openidconnect.web.OidcEndpointServices.handleOidcRequest(OidcEndpointServices.java:281)
	at com.ibm.ws.security.openidconnect.web.OidcEndpointServlet.handleRequest(OidcEndpointServlet.java:111)
	at com.ibm.ws.security.openidconnect.web.OidcEndpointServlet.doPost(OidcEndpointServlet.java:69)
	at javax.servlet.http.HttpServlet.service(HttpServlet.java:707)
Resolving the issue

IM supports the LDAP Entity type configuration for LDAP User and Group entities to define the ObjectClass or ObjectCategory attributes automatically in the Liberty XML file.

For the existing LDAP connection, you need to restart the platform-auth-service pods to enable the LDAPEntityType configuration.

  1. Get the platform-auth-service pod name.

    oc get pods -n <your-foundational-services-namespace> | grep platform-auth-service

  2. Delete the platform-auth-service pod.

    oc delete pod <platform-auth-service-pod-name> -n <your-foundational-services-namespace>

The following is the sample Liberty XML file with the LDAP configuration:

<server>
    <featureManager>
        <feature>ldapRegistry-3.0</feature>
    </featureManager>
    <ldapRegistry id="SunOneLDAP" realm="REALM" host="[dd103bgpvip1165.virginia.ms.com](https://dd103bgpvip1165.virginia.ms.com/)" port="389"
            ignoreCase="false" baseDN="o=Morgan Stanley" bindDN="msfwid=2053167,ou=prodids,o=Morgan Stanley"
            bindPassword="{xor}OQ9mHBIlFQVoaGk4NSgK" ldapType="Sun Java System Directory Server" recursiveSearch="true" sslEnabled="false"
            certificateMapMode="CERTIFICATE_FILTER" certificateFilter="uid=${SubjectCN}">
         <ldapEntityType name="PersonAccount">
                <objectClass>msperson</objectClass>
         </ldapEntityType>
         <!-- For Groups -->
        <ldapEntityType name="Group">
                  <objectClass>msaclgroup</objectClass>
       </ldapEntityType>
        <iplanetFilters
            userFilter="(&amp;(objectClass=msperson)(uid=%v))"
            groupFilter="(&amp;(cn=%v)(objectclass=msaclgroup)(mseonid=24507))"
            userIdMap="*:uid"
            groupIdMap="*:cn"
            groupMemberIdMap="groupofuniquenames:uniquemember" />
	    <ldapCache>
	      <attributesCache size="2000" timeout="1200s" enabled="true" sizeLimit="2000"/>
	      <searchResultsCache size="2000" timeout="1200s" enabled="true" resultsSizeLimit="2000"/>
	    </ldapCache>
    </ldapRegistry>
</server>

Unable to log in as LDAP user after you configure an LDAP connection

You might not be able to log in as an LDAP user even when the connection test and the LDAP configuration are successful.

You see an error that indicates an invalid username or password.

You might see the following error in the log files of the platform-auth-service container:

CWIML4537E: The login operation could not be completed. The specified principal name XXXXXX is not found in the back-end repository.

To identify the error, enable trace for Liberty service to know the exact error in First failure data capture (FFDC) logs. For more information, see Enable debugging for user authentication issues.

Following are the possible causes. A resolution is provided for each cause.

Cause 1 - Invalid username value is used when you logged in

The user name value is not the same as the userIdMap filter attribute value.

Resolution for cause 1

Ensure that you enter the correct user name. The user name must be the same as the userIdMap filter attribute value. The user name is case-sensitive.

Consider the following example:

LDAP user details on an LDAP server:

dn: uid=testuser,ou=people,dc=abc,dc=com
objectClass: inetOrgPerson
objectClass: organizationalPerson
objectClass: person
objectClass: top
cn: TestUser
givenName: TestUser
sn: SN
uid: testuser
userPassword: testuser
mail: testuser@abc.com

LDAP configuration:

User filter: (&(uid=%v)(objectclass=person))
User ID map: *:uid

If you use *:uid as the userIdMap filter, then you must use the uid value testuser as the user name when you log in.

Cause 2 - LDAP login user or Bind DN user is disabled or locked at the LDAP server
  • The LDAP login user is disabled or locked at the LDAP server due to many unsuccessful login attempts.
  • The Bind DN user is disabled or locked at LDAP server due to many unsuccessful login attempts.
Resolution for cause 2
  • Use the ldapsearch tool to test the LDAP connection.
  • Enable or unlock the LDAP login user or Bind DN user at the LDAP server.
Cause 3 - Invalid Password value is used to log in
  • The LDAP user password might be wrong.
  • The Bind DN password might contain some unsupported special characters.
Resolution for cause 3
  • Enter the correct password and try logging in.
  • If the Bind DN password has special characters, change the password and do not use special characters in the changed password.
Cause 4 - LDAP configuration might not be synchronized across all the pods in a high availability (HA) cluster

The login request might be going to a pod in an HA cluster that does not have the LDAP configuration.

Resolution for cause 4

Restart the platform-auth-service pod. If the issue is still not resolved, restart the platform-auth-service, platform-identity-provider, and platform-identity-management pods.

Cause 5 - LDAP connection issues due to various reasons
  • The LDAP server is not reachable.
  • You used the LDAP server hostname in the LDAP server URL, and the hostname is not reachable. This issue might be because the correct DNS server entries were not added during cluster installation.
  • If LDAPS is used to configure the LDAP connection, following might be the possible causes:
    • An IP address is used instead of the LDAP server hostname in the LDAP server URL.
    • The LDAP server certificate is not imported into your cluster.
    • The LDAP server certificate does not match with the LDAP server hostname (or certificate SANs (Subject Alternative Names)).
Resolution for cause 5
  • Test the LDAP connection by using the ldapsearch tool.
  • Add the LDAP server hostname in the /etc/hosts file either on the master node or in the platform-auth-service container.
  • For configuring an LDAPS connection, use the LDAP server hostname in the LDAP server URL and the LDAP server certificate is imported into your cluster. Followed all the required steps for Configuring LDAP over SSL.
  • Change the hostname, or get a new certificate that matches with the LDAP server hostname or any one of the certificate SANs.
Cause 6 - External database connection failed in the platform-auth-service container

You can see external database connection failure errors in the logs of the platform-auth-service container.

Resolution for cause 6

Restart the platform-auth-service pod that is configured with the external database.

Resolve common issues with search users or groups

Unable to search users or groups while you create a team.

Cause

You used an invalid search string.

Resolution

You must use the value of the cn attribute or the user or group attribute such as uid or emailaddress that you used in the LDAP configuration.

Consider the following example:

LDAP user details on an LDAP server
  dn: uid=testuser,ou=people,dc=abc,dc=com
  objectClass: inetOrgPerson
  objectClass: organizationalPerson
  objectClass: person
  objectClass: top
  cn: TestUser
  givenName: TestUser
  sn: SN
  uid: testuser
  userPassword: testuser
  mail: testuser@abc.com

Following filters are used in the LDAP configuration:

  • User filter: (&(uid=%v)(objectclass=person))
  • User ID map: *:uid

The userIdMap that is used is *:uid.

The valid values that you can use to search for a user are as follows:

  • TestUser (cn value)
  • testuser (uid value)