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>
orldaps://<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>
orldaps://<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
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
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
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 issues
Unable to log in as an LDAP user if you used LDAPS to configure your 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.
Causes
-
The LDAP server certificate was not imported into IBM® Cloud Private.
-
You used IP address instead of the LDAP server hostname in the LDAP URL.
-
You used the LDAP server hostname in the LDAP URL. However, the hostname is not reachable. This issue might be because the correct DNS server entries were not added during IBM Cloud Private installation.
Resolution
-
First, ensure that you use the LDAP server host name in the LDAP URL. Then, import the LDAP server certificate.
-
Add the LDAP server host name in the
/etc/hosts
file either on the master node or in theplatform-auth-service
container of theauth-idp
pod.
Unable to log in as an LDAP user because of invalid user credentials
You see an error that indicates an invalid username or password.
Causes
-
The username is not the same as the USER ID map filter attribute value.
-
The user password contains XML-based special characters such as
$ < > & ' "
.
Resolution
-
Ensure that you enter the correct username. The username must be the same as the USER ID map filter attribute value. The username is case-sensitive.
Consider the following parameters that are used for an LDAP configuration:
LDAP user details: 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
If
*:uid
is used as the USER ID map filter, then you must usetestuser
as the username when you log in. -
Try removing the special characters from your password.
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 parameters that are used for an LDAP configuration:
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
The USER ID map 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)