How LDAP connections work in Koha 3.4

by ByWater Staff on Sep 8, 2011

LDAP features available

Koha can connect to a single external LDAP server for user authentication, and in some cases, replication and updating of patron data. This works for general LDAP servers (like OpenLDAP), as well as Microsoft’s Active Directory.

For LDAP servers that bind by a single, privileged user, Koha can authenticate users, update existing user’s patron information and/or create new user accounts based on the LDAP record. The mapping from the LDAP server’s fields must be one-to-one, that is one LDAP field goes into one Koha field. The data comes over exactly as it is, without any kind additional logic (like normalization). The patron’s categorycode and branchcode must both be valid codes as configured in Koha. Default field values can be set.

For Active Directory and many other LDAP setups, LDAP is configured to bind as the individual user, instead of a single privileged user. At ByWater Solutions, we’ve found this to be the most common setup for our partners, but your mileage may vary. With this setup, update and replicate are currently not available. This is being worked on actively.

The LDAP authentication process

Each time a user tries to login to either the OPAC or the staff client, Koha first attempts to authenticate against LDAP. On success, several things can happen:

• if the patron is returning, and update is OFF, they are simply logged in with no changes to their Koha patron record
• if the patron is returning and update is ON, the information from LDAP that is mapped to Koha overwrites their existing Koha data in those fields. This includes hashing and storing the user’s LDAP password (md5 base 64 hash).
• if the patron is new, and replicate is turned ON, the information from LDAP is used to create a new patron record, based on the values in the mapping. The password is only stored locally in Koha if the password is part of the mapping.

If LDAP authentication fails, Koha then tries an internal authentication against the Koha database. This means you can have patrons and staff access Koha even if they do not have an LDAP record. You can also provide an alternate password for patrons or staff, in the event that your LDAP server goes down temporarily.

How to set up LDAP authentication

To turn on LDAP, you need to modify your koha-conf.xml file to include the necessary connection and mapping info, as well as as the flag to turn it all on. See C4/Auth_with_ldap.pm’s documentation for more details.

You’ll need the following information for all connections:

• LDAP server IP. If you’re running on a non-standard port, include the port. If you’re running over SSL, be sure to prefix the IP with “ldaps://”
• The base for LDAP search (something like “ou=Users,dc=bywatersolutions,dc=com”)

For privileged-user connections, you’ll need:

• An LDAP account that can perform ‘search’. Both username and password are required
• If you wish to use update or replicate, you’ll need a Mapping

• Mappings indicate what LDAP populates what Koha field. You can set a default value
• Branchcode, Categorycode, Surname, address and city are all required by the Koha database; be sure to provide default values for these
• If you include a mapping for password, it the hash of the password will be cached in Koha on Replicate. If you turn on Update, the hashed password will be stored in Koha regardless of whether you have this mapping or not.

For auth-by-bind connections (include Microsoft Active Directory), you’ll need this information:

• Principal-name format: typically, this is of the form “user@domain.com”, where user is the patron’s login, and “domain.com” is the domain of your institution.
• Your patrons will need to be loaded from CSV using the Bulk Patron Import tool in Koha. Userid will need to be populated with the LDAP user login you wish them to use, but password can remain blank (or a default password can be added)

For quick testing of the LDAP connection on the command line, you can do the following:

1. Be sure PERL5LIB and KOHA_CONF are exported correctly for your installation (see Koha Installation Documentation)
2. export DEBUG=2
3. /path/to/files/opac/opac-user.pl userid=your_test_ID password=test_user_password > junk.txt
4. You should see debug information about your LDAP connection

[Originally posted by Ian Walls]