SAML-Based Single Sign-On/Sign-Off for the Esploro Research Hub
- General System Administrator
This page describes how to work with SAML in the Esploro research hub. For a video giving a general overview of working with SAML see here. For general information on authentication in Esploro see here.
For Alma users, the authentication profiles are common between Esploro and Alma. This means that the profiles are editable both in Alma and Esploro. Therefore, changes to the authentication profile will be reflected in Alma, and the converse (from Alma to Esploro).
If you have separate certificates for Alma and Esploro, you should only use one integration profile, and configure the IDP certificates of the two products under
Esploro supports the SAML 2.0 Web Browser SSO profile. This enables Esploro to exchange authentication and authorization information, allowing a user to sign in or out of an external system and be automatically signed in or out of Esploro, or vice versa.
For a detailed overview of SAML-based SSO, see https://developers.exlibrisgroup.com/alma/integrations/user-management/authentication/inst_idp/saml.
- On the Integration Profile List page (Configuration > General > External Systems > Integration Profiles), select Add Integration Profile. The first page of the integration profile wizard appears.
- Enter a code and name for the integration profile.
- Select the SAML option from the "Integration Type" dropdown list.
- From the "System dropdown list", select the system to be used for authentication, such as 'Shibboleth'.
-
Select Next. You are taken to the next page.
Integration Profile Wizard for SAML, Second PageOn this page, enter the following information.
SAML Integration Profile page - Action tab Field Description Metadata Upload method
You can populate the profile information from metadata. To do that, select the Metadata Link option and provide the location of the link in the Metadata file link field. To use a metadata upload, select the Metadata upload option and select the file in the Upload IdP metadata file field. Metadata file link
Automatic update Select for Esploro to facilitate a rollover process by managing two IdP certificates simultaneously. This enables configuring the Integration profile to fetch the metadata when it is modified by the IdP. Enabling Automatic update will override the information in the Integration Profile every 2 hours in a similar way it is done when clicking on the "Populate Profile" button. It is recommended to test if SSO works well before applying it.
Automatically populating the profile is currently only supported for self-signing IdP certificates. If your IdP uses a chain-of-trust certificate for signing, it is required to upload a JKS file manually.
Default SAML profile
Select to configure this profile as the default.
To use a profile that is not the default, use the /SAML/idpCode/[profile code] suffix in the Esploro URL.
ForceAuthN Select to force authentication when Esploro authenticates users via SAML. For more information on SAML ForceAuthN, see here.
When this checkbox is not selected, then when Esploro authenticates users via SAML, it does so directly through the institutional IdP, thus providing end users with an SSO experience.
IdP Issuer If the profile was not automatically populated with metadata (in the above fields), enter the settings for the IdP issuer, IdP Login URL, User ID Location, User ID Attribute Name, IdP Logout URL, and IdP Single Logout Service, and Sign Single Logout Requests.
For more information on these fields, see https://developers.exlibrisgroup.com/alma/integrations/user-management/authentication/inst_idp/saml.
IdP Login URL IdP ID location User ID attribute name IdP logout URL IdP single logout service Sign single logout requests Apply SHA1 signature (Default SHA2) Select Apply SHA1 signature (Default SHA2) to change the signature of the profile to SHA1 (also called SHA128) signature, in order to sign the logout requests with this signature.
For profiles created after July 2020, the default is SHA2 (also called SHA256), but you can change that to SHA1, if needed.
For profiles existing before SHA2 was introduced in July 2020, the default is SHA1, but you can change that to SHA2, if needed.Esploro metadata file version Select an Esploro metadata file version. When creating a new profile, two options are available, the self-signed Version 20XX and Signed certificate. When editing an existing profile, three options are available, the self-signed Version 20XX, Signed certificate, and whichever certificate you were using previously. It is important to note the expiration date when choosing a certificate and make sure to replace it prior to that date If you opt to use a previous certificate, Esploro continues to accept it, even after the expiration date. If you edit an existing profile and select a new certificate, once you save the profile, the previous certificate becomes unavailable. Before changing your certificate, you must check with your IT department. IDP Certificate 1 / 2 Esploro enables holding two certificates simultaneously and tries to authenticate using both certificates. This is useful when a SAML IdP changes their certificate (for security reasons). The certificate needs to be updated on the integration profile. Holding two certificates simultaneously allows the institution to add the new certificate ahead of time, without removing the old certificate until after the IdP has made the switch. Holding only one certificate can cause downtime if the certificate is not updated at the same time on both systems, since then Esploro does not trust the response from the IdP that was signed with the "wrong" certificate.
The certificates are cyclic: adding a 3rd certificate removes the 1st certificate, and the new certificate becomes the 2nd). Uploading a second certificate is not mandatory.
This feature should also be used by customers who have both Alma and Esploro, and have different certificates for each of them. In this case, configure the Alma certificate under IDP Certificate 1 and the Esploro certificate under IDP Certificate 2.
For each certificate, in Certificate upload method, select the type of certificate to upload
(see https://developers.exlibrisgroup.com/alma/integrations/user-management/authentication/inst_idp/saml). Esploro accepts file uploads, free-text certificate entry, or JKS files. If JKS file or Free-text certificate file is selected, a field will be displayed to select the file from the user's file system. If Free-text certificate is selected, a field is displayed to accept the text of the certificate. A note beside the field indicates if a certificate has already been uploaded.As of January 1, 2017, Esploro no longer supports certificates using the MD5withRSA encryption algorithm. For more information, see https://blogs.oracle.com/java-platform-group/entry/strengthening_signatures.
Active When an authenticated SAML user logs in that does not have an existing Esploro user, if you want a new Esploro user to be automatically created, select Active in the Self Registration section. - Enter the User Group, Resource Sharing Library, and Statistical Category that you want to have assigned to the automatically created user.
- You can also define the mapping of SAML attributes to their corresponding user fields in Esploro by selecting the Mapping of assertion fields to Esploro fields link.
- Enter the Esploro field name in the Code field. Enter the SAML assertion code in the Description.
- Select Customize.
User Group Resource Sharing library Statistical Category Update user upon login Recreate user roles upon login Mapping of assertion fields to Esploro fields XSL configuration file - Select Save.
Testing Authentication on SAML Integration Profile
You can test your SAML integration directly from the SAML configuration page. This removes the need to log out from Esploro and log in again, and if the authentication fails, provides a clear indication of what went wrong.
- Once you filled in all the relevant information on the SAML integration profile, click the "Test" button. A popup window opens.
- In the popup window, select the product from the list of your institution's available products. This generates a test link to the IdP set in the integration profile.
- Copy this link and paste it to a different browser (or, if you are working with Chrome, to an Incognito tab). Your SAML login page opens.
- Submit your credentials. You are redirected to a new page showing the authentication result and additional messages explaining what went on and possibly what went wrong.
The credentials are used only for the test and do not actually log in the user whose credentials were entered here.
- Close the test window and return to Esploro. If needed, update the integration profile/IdP and test again. If no changes are necessary, save the profile.
Replacing a Signed Certificate
If you need to replace your Signed Certificate, you must do it with both Research Hub and the Portal and Profiles, in coordination with your IdP.
SAML SSO usually works even with expired certificates. Some IDPs enforce non-expired certificates (or can be configured to do so), and Ex Libris ensures that up-to-date certificates are added, enabling customers with those IDPs to update the certificate.
Send the certificate file to your IT department along with the new metadata that is produced by selecting the appropriate link below (inserting your university's base Research Hub or Portal and Profiles URL in place of <ESPLORO_HUB_OR_PORTAL_BASE_URL>):
https://<ESPLORO_HUB_OR_PORTAL_BASE_URL>/view/saml/metadata?VERSION=VERSION_2030 (2030 self signed)
https://<ESPLORO_HUB_OR_PORTAL_BASE_URL>/view/saml/metadata?VERSION=SIGNED_20240109 (Jan 2024 DigiCert)
Make note of the date and time that the IdP will switch the certificate. As close as possible to that time, follow the process detailed in Alma Metadata file version to select the new certificate in the integration profile.
When either the institution or the IdP upgrades the institution certificate, the login will not work until the other switches over as well. This is why it is important to note when the IdP is switching over to minimize the down time.
Replacing an IdP Signing Certificate
This section is relevant only if your institution holds only one certificate in the "IDP Certificate 1 / 2" sections of the integration profile. If both certificates were uploaded, then holding two certificates simultaneously allows the institution to add the new certificate ahead of time, without removing the old certificate until after the IdP has made the switch, refer to Automatic Rollover of an IdP Signing Certificate below.
If the IdP signing certificate on your Esploro SAML profile is about to change, upload the new certificate using one of the three supported methods:
- Free-text certificate,
- Certificate file,
- JKS file. JKS is required for chain of trust certificates.
Make sure to perform this change and click Save at the same time that the IdP switches over to the new certificate. Otherwise, SAML authentication will fail during the interval.
Switching to a newer signing certificate automatically, without updating the SAML profile in Esploro, might cause a system-down.
Automatic Rollover of an IdP Signing Certificate
- Verify the Integration profile is configured to update automatically and that the link is valid.
- Configure an additional certificate in the IdP.
- Wait for Esploro (and other SPs if they exist) to read the new metadata.
- Remove the old certificate from the IdP.