SAML

Ex Libris Developer Network Alma Documentation Integrations Users in Alma Authentication Institutional IDP SAML

SAML Authentication: Introduction
Gathering information from your identity provider
Providing information to your identity provider
Setting up a SAML integration profile in Alma
Checking Alma users
Using SAML authentication
XML Samples

SAML Authentication: Introduction

Alma supports the SAML 2.0 Web Browser SSO profile. This enables Alma to exchange authentication and authorization information with your institutional Identity Provider (IDP), allowing a single sign-on for the institution’s users:
When the user attempts to log in to Alma, Alma redirects to the IDP and sends an authentication request. The IDP performs a single-sign-on check, and if the user is not logged in to the IDP, a login page is displayed (this is not the Alma login page, but the IDP login screen). After the user logs in, the IDP redirects back to Alma with a SAML response, including an assertion. Alma retrieves the user based on the SAML response and logs the user in.

The SAML authentication workflow is illustrated in the following diagram:

In addition to single-sign-on, Alma can be configured for SAML single-sign-out. This enables a user to log out of the external system and be automatically logged out of Alma, or vice versa:
When you log out of Alma, Alma sends a request to the IDP to log you out of all other systems. The IDP may present you with the option to log out from all or from specific applications.

To configure SAML settings for single-sign-on (and optionally, single-sign-out) between Alma and your IDP:

Collect information from your IDP
Provide information to your IDP
Set up a SAML integration profile in Alma
Test the login process with a user or two

Gathering information from your identity provider

IDP metadata file – The IDP metadata file can be supplied as a link, or as an XML file that will be uploaded to Alma.
This file should include the following information:
– IdP issuer
– IdP login URL
– IdP single logout service
– Certificate
Note: As of January 1, 2017, Alma will no longer support certificates using the MD5withRSA encryption algorithm. For more information, see here.
IDP user data – One of the user-related details that are returned by the IDP should be used as a matching point in Alma. The IDP returns an assertion with two parts:
– a subject part that includes a NameID or NameIdentifier element
– an attribute part that includes a list of user-related attributes (phoneNumber, mailAddress, and so forth)
You need to decide which of the user-related details (the NameID element, or one of the attributes) will be used as a match point. It should be a value that uniquely identifies the user.
IdP single logout policy – The IDP should supply information if single logout is supported and if single logout requests should be signed.

Providing information to your identity provider

The following information should be given to the IDP:

Alma metadata file

From the “Alma metadata file version” dropdown select if to use a self-signed certificate or a certificate signed by DigiCert.
You can then click on the “Generate Metadata File” button to download the file or get a link pointing to it:

From time to time, Ex Libris will add new certificates to the drop-down (while keeping backward compatibility for the expired certificates). If you like to switch to a new certificate, note that the drop-down will show only the current certificate used by the profile and a newer one (if exists). Once you select a new one you cannot return to an expired certificate.

New! (for Alma July 2023 release): You can point to the metadata file which is configured at a specific integration profile using a link such as:

https://your.lib.alma.exlibrisgroup.com/view/saml/metadata?institution={institution-code}&idpCode={code you gave the integration profile}

Alma’s expected assertion – Share the SAML assertion sample with your identity provider so they can determine the format Alma requires for successful single sign-on.
Note that the IDP assertion response should include the following fields:
Audience – should match the entityID of the metadata file
Recipient – should match the AssertionConsumerService location of the metadata file
IDP-initiated login information – In order to enable IDP-initiated login, the IDP must generate and send the ‘Relay state’ parameter:
For normal Alma login: mng@@<institution_code>
For Leganto login: leganto@@<institution_code>

Setting up a SAML integration profile in Alma

Institutions usually have a single IDP, hence a single SAML integration profile should be sufficient. In case the institution works with more than one IDP, an integration profile should be defined for each IDP. Only one of them can be defined as the default. Typically that would be the integration profile of the IDP that is used by the largest group of users.

Information from the IDP metadata file – The IDP metadata file might be supplied as a link, or as an XML file.
Alma will automatically fill in the following information according to the IDP metadata file:
– IdP issuer
– IdP login URL
– IdP single logout service
– Certificate
Following is the mapping between the IDP metadata file fields, and the Integration Profile fields:

