How to configure SSO on the Portal
Single Sign-On (SSO) is a type of authentication service that allows users to log in to various connected applications with only one set of credentials (usually their username/organization email and password). This simplifies the login process for users, as they don't need to create multiple accounts and manage different sets of credentials.
SSO also makes it easier for account administrators to manage user access and permissions from a single source of truth, and for organizations to comply with regulatory requirements.
Spectra Assure Portal can integrate with SSO solutions that support the OpenID Connect (OIDC) protocol. Organization administrators can enable and disable SSO login on the Portal, as well as configure their preferred SSO method. The configuration maps user SSO information set in the identity provider to groups and roles on the Portal.
This guide is for organization administrators who want to enable and configure SSO on their Portal instance.
SSO login workflow
When SSO is configured on a Portal instance, the login workflow changes from the default (local login) to the following:
The user selects the "Log in with SSO" option on the login page.
OIDC redirects the user to the identity provider (IdP) to determine their identity. This is done by checking for an active session. If the user is not logged in to their account on the identity provider side, they will be asked to authenticate.
When the IdP authenticates the user, it redirects them back to the Portal.
Using the information from the IdP, the Portal confirms the user's identity and assigns configured roles to the user. The roles remain active during the user's session. If no organization roles are mapped to the user, they will be denied access to the Portal.
Before you start
Carefully consider the information in this section before you configure SSO on your Portal instance.
Requirements and limitations
| Active SSO settings | Only one SSO integration can be configured at a time on a Portal instance. |
| Groups | At least one SSO group must be assigned to the "Organization Administrator" role on the Portal. There is no upper limit to the amount of groups that can be configured. Nested groups are not supported. |
| MFA | MFA (multi-factor authentication) is not supported on the Portal side, but can be enforced by the identity provider (IdP). |
| User sessions | By default, user sessions expire after 2 weeks, but session duration and expiration can be configured differently by ReversingLabs for each Portal instance. When SSO is activated, all existing user sessions will be invalidated. |
| Supported protocols | OpenID Connect (OIDC) |
| Supported integrations | Okta (recommended), but any IdP that supports OIDC should work. |
| Information required from IdP | Client ID, Client secret, Authorization endpoint, Token endpoint, Scopes The UserInfo endpoint is required if you want to use it as a claim source. |
| Supported claim sources | You can set either ID Token, UserInfo endpoint, or Access token as the claim source. Consult your IdP documentation for more detailed instructions, because some providers do not support all options listed here. |
| Security | Currently supported ID token signing algorithm is RS256 (RSASSA-PKCS1-v1_5 using SHA-256). Token verification is only done if the JWKS endpoint is set, and either the ID or the access token is used as a claim source. |
What happens when SSO is enabled?
When SSO is enabled for the Portal, existing local users are disabled and not shown on the Members page.
Standard user management functionality is also disabled and done on the identity provider side. This includes creating and updating users, adding and removing users from groups, and changing/resetting user passwords. However, users can still be removed from an organization directly through the Actions menu on the Portal.
Your organization may deactivate SSO user accounts of former employees and collaborators on the identity provider side.
When SSO is enabled on the Portal, an additional step is required to prevent unauthorized access and service abuse. To fully disable access to the Portal for a deactivated user, remove their account from your organization on the Members page.
This ensures that any remaining Personal Access Tokens generated for the user account are no longer valid.
When SSO is enabled, organization roles are determined by mappings in the SSO configuration, while user group roles are still managed on the Portal side.
The full list of permissions per role is available on the User and group management page.
Disabling SSO on the Portal reverts to local login. In this case, only local users are shown on the Portal. SSO settings are preserved, so if you want to re-enable SSO, you can restore the previous configuration directly on the Portal.
Previously used local login passwords cannot be restored after disabling SSO. Administrators should instruct the users to request new passwords from the login page with the "Forgot my password" link.
Prerequisites
To successfully configure SSO on the Portal, you need to have:
An administrator account for the Portal.
A valid admin account on the side of your identity provider.
1. Configure SSO on the IdP side
To be able to configure SSO on the Portal, you must first set up the integration with your preferred identity provider (IdP).
The Portal should be able to integrate with any identity provider that supports OpenID Connect (OIDC). For the purposes of this guide, we recommend Okta.
Regardless of the identity provider you choose, you'll have to set up the callback URL in the IdP configuration. In Okta or any other compatible IdP, the Sign-in redirect URIs should contain:
https://<PORTAL_URL>/login/sso-verificationhttps://<PORTAL_URL>/verify-sso-changeshttps://<PORTAL_URL>/settings/user-directory
For example, if your Portal URL is my.secure.software/production, you would use:
https://my.secure.software/production/login/sso-verificationhttps://my.secure.software/production/verify-sso-changeshttps://my.secure.software/production/settings/user-directory
Follow the instructions in the official Okta documentation to complete this step.
2. Configure SSO on the Portal
On the Portal side, the first step in configuring SSO is to enable it.
Log in to your Portal instance as an organization administrator.
Access
Settings > User Directory (SSO)in the Portal. On the SSO Configuration page that opens, select OIDC. This enables the SSO feature and allows you to modify the SSO settings on the Portal side.
The following configuration sections are available when OIDC is selected:
- Client configuration
- Provider configuration
- Signature verification
- User attribute mapping
- Organization role mapping
Depending on how your IdP is set up, you may need to fill in all configuration sections. The Signature verification section is always optional and only used for increased security (protecting against faked ID tokens).
The following tables describe the minimum required configuration fields in each section. Those fields must be filled in for the SSO integration to work.
| Client configuration | Description |
|---|---|
| Client ID | Client Identifier value for the application in your IdP settings. |
| Client secret | The value used by the application to authenticate to the authorization server. |
| Provider configuration | Description |
|---|---|
| Authorization endpoint | URL used for initiating the authorization workflow with the IdP. |
| Token endpoint | URL used for fetching your access token. |
| UserInfo endpoint | URL used for fetching user attributes. Required only if Claim source is set to UserInfo endpoint. |
| Scopes | One or more groups of claims defined on the identity provider side. Specified scopes are requested during authorization to verify the user's identity and access rights. You must specify the openid scope here. If you want to specify multiple scopes at once, separate them by spaces (e.g. openid profile email groups). |
| User attribute mapping | Description |
|---|---|
| Specify the claim that contains the user email addresses. Those email addresses will be used for user authentication on the Portal. | |
| Groups | Specify the claim that contains the list of user groups on the identity provider side. |
First name and Last name are optional fields in the User attribute mapping section, but it's useful to specify these claims when configuring SSO for the first time.
You must map at least one SSO group to the "Organization Administrator" role in the Organization role mapping section. This is required to prevent issues with administrators being locked out of the Portal. If organization administrators lose access to the Portal, contact ReversingLabs Support for assistance.
Select Save at the top of the SSO Configuration page to apply your changes. After completing the setup, you should log in to the Portal with your SSO credentials to confirm the configuration is working properly.
3. Map SSO groups to Portal groups
Users with an SSO provider account need to be in at least one SSO group (configured on the identity provider's side). That SSO group must be connected to a group on the Portal for its members to leverage the full functionality of the Portal.
Group-level mapping
Organization administrators can map SSO groups to Portal groups on the Settings > User Directory (SSO) > Group mapping page in the Portal.
All users mapped in this way will get the "Group Member" role.
Any other group roles must be directly managed in the Portal. This is done from the Members > Groups page by selecting a group and using the Actions > Edit Group Role for each individual member.
Organization-level mapping
Organization administrators can change the roles on the organization level for specific SSO groups in User Directory (SSO) > Organization role mapping.
Mapping users in this way assigns all members of the specified SSO group the same organization role on the Portal. That organization role can be either Organization Administrator, Organization Member, or Organization Security.
At least one SSO group must be assigned to the "Organization Administrator" role.
Any other group management, like adding or removing users from SSO groups, adding applications to groups, or editing SSO groups, must be done through the identity provider.
When you have successfully configured SSO on the Portal, users should immediately have access to the groups and roles they need after they log in.
If you encounter any issues with the SSO configuration that can't be resolved on the identity provider side, contact ReversingLabs Support for assistance.