SAML

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

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

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
   Note: 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 supply information if single logout is supported.
4. 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:

1. 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}

2. 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
3. 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>

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.

1. 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

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: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 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.

Replacing Alma’s Certificate

• Authentication Request Example
  
• Assertion Example
• Encrypted Assertion Example