Koha is a free library software that we use at our school. We use it to manage both our teaching materials and our school library. Previously we used LITTERA for this, but since last summer we have switched completely to Koha. The core of our school infrastructure is a linuxmuster.net school server. Every student and colleague has an internal username, which is needed to log in at our school computers. linuxmuster.net has a LDAP server for this purpose. In this article I would like to show you how to set up a LDAP connection in Koha, so that all users can log in to the library system with their internal school login.

Connect Koha to Active Directory / AD (linuxmuster.net v7)

Linuxmuster.net v7 comes with a Samba 4 Active Directory. This has also changed the connection to Koha compared to the previous version. The settings are still in /etc/koha/sites/library/koha-conf.xml (if the Koha instance is called library). We need to edit this file as follows:

<ldapserver id="ldapserver" listenref="ldapserver">
  <hostname>ldaps://10.0.0.1</hostname>
  <base>ou=schools,dc=linuxpattern,dc=net</base>
  <user>cn=global-binduser,ou=management,ou=GLOBAL,dc=linuxmuster,dc=net</user><!-- DN, if not anonymous -->
  <pass>Bind user password</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 -->
  <anonymous_bind>0</anonymous_bind>
  <auth_by_bind>1</auth_by_bind> <!-- set to 1 to authenticate by binding instead of password comparison -->
  <principal_name>%[email protected]</principal_name>
  <update_password>0</update_password>
  <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 -->
    <userid is="samAccountName"></userid>
    <email is="mail"></email>
  </mapping>
</ldapserver>

A few short hints:

• <hostname>: Here we have to enter the address of the LDAP server (the linuxmuster.net v7 server). We also need to make sure that our Koha server can reach the LDAP server through the ports (TCP/UDP 636) for LDAPS.
• <base>: The LDAP path for our user accounts. The domain at the end will probably need to be adjusted.
• <user>: the bind-user, so that Koha can access the user data in AD.
• <pass>: The password of the Bind-User. It can be found on the linuxmuster.net server at /etc/linuxmuster/.secret/global-binduser
• <replicate>: If a user logs in via LDAP, we want him to get a Koha account as well.
• <update>: We need this option to update users with information from LDAP if a Koha account already exists.
• <auth_by_bind>: We want to use the bind user for the logon credentials check. For Active Directory, this option must be 1.
• <principal_name>: This is probably the most difficult part. The most suitable is the userPrincipalName from AD. For linuxmuster.net v7 it is set to [email protected] (adjust domain again!). User is replaced here by %s (which again is determined by the mapping below).
• <mapping>: Here we can define which data from LDAP / AD should overwrite which attribute in Koha. Most importantly, userid is important, as this is used to replace the %s in <principal_name>. With Samba 4 / AD the mapping looks like this: <userid is=”samAccountName”></userid>

Configure Koha LDAP connection (linuxmuster.net v6.2)

Koha saves its settings in the file koha-conf. xml. This file is located at /etc/koha/sites/library/koha-conf. xml, if the Koha instance is called library. We open this file with an editor of our choice and look for the entry <useldapserver>0</useldapserver>.

$ sudo nano /etc/koha/sites/library/koha-conf.xml

The documentation for the Koha LDAP connection is not very detailed. The essential information can be found in the Perl documentation on the Koha LDAP module. On this page you will find an example configuration, which we can mostly use. A few small changes are necessary to make the integration between linuxmuster.net and Koha work fine. First we change <useldapserver>0</useldapserver> to <useldapserver>1</useldapserver> to inform Koha that we want to use an LDAP server for the login. Immediately afterwards we insert the following lines:

 <ldapserver id="ldapserver"  listenref="ldapserver">
  <hostname>ldaps://10.16.1.1</hostname>
  <base>ou=Accounts,dc=linuxmuster,dc=net</base>
  <user>cn=admin,dc=linuxmuster,dc=net</user><!-- DN, if not anonymous -->
  <pass>Bind-User-Passwort</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 A$
  <principal_name>uid=%s,ou=Accounts,dc=linuxmuster,dc=net</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 -->
   <userid       is="uid"></userid>
   <password     is="userpassword"></password>
   <email        is="mail"></email>
  </mapping>
</ldapserver>

A few short hints:

• <hostname>: Here we have to specify the address of the LDAP server (the linuxmuster. net server). Furthermore, we have to make sure that our Koha server can also reach the LDAP server via the ports (TCP/UDP 636) for LDAPS.
• <base>: The LDAP path for our user accounts. The domain at the end probably needs to be adjusted.
• <user>: the bind-user, so that Koha can access the user data.
• <pass>: The password of the bind user. It is located on the linuxmuster. net server at /etc/ldap/ldap. secret
• <replicate>: When a user logs in via LDAP, we want him/her to have a Koha account.
• <update>: We need this option to update users with information from LDAP if a coha account already exists.
• <auth_by_bind>: To check the logon data we want to use the bind-user.
• <mapping>: Here we can define which data from the LDAP should overwrite which attribute in Koha. Especially important is userid and password.

Test Koha LDAP connection

To test the LDAP connection, we call the Koha OPAC page and log in with a linuxmuster. net user account. If there are problems loading the website or if you can’t log in, you can check the Koha server at /var/log/koha/library/opac-error. log for the reason.

If the login was successful, you will see a list of the user’s current borrowings:

Test Koha LDAP / AD connection via command line

Especially when setting up the connection to the LDAP / AD server it is faster if you can test directly on the command line if the configuration is correct. To do this, enter the following commands:

$ service koha-common restart && service memcached restart
$ export PERL5LIB=/usr/share/koha/lib/ && export KOHA_CONF=/etc/koha/sites/library/koha-conf.xml && perl /usr/share/koha/opac/cgi-bin/opac/opac-user.pl userid=user1 password=foo

Make sure to adapt the path to the koha-conf.xml, as well as user and password.

Conclusion

The LDAP connection in Koha is a big win for our users. Previously, with LITERRA it was not possible for individual users to see their current loans. Furthermore, the user data now only have to be maintained in one place and not in different programs. Operation via a web interface is a great benefit for all library staff and simplifies their work. Getting started in Koha may be a bit steeper than other library programs, but the possibilities and flexibility of this open source software are impressive!