Koha and SAML

Koha supports SAML and OpenID Connect.   The following is an outline of the configuration process in integrating Koha with your IdP.

SAML Single Sign-On (SSO) for Koha enables users to authenticate using an external Identity Provider (IdP) such as Microsoft Entra ID (formerly Azure AD), Okta, Google Workspace, or ADFS. Koha acts as the Service Provider (SP), trusting the IdP to authenticate users and send identity attributes in a SAML assertion.

Configuring **SAML Single Sign-On (SSO)** for Koha enables users to authenticate using an external Identity Provider (IdP) such as Microsoft Entra ID (formerly Azure AD), Okta, Google Workspace, or ADFS. Koha acts as the **Service Provider (SP)**, trusting the IdP to authenticate users and send identity attributes in a SAML assertion.

Overview of the SAML Flow

SAML (Security Assertion Markup Language) authentication works as follows:

1. A user attempts to access Koha.
2. Koha redirects the user to the IdP.
3. The user authenticates at the IdP.
4. The IdP sends a signed SAML assertion back to Koha.
5. Koha validates the assertion and logs the user in, matching them to a local borrower account.

Setting up SAML: the Metadata Exchange Process

Metadata exchange establishes trust between Koha (SP) and the IdP.

Step A – Provide SP Metadata to the IdP

Prosentient Systems will provide a metadata file for your institution, and we will expect a metadata file or link in exchange.  This contains the:

* SP Entity ID (e.g., `https://test.intersearch.com.au`)
* ACS URL (e.g., `https://test.intersearch.com.au/your signon`)
 

This metadata is uploaded into the IdP’s “Enterprise Application” or “Service Provider” configuration section.

Step B – Import IdP Metadata into Koha

The IdP provides metadata (XML file or URL) containing:

* IdP Entity ID
* Single Sign-On URL
* Public signing certificate

This is imported into Koha’s SAML configuration so Koha can:

* Redirect users correctly
* Validate the IdP’s digital signature
* Ensure assertions are trusted

At this point, the trust relationship is established.

Step C - Configuring Claims (Attribute Mapping)

After trust is established, the IdP must send identity attributes (claims) to Koha. These attributes are embedded in the SAML assertion.

The Primary Linking Attribute is usually Email Address but also sometimes Staff ID

Most Koha implementations use **email address** as the unique identifier to match users to borrower accounts.

Typical SAML claim:

* `NameID` = email address
 or
* Attribute: `mail` or `email`

Koha is configured to:

* Match the incoming email to the borrower’s email field.
* Optionally auto-create users if not found (depending on policy).

Using email ensures uniqueness and consistency across systems.

Standard User Attributes

In addition to email, the IdP typically sends:

These can either:

* Update user records at login, or
* Be used only at initial account creation.

Optional Organisational Attributes

Additional claims can support borrower categorisation and permissions:

department   for   Faculty or branch       
physicalDeliveryOfficeName for branch or Library location
 title for  Position (e.g., Librarian, Student, Professor) 
employeeType for Staff vs Student 

memberOf forGroup-based permissions  
 

These attributes can be used to:

* Automatically assign borrower category (e.g., STAFF, STUDENT)
* Set branch/location
* Control access to staff client vs OPAC
* Drive role-based permissions

For example:

* If `employeeType = staff`, assign Koha category “STAFF”
* If `department = Health`, assign branch “HLTH”