Setting up SingleSignOn authentication
- Introduction to Identity in RSpace
- Before starting...
- SAML-based SSO setup
- 1. Technical setup
- 2. Creating initial admin accounts
- 3. User access policy
- 4. Testing and sign-off
- 5. Using the same SSO user to access multiple RSpace accounts
This article explains how to set up SSO for RSpace using the SAML2 protocol. It applies equally to both on-premises and SaaS deployments.
Introduction to Identity in RSpace
Research data may need to be kept for decades after creation, and it's essential to be able to refer back to the person who created the work, even if that person has changed their name since.
RSpace uses a username to identify users. An RSpace username is immutable and remains eternally unique. This is so that work performed by an individual can be reliably tracked over time, in log files and exports, and is always traceable back to the same individual.
This means that an RSpace username obtained from an IdP (Identity Provider) should not be a changeable value. In many cases, the credentials used to authenticate to an IdP are mutable, so an IdP login username may not make a good RSpace username.
For this reason, we encourage the use of a unique identifer - the value of the 'eppn' attribute released by the IdP - as the RSpace username.
Setting up SSO can involve several different people at an institution with different roles, e.g. in Identity/Access Management, Data Protection/Privacy, and IdP (Identity Provider) configuration.
In our experience after performing many installations, the process is greatly smoothened if people with these different roles are aware of each other, and have the authorisation to make decisions required to make the system work.
ResearchSpace will appoint one technical contact, and one customer support contact to handle the setup.
SAML-based SSO setup
Once a running RSpace server is available, accessible from the IdP and secured by HTTPS, SSO setup can proceed. There are are four phases:
- Technical setup to connect the Identity Provider with RSpace (the Service Provider).
- Create initial RSpace admin accounts.
- Choose a policy for how users will access RSpace.
- Test and sign-off.
Step 3 can proceed independently of steps 1 and 2.
Each step is explained in more detail below.
1. Technical setup
ResearchSpace will work with customer technical contact to exchange SAML metadata and agree on URLs and SAML attribute names.
The exact details of how this is done depends on how the Identity Provider registers new Service Providers and is outside the scope of this document.
If at all possible, it's very helpful if ResearchSpace staff can troubleshoot independently. For this we either need access to a test/sandbox Idp environment or a guest account on the real IdP. If this can't be accomplished, then we will need the assistance of the customer to help verify the SAML exchange is occurring correctly.
Required SAML attributes
eppnattribute containing the user's unique, immutable ID is the only mandatory attribute required.
- For Signup Scenario 1 (self-signup), the initial user experience is enhanced if the
last namecan also be made available as SAML attributes. A user can edit these values in RSpace if they choose, either at signup time, or later in their profile page.
2. Creating initial admin accounts
Admin roles in RSpace are used to manage user accounts and configure the application. Admin roles must be created manually using the RSpace web interface.
- When RSpace is installed, an internal sysadmin user 'sysadmin1' is automatically created by RSpace. This sysadmin account is not linked to any SSO identity, but is used to 'bootstrap' the system and create an initial set of admin users that are linked to an SSO identity.
- To create a new admin account in RSpace, you need to know the unique user ID, email and name of the person. See Create New Users (for System Admins) for details. Either ResearchSpace staff or customer staff can assume the internal sysadmin role to perform this process.It's essential that the unique id (the eppn value that will be provided in a SAML assertion) is used for the RSpace username.
- Running RSpace in Standalone mode, and logged in as sysadmin1 user, create one or more organisational system admin users.
- After restarting RSpace in SSO mode, the newly created sysadmin users can login to RSpace via SSO and have full access to configure RSpace and create more users.
3. User access policy
There are two ways that end-users can start using RSpace.
Signup-scenario 1: Users self-signup
- The first time new users go to RSpace, they will be redirected to the Identity Provider's login page, and will need to authenticate.
- After authentication, users will be redirected to an RSpace signup page, pre-populated with some profile information released from the IdP, and confirming they want an account.RSpace can be configured to let users self-identify as PIs, in which case a LabGroup will automatically be set up for them. If this option is disabled, people signing up this way will just have regular user accounts, and an administrator can later convert a user account to a PI account.
- Upon signing up, the new user will go straight through to the RSpace Workspace and they will occupy 1 license seat. They can start using RSpace immediately.
- On subsequent logins, users will go straight to RSpace after authenticating with the IdP.
Signup-scenario 2: Users are white-listed by an administrator
In this scenario, anybody using RSpace must be 'white-listed' and an account set up by an RSpace administrator.
An admin can create user accounts of any type: User, PI, Community Admin or System Admin. In this approach, some initial System Admin users can be created by RSpace technical staff, to bootstrap the system. These admins can create any new user accounts they wish. When a whitelisted user tries to access RSpace, after authentication, they will go straight to the RSpace Workspace, without a sign-up page confirmation.
Which signup scenario to choose?
Scenario 1 (self-signup) is much less admin work. People sign up to RSpace without any admin involvement.
If you are concerned that people will sign up and not use the system, denying other users a license seat, these dormant accounts can later be disabled by a sysadmin, freeing up a license seat.
You can think of this approach as an 'optimistic' approach; that people will largely do the right thing, and mistakes/unintended signups can be rectified later.
Scenario 2 (white-listed signup) is a good solution if you want full control over exactly which individuals can use RSpace. This means manually creating user accounts for every user wishing to use RSpace.
It gives you total control over management of license seats. You must know, or be able to find out, the unique eppn ID for each user in order to set these as usernames for the accounts you create.
It is also possible to create multiple users by batch upload from a CSV file containing user details, or via the RSpace API.
4. Testing and sign-off
Before making RSpace generally available to end-users, the authentication flow should be tested by the customer to ensure that:
- Login and logout work as expected.
- The correct user-access policy is in place.
- At least one admin user has access to RSpace using SSO authentication.
RSpace will also confirm that the system is ready for use.
This testing phase will ensure a smooth initial experience for new users, and reduce the risk of authentication-related support requests both to ResearchSpace and the customer.
5. Using the same SSO user to access multiple RSpace accounts
We support this in a limited manner, for example if you are both an adminstrator and end-user of RSpace. Please read Setting up multiple RSpace accounts with the same SSO identity.
Glossary and acronyms
eduPersonPrincipalName: A SAML attribute containing a unique, ideally unchanging username. This may be a staff id or email address but may also be an opaque value. It is essential that this attribute is mapped to the RSpace username.
Identity Provider: is an application that issues authentication assertions, used in conjunction with a Single Sign On mechanism. The customer's institution may have its own IdP, or use a federated IdP spanning a state or country. Commercial services such as Okta can also serve as an IdP.
Security Assertion Markup Language is an open standard for exchanging authentication and authorization data between parties, in particular, between an identity provider (IdP) and a service provider (SP).
Single Sign On. Users at an institution can use the same credentials to authenticate to multiple applications.
Service Provider. An application or piece of software that accepts authentication assertions provided by an Identity Provider. Here, RSpace is the Service Provider.
RSpace user with 'System Admin' role who can create and manage user accounts, and configure RSpace global behaviour.