Troubleshooting LDAP errors

ENTERPRISE

Troubleshooting common authentication and configuration issues for your LDAP directory

The Lightweight Directory Access Protocol (LDAP) provides a lightweight client-server protocol for accessing directory services. The protocol provides a standards-based method for defining objects and their attributes for X.500-based directory services. LDAP runs over TCP/IP or other connection-oriented transfer services.

Common issues when using Microsoft Active Directory

Microsoft Windows Server Active Directory is the LDAP-based identity store for Windows forests and domains. Active Directory stores details about users, groups, computers, roles, and organizations in LDAP-compliant objects and attributes and returns the information you search for using LDAP queries in the same format as other LDAP services such as OpenLDAP.

Because integrating Active Directory authentication into a multi-platform environment can present challenges that you are less likely to encounter when you use ApacheDS, OpenLDAP, or other LDAP services, the most common issues with LDAP authentication and configuration involve communication with the Active Directory domain controllers or replication across Active Directory domains.

Cannot connect to the directory backend

If you attempt to retrieve information from Active Directory but the connection fails, you might see the following error message:

Cannot connect to the directory

Figure 1. Connection error message: timeout

If you see an error message indicating the connection to the backend directory failed, the problem is most often caused by one of the following issues:

  • A required port is closed to all traffic or protected by firewall rules.

    Specific port requirements depend on the version of Active Directory you are using and the type of communication traffic. For example, most LDAP traffic requires port 389 for TCP or UDP connections to handle directory and replication services, user and computer authentication, and group policy distribution.

    To handle the same type of traffic over a secure communications channel, LDAP requires port 636 for TCP connections to deliver encrypted messages over a secure socket layer (SSL).

  • DNS cannot resolve the name or IP address for the Active Directory domain controller.

If you encounter this error, check whether the computer where you saw the error has the correct IP address for the network interface and the domain controller. You can check the current IP address and network settings for domain connections using the DHCP server role or manually in the network adapter settings. For example, you can retrieve the current network settings for the computer using ipconfig or a similar operating system command to display network configuration details.

If there is a problem with the port number, host name, or host IP address, edit the values in the LDAP directory settings to specify the correct port, host name, or host IP address.

To edit the LDAP directory settings:

  1. Log in to the DC/OS web-based console.

  2. Click Settings, then click LDAP Directory.

  3. Click Edit Directory.

  4. Modify the host name, host IP address, or LDAP port.

  5. Click Save Configuration.

Transport layer security (SSL/TLS) connection errors

If you attempt to connect to Active Directory and the connection fails because there is a problem communicating with the server using transport layer security (SSL/TLS), you might see the following error message:

SSL connection error

Figure 2. Connection error: socket SSL wrapping error

For example, you might see this error if the LDAP server is not configured to accept SSL/TLS connections or if the certificate used to secure the channel is invalid.

If you have a problem connecting to Active Directory when using secure socket layer (SSL) connections, you should:

  • Check that LDAP over SSL (LDAPS) is enabled for the Active Directory LDAP server role and that you have imported a valid CA certificate to allow SSL/TLS connections.
  • Check how you have configured the appropriate corresponding LDAP SSL/TLS setting for the directory in the DC/OS cluster.

If the Active Directory LDAP server role is not configured to allow SSL/TLS connections, you should verify that the DC/OS cluster is configured to allow unencrypted communication.

To change how DC/OS handles SSL/TLS connection errors:

  1. Log in to the DC/OS web-based console.

  2. Click Settings, then click LDAP Directory.

  3. Click Edit Directory.

  4. Under Select SSL/TLS setting, select another option.

    SSL/TLS setting option

    Figure 3. SSL/TLS setting options

    For example, if you have configured the Select SSL/TLS setting to Use SSL/TLS for all connections, you might want to change the setting to Attempt StartTLS, proceed unencrypted if it fails.

  5. Click Save Configuration.

SSL/TLS is enforced but the connection fails

If you have configured connections to the LDAP server to abort if unable to use transport layer security (SSL/TLS), you might see the following error message:

Aborted SSL/TLS connections

Figure 4. Connection error message: TLS error

