Single sign-on (via SAML) is now available to Enterprise edition customers on both single and multi-tenancy systems. This guide explains how to set it up.

Introduction

Connecting Preservica to your Identity Provider using SAML is straightforward and can be done using our New Generation interface (NGI). This guide walks you through the different steps including screenshot with examples.

If you would prefer to set SAML up using APIs instead, then please see our API-specific guide.

If you encounter an issue at any point in this process, please contact support@preservica.com.

There are two key things to know about this single sign-on implementation:

Integrate your IdP’s group or role membership with Preservica roles

Roles within Preservica are controlled by group membership in your IdP so you need to ensure that group membership is being included in the SAML assertion.

Find out more in section 1.1.2.

Dedicated login page for each tenant

At the end of setting up SAML, you will be provided with a unique login URL for your Preservica tenant and you will need to instruct your SAML users to use this URL to log into Preservica. The good news is that they only have to use that URL the first time - when they come back to Preservica within the same browser, they will automatically be redirected, and they will only need to use the unique login URL if they want to switch tenant (if your Preservica edition gives you access to more than one tenancy).

If you want to use the same user to log in to multiple tenancies, create a separate Enterprise Application for each tenancy and assign the appropriate groups to each. Users will need to visit the unique login URL for each tenant when they log in.

How to set up SAML with Preservica

To start using SAML, you need to add an Enterprise Application in your SAML Identity Provider (IdP), and then configure your Preservica tenant to use that Enterprise Application. 

Step 1: Add a new Enterprise Application in your SAML IdP

You will need to create a new Enterprise Application in your IdP for each Preservica tenant (if you have multiple tenants in your Preservica instance). Depending on your organization, you may need to ask this of your IT team.

There are two parts to the setup: Authentication and Authorization (i.e. group membership).

1.1 Authentication

To set up an Enterprise Application within your IdP, you will need to provide some information about Preservica’s SAML implementation. Specifically, you will need:

EntityID = ….

Assertion Consumer Service (ACS) URL = …..

If Preservica already provided you with the Entity ID and ACS URL, you can skip to section 1.2.

Otherwise, you can get this information via your browser (where your-preservica-url needs to be replaced by your dedicated Preservica URL):

a. Log onto https://your-preservica-url/auth/login using your current non-SSO account 

b. Ignore the redirect and type the following URL in your browser: https://your-preservica-url/auth/saml/sp-metadata

c. This will download onto your computer a saml-sp-metadata.xml file that contains the entityID and the ACS URL (called Location) within the XML (see screenshot below)

