How to configure SSO on the Portal
Single Sign-On (SSO) is an authentication approach that allows users to log in to various applications and services 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.
The SSO feature on the Spectra Assure Portal supports the following protocols:
- OpenID Connect (OIDC)
- Security Assertion Markup Language (SAML) (2.0)
Organization administrators can enable and disable SSO login on the Portal, as well as configure their preferred SSO method on the Settings > User Directory (SSO) page. 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.
The Portal 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. In other words, it's not possible to use OIDC and SAML at the same time. |
| 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) Security Assertion Markup Language (SAML) |
| Supported integrations | Okta (recommended), but any IdP that supports OIDC and/or SAML should work. |
| Information required from IdP | OIDC: Client ID, Client secret, Authorization endpoint, Token endpoint, Scopes The UserInfo endpoint is required if you want to use it as a claim source. SAML: Metadata URL |
| OIDC: 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. |
| OIDC: 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
Typically, the SSO configuration involves the following steps:
- Set up the integration on the identity provider (IdP) side
- Copy the required information from the IdP configuration
- Set up the preferred SSO method on the Portal using the information from the IdP configuration
- Map user groups configured in IdP to groups on the Portal
- Test and validate the configuration
1. Configure SSO on the identity provider 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 OIDC or SAML. The instructions in this guide are based on Okta configuration and may differ for other identity providers.
This step is different for each SSO method. Select the tab for the method you want to configure.
- OIDC
- SAML
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
If Okta is your IdP, follow the instructions in the official Okta documentation to complete this step.
Regardless of the identity provider you choose, you'll have to configure it so that Spectra Assure Portal is treated as a Service Provider (SP) in the SAML authentication workflow.
1 - To ensure the data can be correctly passed between the IdP and the Portal, the following configuration is mandatory on the IdP side:
| Assertion Consumer Service | The address to which the IdP will send a SAML response. In some IdPs, this is called SSO URL or Reply URL. Must be set to <PORTAL_URL>/api/auth/v1/sso/saml/acs For example, if your Portal URL is my.secure.software/production, you would use: https://my.secure.software/production/api/auth/v1/sso/saml/acs |
| Service Provider Entity ID | A unique identifier for the service provider in your IdP configuration. In some IdPs, this is called Audience URI. Must be set to <PORTAL_URL> For example, if your Portal URL is my.secure.software/production, you would use: https://my.secure.software/production |
| Name ID Format | The format in which usernames will be sent in the SAML response. Must be set to EmailAddress |
| Application username | Must be set to Email |
2 - To be able to match the user accounts from the IdP to users in the Spectra Assure Portal, configure the following attribute statements:
| Name | Value |
|---|---|
user.email | |
| first_name | user.firstName |
| last_name | user.lastName |
3 - To allow mapping the user accounts from the IdP to groups in the Spectra Assure Portal, configure the group attribute statements as follows:
| Name | Filter / Regular expression |
|---|---|
| groups | .* |
Setting the filter to this value allows the Portal to retrieve all groups from the IdP. Make sure user accounts and/or groups are correctly assigned on the IdP side. In Okta, this can be done in the Assignments configuration for the SAML application.
4 - After completing the configuration on the IdP side, copy the Metadata URL. You will have to use this URL later in the Portal configuration. In Okta, this information can be found in Sign On > Settings > Metadata details for the SAML application.
Different IdPs may require different values for service provider configuration. In addition, the SAML response sent by the IdP when logging in to a service provider may have different default values.
If Okta is your IdP, consult the official Okta documentation for additional help with this step.
2. Configure SSO on the Portal
On the Portal side, the first step in configuring SSO is to enable it.
1 - Log in to your Portal instance as an organization administrator.
2 - Access Settings > User Directory (SSO) in the Portal. On the SSO Configuration page that opens, select your preferred SSO method. This enables the SSO feature and allows you to modify the SSO settings on the Portal side.
This step is different for each SSO method. Select the tab for the method you want to configure.
- OIDC
- SAML
When OIDC is selected, the following configuration sections are available:
- 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.
When SAML is selected, the following configuration sections are available:
- Provider configuration
- User attribute mapping
- Organization role mapping
The Metadata URL in the Provider configuration is always mandatory. Input the metadata URL you previously copied from the IdP configuration into this field.
The following configuration fields should be filled in for the SSO integration to work. Their configuration values must match the names configured in the attribute statements on the IdP side. You may have to use different values than the ones listed here. In that case, always make sure they are aligned with the configuration on the IdP side.
| User attribute mapping | Configuration value |
|---|---|
email | |
| First name | first_name |
| Last name | last_name |
| Groups | groups |
First name and Last name are optional fields in the User attribute mapping section, but it's recommended to specify them when configuring SSO for the first time.
3 - In the Organization role mapping section, you must map at least one SSO group to the "Organization Administrator" role. 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.
4 - To apply your changes, select Save at the top of the SSO Configuration page. 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.
This step is the same for all supported SSO methods.
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.
Some identity providers don’t expose group names, and instead use an ID like bcbd79b7-784f-43f2-af70.
If that is the case with your identity provider, you should specify the ID as the Group name in your SSO Identity Provider in the group mapping configuration.
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.