LDAP Login Handler

The LDAP login handler lets users sign in with the user name and password of an LDAP directory (OpenLDAP, Active Directory and others). On a successful sign-in Exponential creates a user account for the directory user, or updates the existing one, and places it in user groups according to the directory's group information. The password itself is checked by the directory.

The handler is part of the kernel (kernel/classes/datatypes/ezuser/ezldapuser.php) and is configured in settings/ldap.ini. PHP needs the ldap extension.

Switching it on

Login handlers are tried in the order of site.ini [UserSettings] LoginHandler[] until one accepts the user. Keep standard first, so that local accounts such as the administrator still work when the directory cannot be reached:

# settings/override/site.ini.append.php
[UserSettings]
LoginHandler[]
LoginHandler[]=standard
LoginHandler[]=LDAP

Then set the directory in settings/override/ldap.ini.append.php:

[LDAPSettings]
LDAPEnabled=true
LDAPServer=ldap.example.com
LDAPPort=389
LDAPVersion=3
LDAPBaseDn=ou--people,dc--example,dc--com
# leave both empty when the directory allows an anonymous bind
LDAPBindUser=cn--reader,dc--example,dc--com
LDAPBindPassword=secret
LDAPSearchScope=sub
LDAPLoginAttribute=uid
LDAPFirstNameAttribute=givenname
LDAPLastNameAttribute=sn
LDAPEmailAttribute=mail
Utf8Encoding=true

An INI value cannot contain =, so every DN and filter is written with LDAPEqualSign (-- as shipped) in its place: ou--people,dc--example,dc--com means ou=people,dc=example,dc=com. The bind password is a secret: keep the override file out of version control.

The sign-in, step by step

With LDAPDebugTrace=enabled each step is written to the debug output as a notice, numbered 1/5 to 5/5. Never leave the trace on in production: it can write the login name and password to the logs.

1. Connect and bind. The handler connects to LDAPServer and LDAPPort with protocol LDAPVersion (2 as shipped; most directories today need 3) and LDAPFollowReferrals, and binds as LDAPBindUser with LDAPBindPassword, or anonymously when they are empty. This account only needs to read the user entries.
2. Search for the user. It searches below LDAPBaseDn for an entry whose LDAPLoginAttribute equals the name typed in. LDAPSearchScope is sub (the whole subtree), one (one level below the base) or base (the base entry only). LDAPSearchFilters[] adds conditions, all of which must hold, for example LDAPSearchFilters[]=objectClass--inetOrgPerson.
3. Authenticate. It binds again, as the user's DN with the password typed in. If this bind succeeds, the user is signed in.
4. Groups. It decides which user groups the account belongs to: see LDAP group mapping types. Without a match the account goes to the default group of LDAPUserGroup[] (a content object ID or a group name, as LDAPUserGroupType says).
5. Store the account. It creates the user, or updates first name, last name, e-mail and groups of the existing one, and publishes it. First and last name are written to the attributes first_name and last_name of the user class.

If the first name is not in the directory but the common name is, set LDAPFirstNameAttribute=cn and LDAPFirstNameIsCommonName=true: the last name is taken off the common name. If the directory has no e-mail address, leave LDAPEmailAttribute empty and set [email protected]: the address becomes the login followed by the suffix.

Good to know

• A user whose local password matches is signed in by the standard handler without asking the directory. Accounts the LDAP handler created are found in the directory on each sign-in.
• The handler binds in plain LDAP; it does not start TLS itself. Use a network you trust between the web server and the directory.
• Roles are not taken from the directory: give the groups the handler uses the roles their users need (see Roles and settings).
• Every setting is listed with its shipped value in the settings of ldap.ini.

More

• LDAP group mapping types, Roles and settings and Changes since the 4.x releases.
• Single Sign On (SSO) handlers, for sign-in through another system.