Ready to Learn?Ex Libris products all provide open APIs

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 a single-sign-on, Alma can be configured for SAML single sign out with an external system. 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 requests the IDP to log you out of the external system. In a typical implementation, you are automatically logged out of the external system. Alternatively, the external system can present you with the option to log out from it (and may offer you to log out of additional systems).

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

  1. Gather information from your identity provider
  2. Provide information to your identity provider
  3. Set up a SAML integration profile in Alma
  4. Check the Alma users
  5. Use it!


Gathering information from your identity provider

  1. IDP metadata file
    The IDP metadata file can be supplied as a link, or as a xml fiel that will be uploaded to Alma.
    This file should include the following information:
    - IdP issuer
    - IdP login URL
    -IdP single logout service
    - Certificate
    Important: As of January 1, 2017, Alma will no longer support certificates using the MD5withRSA encryption algorithm. For more information, see here.
  2. 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 uniquly identify the user.
  3. IdP single logout policy
    The IDP should give 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:

  1. Alma metadata file

As of the Alma November 2016 release, Alma uses a signed certificate (Expiration date: 02 ‎October ‎2019, Signed by: DigiCert, Signature algorithm: sha256RSA, key size: RSA 2048).
Give the following link of the Alma metadata file to the IDP: {Alma domain}/view/saml/metadata.

It is also possible to generate the Alma metadata file using the "Generate Metadata file" button on the SAML integration profile:

Note that for existing SAML integration profiles, it is also possible to use the following versions of Alma metadata file:

  • Version 2 (Expiration date: 01 ‎July ‎2114, Self Signed, Signature algorithm: sha1RSA, key size: RSA 2048)
  • Version 1 (Expiration date: 07 ‎April ‎2023, Self Signed, Signature algorithm: sha1RSA, key size: RSA 3072) - Deprecated
  1. Alma's expected assertion
    Share the example SAML assertion 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
  2. 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

To authenticate users using SAML, an external integration profile of 'SAML' type must be defined. Institutions usually have a single IDP, hence a single SAML integration profile should be defined. In case the institution works with more than a single IDP, an integration profile should be defined for each IDP. Only one of them can be defined as the default. This should be the integration profile of the IDP that is used for authenticating the largest group of users.
  1. Give information from the IDP metadata file
    The IDP metadata file might be supplied as a link, or as a xml file.
    As of the November 2016 release, Alma will automatically fill 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 SAML integration profile fields:
    IDP metadata file fieldAlma SAML integration profile field
    entityID attributeIDP issuer
    SingleSignOnService field (of HTTP redirect type), Location attributeIDP Login URL
    singleLogoutService (of HTTP redirect type)IDP Single Logout Service
    X509Certificate (first occurance)Certificate
  2. 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:NameID SPNameQualifier=""Format="urn:oasis:names:tc:SAML:2.0:nameidformat:uri">73b393827e543cc2d8abe6f0c3df889f835b7e43</saml:NameID>
    <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 Name="telephoneNumber"NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:uri">
    <saml:AttributeValue xsi:type="xs:string">12345</saml:AttributeValue>
    If the telephoneNumber is used as a matching point, the SAML integration profile definitions should be as follows:

    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:

  3. 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 automatically be filled 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.

Checking the Alma users

The users that are authenticated by the IDP should exist also in Alma. They will usually be defined as external, as their information usually exists as part of the IDP and is synchronized in Alma on a regular basis.
These users in Alma MUST have an identifier, unique cross institution, that holds the information that was defined as a match point. This is in order to find them in Alma, after they were authenticated in the IDP.
In order to have that identifier, you need to make sure that during import and synchronization from the SIS system, the users have this identifier. See SIS for more details.

Using SAML authentication

The user logs in to Alma using the regular login URL, with "/SAML" suffix.
For example:
In case there is more then one SAML integration profile, the default profile is the one that will be used by the "/SAML" URL. In order to login using a different integration profile, its code should be specified explicitly in the URL:{specific SAML integration profile code}