LDAP

Setting up LDAP (Lightweight Directory Access Protocol) for Koha allows you to store all user information in a central database which is accessed both by your organisation’s Koha instance and for users to authenticate on other existing systems.

LDAP is a protocol used for file discovery over networks and network authentication.

LDAP configurations are powerful allowing you to customise how Koha and LDAP interact. LDAP can be configured so that new accounts created in LDAP can be synced down into the Koha database, additionally updates to the LDAP user account are synced down to the Koha database.

However Koha cannot sync data up to the LDAP server, thus the data traffic when using LDAP is only one directional.

Auth_By_Bind is set to 1 where a Microsoft Windows Active Directory system is in use in the LDAP database.

Before going through the steps to configure LDAP you will need the following information/actions from the organisation

The organisation will need to open a port to allow access to their AD from the server.

Information on the access to the AD server (IP address/hostname, port, SSL info)

Information on the configuration of the AD server (relevant OUs, DCs, CN formats relative to usernames)

Mapping between AD fields and Koha fields, including defaults

Default values for things not provided by AD (categorycode, branchcode for example)

To authenticate a user do we bind as them (seems to be common for AD) or do we use an account and login with that and then check? If the latter, we’ll need details of how to log in

Do the existing usernames in Koha match the usernames that we’ll be using to look them up in AD? If so, good. If not, how will we deal with duplicate users?

Steps to set up LDAP with your Koha instance

1 In Linux terminal navigate to the directory containing the koha-conf.xml file which will either be in: * /etc/koha/sites/<instance-name>/ OR * /etc/koha/

2 Open the koha-conf.xml file with root permissions: sudo vi koha-conf.xml

3 Scroll down to the line containing ‘<useldapserver>0</useldapserver>’ and change it to: <useldapserver>1</useldapserver>

4 Then in the next line below write in the LDAP configurations below:

<ldapserver id="<ldapserverid>"> <hostname><hostname></hostname> <base>dc=<domaincontroller>,dc=<domaincontroller></base> <user>cn=<nameofuser>, dc=<domaincontroller>,dc=<domaincontroller></user> <!--This is the username of user account with permissions to query the LDAP server --> <pass><password></pass> <!-- This is password of the user account with permissions to query the LDAP server--> <replicate><either0or1></replicate> <!-- add new users from LDAP to Koha database --> <welcome><either0or1></welcome> <!-- send new users the welcome email when added via replicate --> <update><either0or1></update> <!-- update existing users in Koha database --> <auth_by_bind><either0or1></auth_by_bind> <!-- set to 1 to authenticate by binding instead of password comparison, e.g., to use Active Directory --> <principal_name><principalname></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> <!-- Athens,OH is the default value for city of all users logging into Koha --> <zipcode is="postalcode"></zipcode> <branchcode is="branch">Central</branchcode> <userid is="uid"></userid> <password is="userpassword"></password> <email is="mail"></email> <categorycode is="employeetype">EM</categorycode> <phone is="telephonenumber"></phone> </mapping> </ldapserver>

5 Save and exit the koha-conf.xml file

6 Check the LDAP connection works by writing in:

ldapsearch -H ldaps://host.name -s base -x -w “” -d 1

Note

Note about hostname Hostname can either be a alphanumerical name or it can be the LDAP server IP address (its optional to write port number). By default the ldaps default port number is 636, whilst ldap default port number is 389

Note

Note about the replicate and update fields The replicate LDAP config field for LDAP in the koha-conf.xml file allow the Koha database to be added to with a new borrower account whenever a user logs into Koha (either the staff client or OPAC) with their LDAP username and password (assuming the same username and password does not already exist in the Koha database).

Whereas the update LDAP config field (in the same file allows) allows for user information in the LDAP database to be synced down to the Koha database. e.g. if someone gets married and their surname changes then the new surname only needs to be updated in the existing LDAP database and that will be synced down to the Koha database automatically if the update configuration is set to 1.

About the mapping fields (the fields highlighted green) <city is=”l”>Athens, OH</city>

The left hand column name (highlighted yellow) is the name of the column in the LDAP database.

The column name inside quote marks (highlighted pink) is the name of the column in the Koha database. NOTE: This can be filled with any value if there is no equivalent column name in the Koha database as exists in the LDAP database.

The value highlighted cyan is the default value for the specified Koha and LDAP columns. So in the above example all user records in the Koha and LDAP databases will by default have the city value of ‘Athens, OH’.

Example of the LDAP configurations:

<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"> <hostname>ldaps://example.co.au</hostname> <base>ou=employees,dc=companya,dc=com,dc=au</base> <user></user> <!-- DN, if not anonymous --> <pass></pass> <!-- password, if not anonymous --> <auth_by_bind>1</auth_by_bind> <replicate>1</replicate> <!-- add new users from LDAP to Koha database --> <update>0</update> <!-- update existing users in Koha database --> <principal_name>ou=employees,dc=companya,dc=com,dc=au</principal_name> <mapping> <userid is="uid" ></userid> <cardnumber is="uid" ></cardnumber> <email is="mail" ></email> <surname is="sn" ></surname> <firstname is="givenname" ></firstname> <categorycode is="1">EM</categorycode> <branchcode is="1">SYD</branchcode> </mapping> </ldapserver>

The values in the mapping area are not always the same, and it depends on what is in your organisations LDAP database. For example some organisations do not use <userid> instead each user is only identified by the <email> field and so no <userid> is written.

Troubleshooting LDAP

The log that LDAP errors are printed to depends on several factors:

If plack is not disabled then LDAP errors are displayed in the plack-error.log file If plack is disabled then the location that LDAP errors are printed to is either the opac-error.log file (if the user is logging into the OPAC) or the intranet-error.log file (if the user is logging into the staff client) All of these three log files are accessible in the following directory:

/var/log/koha/<instance>/

Built with Sphinx using a theme provided by Read the Docs.