[Koha] moving from local IP to OpenAthens SSO access - Koha users

[David Cook]

Hi Jeff,

Joel has broken things down overall pretty well here. I'll step you through a little example.

- Koha connects to Microsoft Entra ID using OpenID Connect
- OpenAthens connects to Microsoft Entra ID using OpenID Connect (or whatever protocol but this one is the easiest to setup)
- Koha contains catalogue records with OpenAthens links

- User clicks a "Microsoft Login" button on Koha, they're redirected to Microsoft Entra ID, they login, they're redirected back to Koha as an authenticated user
- User does some searching in Koha and click on an OpenAthens link. OpenAthens redirects them to Microsoft Entra ID. Microsoft Entra ID recognizes they're already logged in (so the user doesn't need to log in again), and redirects back to OpenAthens as an authenticated user
- User does further work in Koha or OpenAthens and they don't involve Microsoft Entra ID anymore, since they're now logged into these apps. 

I would recommend using OpenID Connect as your SSO protocol, as it's easy to setup and very effective. In new versions of Koha, you can set it up largely on your own. The only thing you need your Koha provider to do is restart your Koha instance after you put in the configuration. 

--

One of my Koha libraries actually has a more advanced setup. They wanted to use SSO with Koha and OpenAthens, but they didn't have an Identity Provider like Microsoft Entra ID. So what we did is we hosted the open source Identity Provider Keycloak for them, and we built an extension that lets Keycloak use Koha's user store as its user database. We then hooked Koha and OpenAthens up to Keycloak using OpenID Connect, so they got SSO while being able to manage everything in Koha and users got to keep their existing passwords. 

--

Overall, it's not a particularly complicated process. IT people might try to scare you about it, but if the technical people know what they're doing - it's very simple. Using SAML instead of OpenID Connect does take more work to setup because the Koha and the Identity Provider (and the OpenAthens and the Identity Provider) needs to produce a signed metadata file to exchange, and Koha needs additional server-side config, but it's the same SSO concept at the end of the day, so same end user user experience.

Anyway, hope that helps!

David Cook
Senior Software Engineer
Prosentient Systems
Suite 7.03
6a Glen St
Milsons Point NSW 2061
Australia

Office: 02 9212 0899

-----Original Message-----

Date: Wed, 2 Jul 2025 15:15:51 -0500
From: "Coehoorn, Joel" <jcoehoorn at york.edu>
To: Jeffrey Gabel <jeff.gabel at brooklaw.edu>
Cc: Koha Community Mailing List <koha at lists.katipo.co.nz>,
	"koha-us at koha-us.org" <koha-us at koha-us.org>
Subject: Re: [Koha] moving from local IP to OpenAthens SSO access -
	Koha	users
Message-ID:
	<CAMSeE4aBJ0mpD+qNkOw4hsTH7i-fJ3hpTHnX7Gaa6=gqLyy_Og at mail.gmail.com>
Content-Type: text/plain; charset="UTF-8"

For this to work, you should **already** have functional SSO in your organization, usually including between Koha and a primary identity provider, such as MS Active Directory, Google, MS Azure/Entra, or an open provider of some sort (usually some flavor of LDAP). This might be provided by something like Okta, Duo, AD FS, MS Entra Enterprise Applications, or some other SAML or SAS (or even OAuth) service.

OpenAthens then uses your existing SSO service to simplify connecting to licensed academic services: things like discovery, journals, serial articles, academic search, etc. You only need to set up the **one** connection between your SSO service and OpenAthens, and then OpenAthens has already done the hard work to know how to federate this with anyone else you might need. This allowed us, for example, to retire an old and insecure EZProxy service for students to get remote access to our licensed digital collections. But you need to have the initial SSO going first.

Note Koha does *not* necessarily need to participate in this process at all. In this scheme, Koha is just one more application, and OpenAthens is another. Both depend on your SSO connection to an identity provider separate from each other.

We used to have students connect to Koha via a SAML SSO connection, and this connection still works, but today students here interact with our catalog entirely via the EBSCO Discovery platform. The authentication path between EBSCO and our network is EBSCO => OpenAthens => AD FS (SAML) SSO => MS Active Directory. Eventually it will be EBSCO => OpenAthens => MS Entra Enterprise Application => MS Entra/Azure AD, but that's still a ways off.
The main thing is neither case ever involves our Koha installation.

But that's the student view. Library staff still directly use Koha for circulation and cataloguing. They authenticate to Koha via SSO, which is Koha => AD FS (SAML) SSO => MS Active Directory. (And the setup between Koha and AD FS was **not** simple or trivial, let me tell you). But again:
this is optional. We could give library staff direct accounts/credentials within Koha, and skip the SSO here.

The point is: you want existing separate SSO infrastructure before starting with OpenAthens. Then Koha can participate as a service provider/relying party to use account infrastructure and credentials kept elsewhere. This is also useful for getting MFA working, which makes the GLBA people happy. But I'm not sure I've ever seen it act as an identity provider, and its participation with an OpenAthens integration is a separate thing. I don't see it as part of the flow between your identity provider and OpenAthens, or between OpenAthens and other applications. If you're wanting to use existing accounts (and credentials) in Koha as an Identity Provider (IdP), it may be possible but I've not heard of anyone attempting it.

*Joel Coehoorn*
Director of Information Technology
*York University*
Office: 402-363-5603 | jcoehoorn at york.edu | york.edu