Koha, LDAP, And You!

by ByWater Staff on Jul 9, 2012

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:

<useldapserver>0</useldapserver>

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">

  <hostname>localhost</hostname>

  <base>dc=metavore,dc=com</base>

  <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>

  </mapping>

 </ldapserver>

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):

~/koha-dev/var/log/koha-opac-error_log
~/koha-dev/var/log/koha-error_log
/var/log/apache2/error.log

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.

Closing

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]