SAML

Contents

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 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 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
    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 uniquely identifies 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.
Example: https://na01.alma.exlibrisgroup.com/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 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
  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 dataOne 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:

  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.

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, as their information exists as part of the IDP.

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 Alma to create and update users on-the-fly, based on their information in the IDP: After a user is authenticated by the IDP, Alma checks 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 ‘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

The user logs in to Alma using the regular login URL, with “/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 different integration profile, its code should be specified explicitly in the URL: https://alma.exlibrisgroup.com/institution/INST_CODE/SAML/idpCode/{specific SAML integration profile code}

XML Samples