SAML
Contents
- SAML Authentication: Introduction
- Gathering information from your identity provider
- Providing information to your identity provider
- Setting up a SAML integration profile in Alma
- Authenticating users
- Using SAML authentication
- XML Samples
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
- 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.
- Sign login/logout requests – Some IDPs require that the requests received from the the SP are signed. It is possible to configure the integration profile to sign either the login request, the logout request, none, or both. It is also possible to configure which algorithm to use for the hash being signed.
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.
You can link to the metadata file (that is configured at a specific integration profile) by:
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.
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:
1. Select the “Add additional certificate” button. Another dropdown is displayed enabling you to select the new certificate. Select Save.
2. Generate a metadata file (that includes both certificates) and upload it to the IDP.
3. Remove the old certificate from Alma and select Save.
4. Again, generate the metadata from Alma (that now includes 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).