Configure Koha with Openldap authentication


Koha is an open source library management system. It is very powerful and fully customizable.  Koha can use the default authentication mechanism as well as LDAP servers like OpenLDAP, Active Directory to replicate and/or updating of patron (User) data. 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.

Each time a user tries to log in 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 the update is OFF, they are simply logged in with no changes to their Koha patron record
  • if the patron is returning and the 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.

Set up LDAP authentication

To turn on LDAP, you need to modify your koha-conf.xml (/etc/koha/sites/%site_name%/) file to include the necessary connection and mapping info, as well as as the flag to turn it all on.

<useldapserver>1</useldapserver><!– see C4::Auth_with_ldap for extra configs you must add if you want to turn this on –><ldapserver id=”ldapserver” listenref=”ldapserver”>
<user>uid=XXX,ou=XX,dc=XXX,dc=com</user><!– DN, if not anonymous –>
<pass>XXX</pass><!– password, if not anonymous –>
<replicate>1</replicate> <!– add new users from LDAP to Koha database –>
<update>1</update> <!– update existing users in Koha database –>
<auth_by_bind>1</auth_by_bind> <!– set to 1 to authenticate by binding instead of password comparison, e.g., to use Active Directory–>
<!– optional, for auth_by_bind: a printf format to make userPrincipalName from koha userid –>
<mapping> <!– match koha SQL field names to your LDAP record field names –>
<firstname is=”givenname”></firstname>
<surname is=”sn”></surname>
<address is=”postaladdress”>3900 University Blvd</address>
<city is=”l”>Tyler, TX</city>
<zipcode is=”postalcode”>75799</zipcode>
<branchcode is=””>KTM</branchcode>
<userid is=”uid”></userid>
<password is=””></password>
<email is=”mail”></email>
<categorycode is=””>KUL-STD</categorycode>
<phone is=”telephonenumber”>903-566-7343</phone>
<dateenrolled is=””>2011-03-27</dateenrolled>
<dateexpiry is=””>2021-05-13</dateexpiry>

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

Mappings indicate what LDAP populates what Koha field.

  • Branchcode, Categorycode, Surname, address, and city are all required by the Koha database. This field must be valid in Koha Database.
  • Example: <categorycode is=””>KUL-STD</categorycode> 
    • In Koha, we need to have 
  • Example: <branchcode is=””>KTM</branchcode>
    • In Koha, we need to have 
  • If you include a mapping for the password, 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 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.
  2. export DEBUG=2
  3. /path/to/files/opac/ userid=your_test_ID password=test_user_password > test.txt
  4. You should see debug information about your LDAP connection

I wish you success!



Anup Chhetri

IT system administrator

You may also like...

error: Content is protected !!