Koha How-To
Single Sign-On / Authentication Options for Koha
by Nick Clemens on May 8, 2019
Koha offers several options for using external authentication services to allow users to sign in. In this blog post I will list the options and cover some of the basics of using different options.
Related: Ebsco EDS/OpenAthens plugins
Basics about SSO:
The process:
For setting up any SSO there are a few things that will make the process proceed smoothly:
1 - Communication between the partner and their IT departments and direct communication between ByWater and IT
In the case of any SSO that must be setup on the Koha backend we are greatly aided by being able to directly communicate with the staff configuring the server at the partner end
2 - Test accounts
If ByWater is provided a test account that mirrors a real account as closely as possible we are able to test and debug any issues in a timely fashion. This is important both during initial setup and later troubleshooting
3 - Partner input
Many of the decisions about SSO (what fields are needed, what will be used to match accounts) are up to the partner and will need to be discussed/chosen by the relevant staff
Local sign on:
No SSO method prevents local sign on. Koha accounts can have their own username/password - if they do then SSO can be avoided. This is useful for library staff accounts who may not be in the SSO database, and allows a backup access in case there are issues in the SSO connection.
For general users it is important to prevent users from being able to set/change their koha password, otherwise they can have a direct Koha password that would allow access even if the SSO record is removed.
As of 19.05 it will be possible to allow select categories to change their password (local users) and prevent other categories from doing so (remote/SSO users)
When loading patron we suggest either blanking the password field, or filling it with a random string to prevent end users from circumventing SSO
Combining methods:
All of these options work independently, and more than one method may be enabled for any site.
Self registration:
None of the methods prevent the use of patron self registration, in the same way that local login is always allowed, if self registration is enabled users can still sign up for local accounts directly through Koha. No information will be passed to the SSO for these accounts unless an export of these accounts is setup.
Auto-provisioning / Account creation:
Several methods support creating accounts when a user exists externally but not locally in the Koha database. There are few things to note:
1 - Users will not be created until they have signed in.
Generally we recommend performing regular patrons loads so that users can circulate items without having signed in to the catalog beforehand. We do not currently harvest users from any SSO sources
2 - Users are required to have a category and branchcode set to valid system settings
Users must be assigned these values on creation - we cannot alter the data received from the SSO source so they must either have direct matches between Koha and the SSO, or be assigned to a default branch/category - usually we setup something like 'SSOUSER' so that these accounts can be identified and fully populated on the next load or by library staff
3 - Any information the library needs in these accounts must be sent by the SSO
When creating the acount we can only populate with information we are given. It is up to the library to determine the fields required and up to IT to ensure those fields are sent
Account updating:
Koha does support updating local accounts with the data retrieved from the SSO. As above, only fields passed by the SSO can be updated, and the data cannot be manipulated, it will be copied directly.
Unless there is an exact match between category/branchcode one cannot enable both auto-provisioning and auto-update - if you do then all users will be reset to the default category specified for creation upon each sign-on.
LDAP:
The basics:
LDAP allows patrons to use the built-in Koha sign in form. Users will enter their username and password - these credentials are the used to look up and match a user in the LDAP server. If an LDAP user is found we then search for a corresponding Koha user and log them in if found. If the ldap lookup fails, or the credentials don't match, the username and password are then checked against the Koha database directly and the user is signed in if the credentials are valid
Setup:
- This is done on the backed by Bywater staff in coordination with library IT
Account creation:
- Yes - see 'Auto-provisioning' section
Account update:
- Yes - see 'Auto-provisioning' section
SAML:
When SAML is enabled a new link for 'Shibboleth sign on' is added to the Koha system. Users with a SAML account will click this link, be directed to your sign on solution, and then checked against existing Koha users. Local sign on is still an option, however, we can hide or customize the login form to highlight SSO or hide local links
Setup:
- This is done on the backed by Bywater staff in coordination with library IT
Account creation:
- Yes - see 'Auto-provisioning' section
Account update:
- Yes - see 'Auto-provisioning' section
CAS:
The basics:
When CAS is enabled a new link is added to the Koha sign in form. Users with a CAS account will click this link, be directed to your sign on solution, and then checked against existing Koha users. Local sign on is still an option, however, we can hide or customize the login form to highlight SSO or hide local links
Setup:
CAS can be setup by the library directly by populating the system preferences
- casAuthentication - Yes/No to enable/disable the service
- casLogout - Yes/No to log the user out of the CAS server when they logout of Koha
- casServerUrl - A full URL to the CAS server
Account creation:
- Not supported at this time
Account update:
- Not supported at this time
Google OAuth:
The basics:
When Google OAuth is enabled a new link is added to the Koha sign in form. Users with a Google account will click this link, be directed to your sign on solution, and then checked against existing Koha users. Local sign on is still an option, however, we can hide or customize the login form to highlight SSO or hide local links
Setup:
OAuth can be setup by the library directly by populating the system preferences
- GoogleOpenIDConnect - Yes/No to enable/disable the service
- GoogleOAuth2ClientID - Find in your Google account
- GoogleOAuth2ClientSecret - Find in your Google account
- GoogleOpenIDConnectAutoRegister - Enable auto-provisioning
- GoogleOpenIDConnectDefaultBranch - Branch to use for auto-provisioning
- GoogleOpenIDConnectDefaultCategory - Category to use for auto-provisioning
- GoogleOpenIDConnectDomain - Limit users to a single google domain
Account creation:
- Yes - unlike other services, google will only populate name and email, and users must be assigned to a default branch/category supplied in the preferences as described above
Account update:
- Not supported at this time
Ebsco services:
EDS/OpenAthens both have koha plugins that support connecting the catalog to these resources. OpenAthens can allow users to sign in once and access various external databases as configured in OpenAthens. It is worth noting these here as they are often a concern for SSO solutions. OpenAthens also supports the SAML protocol as an SSO itself
Read more by Nick Clemens