To change how DC/OS handles SSL/TLS connection errors:

  1. Log in to the DC/OS web-based console.

  2. Click Settings, then click LDAP Directory.

  3. Click Edit Directory.

  4. Under Select SSL/TLS setting, select another option.

    SSL/TLS setting option

    Figure 5. SSL/TLS setting option

    For example, if you want to continue to connect to the LDAP server when secure communication is not available, you can set the Select SSL/TLS setting to Attempt StartTLS, proceed unencrypted if it fails.

  5. Click Save Configuration.

Service account credential issues

If the connection to the LDAP server is successful, but the authentication credentials for the service account are incorrect, you might see the following error message:

LDAP authentication error

Figure 6. LDAP authentication error

To address this issue:

  1. Log in to the DC/OS web-based console.

  2. Click Settings, then click LDAP Directory.

  3. Click Edit Directory.

  4. Click Authentication.

  5. Correct the Lookup DN and the Lookup Password.

    Modify authentication information

    Figure 7. Modify authentication information

  6. Click Save Configuration.

Cannot find user

If the connection to the LDAP server is successful and the service account credentials are correct, but the user is not found, you might see the following error message:

LDAP user not found

Figure 8. LDAP user not found

In most cases, you will see this error if a specified user or service account is not within the scope of the user search base you have defined or if there is a problem with the distinguished name (DN) or distinguished name (DN) template used to bind to the LDAP server. If you see this error, you should verify the following settings:

  • The type of bind operation and authentication method you are using to connect to the LDAP server.
  • The scope defined for the user search base.
  • The user distinguished name (DN) template you are using.
  • The user search filter template you are using.

Specifying a user distinguished name (DN) template

If you are using simple authentication to bind to the LDAP server, be sure that you have specified a valid User DN Template. In most cases, the distinguished name template includes the runtime variable placeholder cn=%(username)s that is replaced in lookup requests with an actual account name value.

Specifying a user search base and filter template

If you are using search authentication to bind to the LDAP server, be sure that you have specified a valid User Search Base and User Search Filter Template.

The user search base should be broad enough to include the appropriate containers, organizational units, and domains you from which you want to return results.

When defining a search filter template, you should keep in mind the following:

  • The %(username)s runtime variable is a placeholder that is replaced in lookup requests with an actual account name value.
  • For OpenLDAP deployments, account lookup requests typically use the UID attribute so the search template placeholder is typically defined using (uid=%(username)s)).
  • For Active Directory deployments, account lookup requests typically use the sAMAccountName attribute so the search template placeholder is typically defined using (sAMAccountName=%(username)s)). In most cases, the sAMAccountName attribute is the account name users enter to log on to computers in the Windows domain.

Verifying Active Directory user account names

If you are using the LDAP server to access Active Directory accounts for Windows users, you can find the sAMAccountName attribute and other account information using Active Directory Users and Computers or Windows PowerShell.

To look up the account information using Active Directory Users and Computers:

  1. Log on to a Windows computer using an account with administrative privileges.

  2. Open the Control Panel for Administrative Tools.

  3. Open Active Directory Users and Computers.

  4. Select the user account.

    Selecting a user in Active Directory Users and Computers

    Figure 9. Active Directory selections

  5. Right-click, then select Properties.

  6. Click the Account tab and check the User login name.

    User login account property

    Figure 10. User login account

Checking for alternative account name formats

In some cases, you might want to look up account information using an alternative to the sAMAccountName. For example, you might want to look for account information by the userPrincipalName that defines unique accounts in a domain with the user@domain.com format.

If you want to use any other valid account name format such as user@domain.com, you can find the valid alternatives to replace the sAMAccountName by using Active Directory Users and Computers or by running commands using Windows PowerShell.

To look up Active Directory user information using Window PowerShell:

  1. Open the Windows PowerShell administrator console.

  2. Import the Active Directory module by using Import menu option or the Import-Module cmdlet. For example, in the PowerShell console you can run the import-module cmdlet like this: PS C:\Users\Administrator> import-module activedirectory

  3. Run the Get-ADUser cmdlet to retrieve the Active Directory properties for a specified user. For example: PS C:\Users\Administrator> Get-ADUser rmcdonald -properties *

