Introduction
These documents provide guidelines for configuring LDAP search and authentication requests. The more specific these requests can be the better the performance will be for all applications using the LDAP service:
- LDAP Java Example
- .NET (C#) Example
- Spring Example
- Standard look and feel for Michigan Medicine (Level-2) LDAP authentication windows
- Standard Michigan Medicine (Level-2) LDAP error response
Instructions
LDAP Authentication Best Practice - How to Authenticate to LDAP
When making LDAP calls, the following five guidelines should be used:
1. Define Search Base
The search base is the point in the LDAP tree where a search begins. Leaving the search base undefined, or searching from RootDSE, causes the LDAP search engine to traverse the entire data store. If the search base is defined more specifically, the engine can find the desired data quicker using less resources.
In our environment, the search base should be set to "dc=med,dc=umich,dc=edu" (without the quotes).
Undesirable Search
base: ""
scope:2 dereference:0 sizelimit:1 timelimit:0 attrsonly:0
filter: "(mail=darthvader@med.umich.edu)"
Problem: No base defined
Preferred Search
base: "dc=med,dc=umich,dc=edu"
scope:2 dereference:0 sizelimit:1 timelimit:0 attrsonly:0
filter: "(uid=darthvader)"
Desired Attrs specified
2. Dereference Aliases
This is a method that requires you to set the alias pointer back to the data it points to. This is an expensive operation. We do not use aliases in our LDAP data store, but we do use alias outside of the recommended search base. If the search base is defined as specified above, there will be no issues with aliases. But, to be careful any search should be configured to NOT dereference aliases.
Undesirable
base: "dc=med,dc=umich,dc=edu"
scope:2 dereference:0 sizelimit:0 timelimit:0 attrsonly:0
filter: "(uid=darthvader)"
attribute: "surname"
Preferred
base: "dc=med,dc=umich,dc=edu"
scope:2 dereference:3 sizelimit:0 timelimit:0 attrsonly:0
filter: "(uid=darthvader)"
attribute: "surname"
attribute: "objectclass"
attribute: "subschemaSubentry"
3. Search for Users by UID Attribute
To locate users in LDAP, the UID attribute should be used. This value will be the same as a uniquename.
Undesirable search
base: "dc=med,dc=umich,dc=edu"
scope:2 dereference:0 sizelimit:25 timelimit:10 attrsonly:0
filter: "(&(objectclass=person)(cn=darthvader,ou=people,dc=med,dc=umich,dc=edu)"
attribute: "cn"
Problem – CN search not uid search
Preferred search
base: "dc=med,dc=umich,dc=edu"
scope:2 dereference:0 sizelimit:25 timelimit:10 attrsonly:0
filter: "(&(objectclass=person)(uid=darthvader))"
attribute: "cn"
4. Specify Desired Attributes to be Returned
Whenever possible, specific desired attributes should be requested. Searches that do not have attributes defined will automatically retrieve all object attributes. To optimize searches for performance specify desired attributes.
Undesirable Search
base: "cn=darthvader,ou=people,dc=med,dc=umich,dc=edu"
scope:0 dereference:3 sizelimit:0 timelimit:0 attrsonly:0
filter: "(objectClass=*)"
no attributes
Empty attribute list implies all user attributes
Problem – No attributes specified
Preferred Search
Search request
base: "cn= darthvader,ou=people,dc=med,dc=umich,dc=edu"
scope:0 dereference:3 sizelimit:0 timelimit:0 attrsonly:0
filter: "(objectClass=*)"
attribute: "groupMembership"
attribute: "mail"
attribute: "uid"
Desired attributes specified
5. Group Searches
When searching groups for members, specify the specific groups necessary. If not specified, the member attribute of all groups will be searched every time the search is invoked.
To identify the user being evaluated, do not use a hardcoded context. Instead, specify the FDN returned as your member= value in the search string. This will help prevent any problems or rework in the event the LDAP structure is expanded or changed.
Undesirable Search
Search request
base: "dc=med,dc=umich,dc=edu"
scope:2 dereference:3 sizelimit:0 timelimit:0 attrsonly:0
filter: "(&(objectClass=group)(member=cn=cpeterff,ou=people,dc=med,dc=umich,dc=edu))"
attribute: "cn"
Problem - No groups specified
Preferred Search
base: "dc=med,dc=umich,dc=edu"
scope:2 dereference:0 sizelimit:0 timelimit:0 attrsonly:0\
filter: "(&(objectClass=Group)(|(cn=mcit-iso*)(cn=umhs*))(member=cn=darthvader,ou=people,dc=med,dc=umich,dc=edu))"
Specific groups are defined. Wildcards may be used.
Establishing a Connection to the LDAP Service
| Parameter |
Pre-Prod |
Prod |
| DNS Name | ldap.p-ent.med.umich.edu | ldap.ent.med.umich.edu |
| Base DN: | dc = med, dc = umich, dc = edu | dc = med, dc = umich, dc = edu |
| Port | 636 | 636 |
| Principle |
cn = {System Account} Contact Account Admin to have account created and IDM to have appropriate rights set-up. |
cn = {System Account} Contact Account Admin to have account created and IDM to have appropriate rights set-up. |
| Mechanism | Simple | Simple |
| SSL | Yes | Yes |
Error Handling
A user may receive an error message when attempting to authenticate to an LDAP directory. Below is a list of error message indexes and the corresponding response that a user sees.
| Message Index |
Response Given to User |
| 0x80070005 | You have insufficient rights to perform required operation |
| 0x8007052E | User Name or Password you have provided is incorrect |
| 0x80072030 | User Name you have provided is incorrect |
| 0x80072035 | Your account is locked out or has expired. Please contact HITS Service Desk |
| -197 | Your account has been locked out for a period of time. You have tried the incorrect password too many times |
| -215 | Please enter a unique password. Password cannot be reused |
| -216 | Password Reset Error: password must be at least 6 characters long |
| -220 | Your account has expired. Please contact HITS Service Desk |
| -222 | Password you have provided is bad. |
| -601 | User Name you have provided is incorrect |
| -669 | Password you have provided is incorrect. |
| -672 | Update Error: insufficient rights |
Below is a list of error message indexes and the corresponding response that a user sees in XML format.
<LdapErrorMessages>
<message index="(0x80070005)" ldap="LDAP_INSUFFICIENT_RIGHTS" win32="ERROR_ACCESS_DENIED">
You have insufficient rights to perform required operation
</message>
<message index="(0x8007052E)" ldap="LDAP_INVALID_CREDENTIALS" win32="ERROR_LOGON_FAILURE">
User Name or Password you have provided is incorrect
</message>
<message index="(0x80072030)" ldap="LDAP_NO_SUCH_OBJECT" win32="ERROR_DS_NO_SUCH_OBJECT">User Name you have provided is incorrect</message>
<message index="(0x80072035)" ldap="LDAP_UNWILLING_TO_PERFORM" win32="ERROR_DS_UNWILLING_TO_PERFORM">
Your account is locked out or has expired. Please contact MCIT Help Desk
</message>
<message index="(-215)">
Please enter a unique password. Password cannot be reused
</message>
<message index="(-216)">
Password Reset Error: password must be at least 6 characters long
</message>
<message index="(-601)">User Name you have provided is incorrect</message>
<message index="(-669)">Password you have provided is incorrect.</message>
<message index="(-222)">Password you have provided is bad.</message>
<message index="(-672)">Update Error: insufficient rights</message>
<message index="(-197)">
Your account has been locked out for a period of time. You have tried the incorrect password too many times
</message>
<message index="(-220)">
Your account has expired. Please contact MCIT Help Desk
</message>
</LdapErrorMessages>