Koha, LDAP, And You! 11

If any of you have tried configuring LDAP in Koha, you have probably realized how complicated it can get. It gets especially complicated when you try and configure it to work with Active Directory. The problem is, no matter how many tutorials or blog posts you read, almost none of them have a solution to your problem. Most LDAP configurations are unique to your organization, which is the real complicating factor when setting up LDAP authentication. I am hoping that I can break out of the traditional post on the matter (usually, “this is how I did it, I hope it works for you too”) and give you a broader understanding of how LDAP works in Koha.

The Config File

The first file you will need to interact with in Koha is the koha-conf.xml. If you are on a development install, you will find this file in ~/koha-dev/etc/koha-conf.xml. If you are on a production install, you will probably find the file in /etc/koha/koha-conf.xml. Toward the very bottom of that config file you will see the following entry:


To enable LDAP you will want to change the 0 to a 1. This basically tells Koha that you want to try and authenticate via LDAP as well as using Koha authentication. You will also want to add the following XML section:

<ldapserver id="ldapserver">
  <user>cn=Manager,dc=metavore,dc=com</user> <!-- DN, if not anonymous -->
  <pass>metavore</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>0</auth_by_bind> <!-- set to 1 to authenticate by binding instead ofpassword comparison, e.g., to use Active Directory -->
  <principal_name>%s@my_domain.com</principal_name> <!-- 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"></address>
   <city is="l">Athens, OH</city>
   <zipcode is="postalcode"></zipcode>
   <branchcode is="branch">MAIN</branchcode>
   <userid is="uid"></userid>
   <password is="userpassword"></password>
   <email is="mail"></email>
   <categorycode is="employeetype">PT</categorycode>
   <phone is="telephonenumber"></phone>

It is important to note that all the fields in the <mapping> tag are not required. You may also include almost any of the fields in the borrowers table which can be found onSchema Spy. The tag inside of the <mapping> tag should correspond to the column in the database. The field that ‘is’ references is the field inside your LDAP configuration. You can assign a default value inside the subfields in mapping (see examples above). This can be especially helpful if you want to replicate users but don’t have the field you want to insert in Koha in LDAP. Other fields you will notice above are <update> and <replicate>. Update basically tells Koha that you want to pull information down from LDAP and update the fields in Koha. Replicate tells Koha that if a user doesn’t exist in the database check LDAP to verify that they are a valid user and pull their data down. If you use OpenLDAP or some other normal LDAP, you can safely ignore the <auth_by_bind> and <principal_name> tags. You should be safely authenticating if you are not using Active Directory. If you are using Active Directory, continue reading.

Active Directory LDAP

The lucky few that get the privilege of of configuring Koha using AD LDAP generally come out of the process with a few grey hairs. AD LDAP is generally pretty picky about what it accepts and you will probably find yourself tailing the error logs quite a bit to find out why authentication isn’t working. Before I begin, I feel the need to say the error logs can be found at (on a git install):


As mentioned above, you will need to add the<auth_by_bind> and <principal_name> tags to the <ldapserver> tag. Auth_by_bind is simple enough. It’s just a flag that tells Koha you will be binding to do authentication instead of password matching. The tag that will cause the most grief (in my experience) is the principal name tag. What goes in this tag depends on what you bind against in LDAP for the principal name. Typically this is the canonical email address for the user, Ex: elliott@bywatersolutions.com. You should really check your LDAP config just to be sure. I have come across some setups that dump the CN for the user in the principal name and some setups that won’t bind against the principal name at all. If you find the latter to be the case, you should try not using the principal name tag. If that also fails, you should contact your closest developer to help you patch C4::Auth_with_ldap.pm to fit your situation.

On a final note to AD LDAP users, I often get asked: “What is the %s for in the principal name tag?”. The answer is pretty simple. It is a place for Koha to do a match and replace. Koha replaces the ‘%s’ with the userid field that was in the <mapping> tag.


I hope this has helped more than it has confused. I know it was a very long explanation, and I have probably omitted something. Please feel free to leave any questions in the comments, and I will answer them to the best of my ability.

Good Luck!

[Originally posted by Elliott Davis]

Leave a comment

Your email address will not be published. Required fields are marked *

Are you human? * Time limit is exhausted. Please reload CAPTCHA.

11 thoughts on “Koha, LDAP, And You!

  • Harold

    I’ve set up my LDAP and configured koha-conf-xml in my server but upon testing I got the following error:

    Can’t call method “bind” on an undefined value LDAP line 111, line 747.

    please help.
    Thanks in advance 🙂

  • Larry Baerveldt

    Typically that error means the Koha server cannot make a connection with the LDAP server. The problem could be in several places; something in the settings is wrong, the bind user or password is incorrect, or it could the ldap server itself. It may be behind a firewall that is blocking your access from the Koha server.

    We have used a Linux command line tool called ldapsearch to test ldap connections. You might start with that because the output is more informative, to try and confirm if your ldap settings are correct and that you can connect to the ldap server. Once that’s working, then you can adjust the settings in koha_conf.xml as needed.

    You might also want to ask for help in one of the Koha Community mailing lists, listed here http://koha-community.org/support/koha-mailing-lists/, or in the #koha IRC channel.


  • Michael

    Hi, thanks for the great instruction. I have configured my Koha authenticated with Active Directory, just wonder whether it is possible to allow Koha to categories users based on different Active Directory attribute? i.e if employeType is staff then this user will be put into staff category, likewise students will be put into students category. Thanks.

    • Larry Baerveldt


      Yes and no. Yes, you can basically map any LDAP field to any Koha field, so you can map something like employeeType to categorycode. But Koha cannot “parse” or do a translation on any of the field mappings from LDAP to Koha. There has to be an exact one-to-one mapping, on the entire LDAP field. And in this specific example, the categorycode field in Koha is case-sensitive. So, if your employeeType field = ‘Staff’ but your patron categorycode in Koha is ‘STAFF’, it won’t match up.

      Similarly, if the field you want to map is something like “CN=Nancy,OU=Staff,OU=Library,DC=domain,DC=edu”, you can’t extract the OU part to get the ‘STAFF’ categorycode. The mapping is on the entire field, exactly as given.

      I hope this helps.

  • Reza

    I want to configure LDAP in koha but I’ve two different AD Server. Is there any way that koha integrate with two AD at the same time?

    Thank You

    • Larry Baerveldt


      It should be possible to list two LDAP servers in the field, separated by a comma. For example:


      We’ve never tried this, but a perusal of the code implies it will work. If this does work, please note that Koha will always use the first server listed, unless it is unavailable, then it will use the second.

      Note that this assumes both ldap servers have identical user databases. If the situation is that some users are on ldap1 and others are in ldap2, it’s not going to work. Koha will always just search ldap1 (unless it is unreachable), and the users in ldap2 will not get authenticated.


      • Michael

        I have 8 domain controllers, all of them are running as cluster designed by Microsoft. So I am using ldap://doaminname, such as ldap://nottingham.edu.cn, then system will pick one domain controller randomly. Hope this is helpful.

  • Adrian

    I got Koha to bind to OpenLDAP and works just fine. I was wondering however, if there is any for Koha to update LDAP?
    We would like to try using the Koha patrons database to modify and add users in the LDAP directory.

    • Jesse Weaver


      Koha’s LDAP implementation is, at this time, one-way. There aren’t any provisions to update the LDAP server when a patron’s record is changed in Koha. This would be an excellent enhancement, though; I’d encourage you to submit it as a bug!