This cmdlet returns all of the properties for the user with the SAMAccountName rmcdonald.

  1. AccountExpirationDate : 
  2. accountExpires : 9223372036854775807
  3. AccountLockoutTime : 
  4. AccountNotDelegated : False
  5. AllowReversiblePasswordEncryption : False
  6. BadLogonCount : 1
  7. badPasswordTime : 131896358930929294
  8. badPwdCount : 1 
  9. CannotChangePassword : False
  10. CanonicalName : example.com/Users/Ronald McDonald
  11. Certificates : {} 
  12. City : 
  13. CN : Ronald McDonald 
  14. codePage : 0 
  15. Company : 
  16. Country : 
  17. countryCode : 0 
  18. Created : 12/17/2018 2:27:43 PM 
  19. createTimeStamp : 12/17/2018 2:27:43 PM 
  20. Deleted : 
  21. Department : 
  22. Description : 
  23. DisplayName : Ronald McDonald 
  24. DistinguishedName : CN=Ronald McDonald,CN=Users,DC=example,DC=com
  25. Division : 
  26. DoesNotRequirePreAuth : False 
  27. dSCorePropagationData : {12/31/1600 4:00:00 PM}
  28. EmailAddress : 
  29. EmployeeID : 
  30. EmployeeNumber : 
  31. Enabled : True 
  32. Fax : 
  33. GivenName : Ronald
  34. HomeDirectory : 
  35. HomedirRequired : False 
  36. HomeDrive : 
  37. HomePage : 
  38. HomePhone : 
  39. Initials : 
  40. instanceType : 4
  41. isDeleted : 
  42. LastBadPasswordAttempt : 12/18/2018 11:44:53 AM
  43. LastKnownParent : 
  44. lastLogoff : 0 
  45. lastLogon : 0 
  46. LastLogonDate : 12/17/2018 2:36:30 PM
  47. lastLogonTimestamp : 131895597903404620
  48. LockedOut : False
  49. logonCount : 0 
  50. LogonWorkstations : 
  51. Manager : 
  52. MemberOf : {} 
  53. MNSLogonAccount : False
  54. MobilePhone : 
  55. Modified : 12/17/2018 2:36:30 PM 
  56. modifyTimeStamp : 12/17/2018 2:36:30 PM
  57. msDS-User-Account-Control-Computed : 0 
  58. Name : Ronald McDonald 
  59. nTSecurityDescriptor : System.DirectoryServices.ActiveDirectorySecurity
  60. ObjectCategory : CN=Person,CN=Schema,CN=Configuration,DC=example,DC=com 
  61. ObjectClass : user 
  62. ObjectGUID : 8a372fe3-b879-4a58-aabd-6001327b2548
  63. objectSid : S-1-5-21-1469461492-1576009741-989685995-1104
  64. Office : 
  65. OfficePhone : 
  66. Organization : 
  67. OtherName : 
  68. PasswordExpired : False 
  69. PasswordLastSet : 12/17/2018 2:27:43 PM
  70. PasswordNeverExpires : True
  71. PasswordNotRequired : False 
  72. POBox : 
  73. PostalCode : 
  74. PrimaryGroup : CN=Domain Users,CN=Users,DC=example,DC=com
  75. primaryGroupID : 513 
  76. ProfilePath : 
  77. ProtectedFromAccidentalDeletion : False
  78. pwdLastSet : 131895592635431368 
  79. SamAccountName : rmcdonald 
  80. sAMAccountType : 805306368 
  81. ScriptPath : 
  82. sDRightsEffective : 15 
  83. ServicePrincipalNames : {} 
  84. SID : S-1-5-21-1469461492-1576009741-989685995-1104
  85. SIDHistory : {} 
  86. SmartcardLogonRequired : False 
  87. sn : McDonald 
  88. State : 
  89. StreetAddress : 
  90. Surname : McDonald 
  91. Title : 
  92. TrustedForDelegation : False
  93. TrustedToAuthForDelegation : False
  94. UseDESKeyOnly : False
  95. userAccountControl : 66048 
  96. userCertificate : {} 
  97. UserPrincipalName : rmcdonald@example.com
  98. uSNChanged : 16787 
  99. uSNCreated : 16781 
  100. whenChanged : 12/17/2018 2:36:30 PM 
  101. whenCreated : 12/17/2018 2:27:43 PM

User with incorrect credentials

If the connection to the LDAP server is successful and the specified user can be found inside the scope of the user search base but the credentials are wrong, you might see the following error message:

Invalid user credentials

Figure 11. Invalid user credentials

If you see this error, check for the following potential issues that can cause the user credentials to be invalid:

  • Verify that the account is not locked or disabled.
  • Verify that the account password has not expired.
  • Check whether there are login hours or other access control restrictions preventing the user from being authenticated.