d. The last part of the entityID (after /saml/sp-metadata)/ is the Tenant ID. As mentioned earlier, you will get a unique Tenant ID per tenant on your instance (if you have multiple tenants). You will use this Tenant ID to select which tenancy to log into using (for example: https://us.preservica.com/auth/login/4071c5554d12f9a190a966996c3949e8)

1.2 Authorization

When setting up your new Enterprise Application, you need to ensure that the group membership/role information is included in the SAML assertion. 

1.3 Have your IdP Metadata URL and IdP Metadata File ready

At the end of the setup, your IdP will provide a Metadata URL (also called App Federation Metadata URL) and/or a Metadata XML file which you will need to complete the setup.

Preservica can provide guides with guidance on how to configure an Azure Enterprise Application or an Okta application on demand (email support@preservica.com) but please note that your own IdP might differ.

Step 2: Configure your Preservica tenant

You will need a non-SSO account with MANAGER role to achieve this.

2.1 Navigating to the interface

1. Log in using your non-SSO Account (with MANAGER role) at this URL: https://your-preservica-url/starter/login
2. In top-right of the screen, select ‘User settings’.
3. In the left sidebar that then opens, select ‘Security Settings’.
4. Within the Security settings page, open the second tab ‘External authentication’.

2.2. Connecting this Preservica tenant to your Enterprise Application

1. Under “Authentication model” make sure that “SAML SSO” is selected.
2. Go to the “Service / identity provider” tab and under “Identity provider information” > “Metadata URL”, enter the IdP Metadata URL (also known as App Federation Metadata Url) mentioned in step 1.3. (alternatively you can also upload the IdP Metadata file).

3. Next, you need to set up your role attribute mapping. 
   Go to the “User configuration” tab and fill out the Attribute name for Role and the Attribute name for User ID in the “Basic configuration” section.
   If your IdP is configured to pass Role and User ID use the following attribute
   - Attribute name for Role: http://schemas.microsoft.com/ws/2008/06/identity/claims/groups
   - Attribute name for User ID: http://schemas.xmlsoap.org/ws/2005/05/identity/claims/upn
   If your IdP uses different attribute names, you will need to fill in these two sections with the attributes used by your IdP.

4. Next, you need to set up your Role mapping
   Click “Add user group” and add as many groups as necessary and map your IdP groups to the Preservica Roles (see end of guide for a description of the Preservica roles). 
   Please note that in IdP such as Azure ID, the value passed by the SAML assertion is not the Group name but the Group Object ID (which is a UUID).
   If you have custom content roles in your tenancy, these should also be mapped. 
   Note: If you want to Edit a Group that you've already mapped, Click "Add user group" and follow the same set-up steps. When you select "Add user group" the existing set-up will be overwritten (or edited) by this newer set-up.
   In step 3 below, we explain how you can check that the correct roles are being passed by your IdP. You can also use this list of role to validate which IdP role you need to map to Preservica roles.

5. Activate the authentication using the button at the bottom and confirm the activation in the pop-up message.
6. The setup is now complete.

If you or your IdP require Preservica to send signed SAML requests, please see Appendix 1 below for instructions to set that up.

Step 3: Confirm your SAML works

To confirm your SAML is set up correctly, please follow these steps:

1. Log in to https://your-preservica-url/auth/login/tenant_ID (the Tenant ID was mentioned in section 2.1.1) as a manager level user using your IdP credentials.

2. Ignore the redirect and type the following URL in your browser: https://your-preservica-url/auth/session

3. In the browser, you should be directed to a page like the one below, with your user details and the roles mapped to this user. Please make sure that the “roles” section contains the correct roles.

Step 4: Review your non-SSO accounts

You will still be able to log in with non-SSO accounts directly defined in Preservica’s authentication store as before. Once you are happy that your SAML connection is working properly, you may want to disable or delete most of these.

You should leave a service account for use with the APIs if you want to use them in a non-interactive environment, as SAML relies on the user logging in through the browser, so it isn’t suitable for background API actions. Of course you should keep the credentials for that service user safe, and only give it the roles it needs to do the work you want to use it for. (Do not create a Manager level service account if you do not need to do management actions via API.). The SERVICE role allows you to restrict login ability for any non-SSO accounts which you need to keep to use with APIs.

Depending on the agreement you have with Preservica, we may also create service accounts in your tenancy to help you with support issues or to investigate operational issues. Access to these accounts is tightly controlled, in line with our security requirements.

Appendix 1: Requiring SAML requests from Preservica to be signed

If you require SAML requests from Preservica to be signed, you can follow the instructions below to provide this certificate and configure it using our APIs.

Step 1: Upload certificate

• Using the POST API endpoint at /api/auth/certificates/ it is now possible to add and store a certificate. The format of the body posted with the request needs to be e.g.:

  {
  "name" : "signing certificate",
  "certificate" : "MIIC3TC...KU=",
  "privateKey" : "MIICeAIBA...Yde3"
  }

Before submitting this, make sure you are aware of the private key, as by design it will not be retrievable at any point after this. When the endpoint has been used successfully, the response will include the above same 3 parameters, along with a unique id, except that the returned privateKey value will just be “true” to reflect that the private key is stored, but will not expose it. These same details can also be returned by using the equivalent GET /api/auth/certificates/ endpoint.

Step 2: Configure your SAML settings to require the certificate

In order to configure the SAML configuration to require (and use) these signed certificates, amend your auth_configuration via the API endpoint PUT /api/auth/configuration/, in the following way:

• Within the auth configuration (obtained from GET /api/auth/configuration/ is a section called samlParameters. Within this, a new parameter “signedRequests” can be added - the format of this addition should be:

  "signedRequests": { "sign": true, "certificate": <<apiId>> }

• The above “<<apiID>>” corresponds to the ID of the certificate you wish to use when it is retrieved from the GET /api/auth/certificates/ endpoint.

• Sending the PUT request to /api/auth/configuration/ with the new signedRequests section will mean that any new authentication request sent to the identity provider will send the stated certificate as part of it.

• Finally, you or your IT team can then configure your SAML IdP to look for this certificate as proof that the request has come from the trusted Preservica source.

Appendix 2: Preservica roles you can assign via IdP

You can assign any custom or content roles you’ve created yourself. 

The full list of Preservica’s functional roles that can be mapped to your IdP are:

ACCESS - This role allows a user to browse and retrieve files and DIPs.

ANONYMOUS - This role is used by the Universal Access application and Portal to control the content and metadata shown to unauthenticated users. It doesn’t have any functional permissions in the application. 

DATA MANAGEMENT - This role grants a user access to the data management workflow system in Preservica, which allows a user to re-index, re-characterise, appraise, delete, and generally manage the archive’s content. 

INGEST - This role grants a user access to the ingest workflows system in Preservica. This allows them to submit data to the archive. 

MANAGER - This grants a user access to the archive administration functionalities of the Preservica application, and full access to the Job Queue and Explorer applications. Caution should be exercised in granting this role. An unwitting or malicious user with manager privileges could cause serious damage to the archive’s data. 

TRANSFORM - This grants a user access to the transformation workflows system in Preservica. This allows them to create and schedule format migrations, creating new accessions both for archival and for testing purposes.

Frequently Asked Questions (FAQs) about SSO in Preservica

Q: We are investigating using SSO and we are wondering how this would work for us as our email address currently determines which environment (prod or test) is accessed from the same end point?

A: You'll need to configure the IDP to send users back to a different assertion consumer URL. Normally that would be setting up two different Enterprise apps within the IDP. Your users will then need to access the right login page for the tenant they want to access (prod or test) as per the introduction section of the above guide.

Q: As an on-premise customer, can we still give our users the ADMIN role through this new SSO set-up?

As long as the admin role is specified in your local.properties file (‘authentication.allow.admin.role’), you should then be able to map it to your IdP groups. (The admin role is only available to on-premise customers who need to manage their configuration of Preservica; for cloud customers the highest-privilege role is the Manager role.)

Q: On a user’s ‘Profile’ page, there is a “Change password” button which is available to all users, even those signing in with SSO. What happens if they try to change the password?

A: Users need to have a current password to be able to change it so SSO users won’t be able to use this button. Thank you for the feedback, we will look to remove this button for SSO users in a future version of Preservica.