How to authenticate library patrons on EZproxy using Koha’s patrons database

In many parts of the world, it is cliche to claim that Koha is a widely used Library Management System. The system is so good at its work that almost everyone this side of the world who wants to automate their library ends up with Koha. Adoption of Koha in many parts of the world has been fuelled by the fact that it is open source (free to use) and comes with most of the functions that custodians of information (librarians) need. Over time, we have experienced a growth in its usage leading to an established installed base, making it difficult for many information custodians to switch to other systems.

After the automation process, the information custodian encounters another problem. Most of the providers of online resources (E-books and E-journals) require that their use is restricted to members of the institutions that have paid subscription fees. One of the ways this is enforced is using a username and password which is often provided to the information custodian. He or she then provides it to their users whenever they need to access the online resource.

This method of controlling access is wrought with an obvious problem. Once the information custodian hands over the username and password to the user, their ability to exercise access control to the subscribed resource is lost almost entirely. This is because users will freely give out the password and username to their friends anywhere. In some cases, this information has even been shared on social media platforms such as facebook and twitter. Once the provider of online resources realizes that their resources are being accessed by unsubscribed users, the culprit subscriber is automatically blocked for misusing their account and violating terms of use.

Another more effective method that providers of online resources use is IP authentication. When you visit a website, your browser sends along with it some information to the server that hosts the website you are visiting. One of the pieces of information the browser sends is the IP address of the computer you are browsing from, OR the proxy IP if you use a proxy server to access the internet in your institution. Using the IP number, the online resource provider’s servers are able to detect the latitudes and longitudes of one’s location, the internet service provider among other information. The online resource providers who use this method require that users are located within the paying institution’s premises. This way, they can detect the user’s location and therefore authenticate them and allow them to access the resources.

This method also has an obvious problem. Not all users (such as students of a university) are always within the institution’s premises. Some are virtual (distant or online) learners while some stay off campus.

To solve the above mentioned problems, those who came before us created proxy server which sits on the subscribing institution’s premises and receives requests from users, forwards the request to the online resource provider, receives the response and forwards it back to the user who requested it. Simple, problem solved.

One of the most widely used proxy servers used by subscribing agencies today is OCLC’s EZproxy. Ezproxy supports 24 methods of authenticating users as at the time of this writing according to OCLC’s website.

Since many libraries around the world already use Koha, the purpose of this document is to demonstrate how institutions already using koha can use koha’s patron database to authenticate the same patrons on ezproxy. Of the 24 methods listed on OCLC’s website, the instructions here will be for external script using PHP, the internet’s most widely used scripting language.

Before you begin, you will need to have the following:

  1. A running EZproxy server (Instructions here)
  2. A running Koha instance (Instructions here)
  3. Administrator access level on both servers
  4. You will also need to install PHP on the server running koha using:

    sudo apt-get install php7.0 php7.0-fpm php7.0-mysql -y

    This will be used to run the PHP script that we set up in the next step.
    Now log in to your koha server and create the following PHP file with a name of your choice such as authenticate.php:

        if(isset($_POST['user']) && isset($_POST['pass'])){
            $dbhost = "localhost";
            $dbuser = "koha_db_username";
            $dbpassword = "db_password";
            $dbname = "koha_db_name";
            //TO DO: These variables are unsafe for use on a live system. Use PDO or Mysqli
            $userid = $_POST['user'];
            $password = $_POST['pass'];
            $con = mysql_connect($dbhost, $dbuser, $dbpassword) or  die("Could not connect: " . mysql_error());
            $result =  mysql_query("SELECT password FROM borrowers WHERE userid = '{$userid}' LIMIT 1;");
            while ($row = mysql_fetch_array($result)) {
                //for koha 3.13 and earlier
                $old_hash = rtrim(base64_encode(pack('H*', md5($password))), '=');
                //for koha 3.14 and later
                $new_hash = crypt($password, $row['password']);
                if( ($row['password'] === $old_hash) || ($row['password'] === $new_hash) ){
                    echo "+Success";
                }  else {
                    echo "Authentication Failed.";
        }else{ //form is not submitted
        echo "<a href=''>Go Home</a>";

    This script is not safe for use on a live system. The POST variables need to be escaped and secured from SQL injection vulnerabilities. Get a safer script using PDO from here on github.
    Place this script in a web executable path since ezproxy will access it via HTTP. To avoid editing your Apache2 configuration, place it in:


    Now if you visit http://<YOUR_KOHA_CATALOGUE_URL>/authenticate.php, you should be able to see a link with the message “Go home”, since this is not a POST request. That’s all you will need to do on your koha server.

    NEXT, you need to log in to your ezproxy server and edit the file users.txt and add the following line:


    This is it. Restart your ezproxy server and if everything went well, your koha patrons should now be able to login to your ezproxy using the same username and password that they use to log in to their koha accounts.

    This is not a Central Authentication System (CAS). For this reason, koha ptrons who are already logged-in to their koha accounts will still be asked to log-in again when accessing ezproxy.

    1. It reduces work greatly since your library staff will not be required to create new accounts for patrons since they already exist in koha with a username and password.
    2. Patrons only have one set of Username/Password for all library services.
    3. It provides a centralized platform for managing patrons account. If you need to edit a patron account, block or even delete, you can comfortably do it from koha!


Otuoma Sanya

Otuoma Sanya is a full-time systems librarian, tech enthusiast and writer. His areas of interest are data mining, institutional repositories, library automation and web development using python Django.

Leave a Reply