IDP metadata file field	Alma SAML integration profile field
entityID attribute	IDP issuer
SingleSignOnService field (of HTTP redirect type), Location attribute	IDP Login URL
singleLogoutService (of HTTP redirect type)	IDP Single Logout Service
X509Certificate (first occurrence)	Certificate

Define the match point of user data – One of the user-related details that are returned by the IDP should be used as a matching point in Alma. The user match identifier may be located in the NameID element, or in one of the user attributes. For example, the IDP can return the following assertion:
```
<saml:Assertion>
  <saml:Subject>
    <saml:NameID 
      SPNameQualifier="https://eu.alma.exlibrisgroup.com/mng/login"Format="urn:oasis:names:tc:SAML:2.0:nameidformat:uri">73b393827e543cc2d8abe6f0c3df889f835b7e43</saml:NameID>
  </saml:Subject>
  <saml:AttributeStatement>
    <saml:Attribute Name="cn"NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:uri">
      <saml:AttributeValue xsi:type="xs:string">Becky Orange </saml:AttributeValue>
    </saml:Attribute>
    <saml:Attribute Name="telephoneNumber"NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:uri">
      <saml:AttributeValue xsi:type="xs:string">12345</saml:AttributeValue>
    </saml:Attribute>
  </saml:AttributeStatement>
</saml:Assertion>
```
If the telephoneNumber is used as a matching point, the SAML integration profile definitions should be as follows:

A similar setup should be defined for using a different user attribute.
If the NameID is used as a matching point, the SAML integration profile definitions should be as follows:
Upload the IDP certificate file

The IDP certificate can be uploaded to Alma in 3 ways (as of the November 2016 release):

Certificate file
JKS file
Free-text certificate

If the IDP metadata file was uploaded to Alma, the certificate part will be automatically filled in according to it.

If you received a *.cer or *.crt file from the IDP, choose “Certificate file” and upload it.
The “JKS file” option should be used in case you have a chain of trust.

For more information about the integration profile, see Alma OLH.

Checking the Alma users

The users that are authenticated by the IDP should exist also in Alma. They will usually be defined as External Users.

There are 2 ways to create and update these users in Alma:

SIS import and synchronization

Users will be created in Alma using a job that will synchronize them on a regular basis. As part of this job, you need to make sure that all users have the match point identifier. See SIS for more details.

SAML JIT (Just In Time) user creation

It is possible to configure the SAML Integration Profile to create (and optionally update) users on-the-fly, based on their information in the IDP: After a user is authenticated by the IDP, Alma will check if the user exists in Alma, based on the defined match point.

If the user does not exist in Alma, and the integration profile was configured to support user creation – the user will be created in Alma.

If the user exists in Alma, and the integration profile was configured to support ‘Update user update upon login’ – the user information in Alma will be updated.

For more information about the integration profile, see Alma’s OLH.

For details about configuring SAML JIT see this blog post.

Using SAML authentication

User login to Alma using the regular login URL, with the addition of “/SAML” suffix. For example: https://alma.exlibrisgroup.com/institution/INST_CODE/SAML.
When there is more than one SAML integration profile, the default profile will be used. In order to log in using a specific profile, its code should be added: https://…/institution/INST_CODE/SAML/idpCode/{specific SAML integration profile code}

Replacing Alma’s Certificate

SAML SSO usually works even with expired certificates. Still, Ex Libris makes sure that up-to-date certificates are added, so customers who wish to can update a certificate before it expires.

From the “Alma metadata file version” dropdown select a new certificate. You can then click on the “Generate Metadata File” button to download the file (or get a link pointing to it). The Metadata should be uploaded to the IDP.

To avoid downtime, the changes in Alma and in the IDP should be done at the same time! Coordinate with your IT the exact time the change is done in Alma and the IDP.

If you would like to change the certificate without coordinating the process, the following flow is possible starting Alma Aug 2023 Release:

1. Click on “Add additional certificate”. Another dropdown appears where you can choose the new certificate. Save.
2. Generate a metadata file (which will include both certificates) and upload it to the IDP.
3. Remove the old certificate from Alma. Save.
4. Again, generate the metadata from Alma (which will now include only the new certificate) and upload it to the IDP.

Each step can be done at a time convenient to you (just make sure to remove the old certificate before it expires).