Configure single sign-on access to the Insight Platform
Configure single sign-on (SSO) to the Insight Platform using an external identity provider (IdP). This feature allows you to authenticate and control user access to the Insight Platform from your existing single sign-on solution.
Before you begin
Security Assertion Markup Language (SAML) is a standard for logging users into applications based on their sessions in another context. This SSO login standard has significant advantages over logging in using a traditional username and password, the most important of which is that users do not need to provide their credentials directly to the Insight Platform to sign in.
Any IdP you want to use must meet the SAML 2.0 compliance requirements, which you can read about here: https://en.wikipedia.org/wiki/SAML-based_products_and_services
To test whether your IdP is compliant, you can use these free SAML testing tools:
Add an IdP certificate
The Insight Platform requires a valid X.509 SAML certificate to be uploaded before you can save your SSO configuration. Your certificate must be a base64-encoded X.509 certificate chain with DER encoding. If you have a certificate with CER encoding, you can convert it by following these instructions: https://knowledge.digicert.com/solution/SO26449.html.
You must be an Administrator of your IdP to download this certificate. Additionally, you must also be an Insight Platform Administrator to upload the certificate to your SSO configuration. Read our User Management documentation for details on the Platform Administrator role and others.
Configure SAML settings
Use the Service Provider metadata provided on the Insight Platform SSO Settings page to configure your IdP with the Insight Platform.
While your IdP may have different names for them, SAML 2.0 compliant SSO configurations require these data fields:
- Assertion Consumer Service (ACS) URL
- Audience (or Entity) ID
- Relay State URL
You can find values for these fields in the Copy the following data into you IdP section in the SSO Settings page in the Insight Platform.
Attribute statements
The Insight Platform requires a user's first name, last name, and email address be included in the SAML assertion for authentication to be successful. The fields that correspond to these values can differ between IdPs as long as they are mapped with the labels FirstName, LastName, and Email. These mappings ensure the Insight Platform will be able to accept them.
If you choose to use our Group Synchronization feature, an additional attribute containing the name of the Insight Platform User Groups you want your users to be assigned to upon login is required.
Configure the Insight Platform
Once you finish configuring your IdP, gather the following information for the Insight Platform:
- Entity ID
- Single Sign-On Service URL
Again, the name of these values will depend on your chosen IdP, but all SAML 2.0 compliant IdPs will provide these IdP Metadata values.
Set up a default access profile
A default access profile allows you to define the products and roles that are automatically assigned to new users provisioned by your IdP. See our default access profile documentation for instructions.
Group Synchronization
Group Synchronization allows you to control user group assignment from within your IdP.
This capability is made possible by including an attribute in your SAML response labelled rbacGroups that contains the name(s) of the Insight Platform User Groups for each user. Your users will be automatically assigned to the corresponding groups in the Insight Platform and will inherit the product, role, and resource access associated with those groups.
With Group Sync enabled, IdP users will be removed from any Insight Platform groups not included in their SAML assertion. IdP Users will retain any roles or permissions assigned directly to them, including those from a default access profile.
Configure user groups
As Group Synchronization requires the use of Insight Platform User Groups, it is important that you have configured groups before activating. Read our Insight Platform User Groups documentation for details on how to do this.
Users local to the Insight Platform
If you purchased or trialed Rapid7 products, you may have several local users that can sign in to the Insight Platform through insight.rapid7.com. These users will retain the ability to sign in this way until they authenticate using SSO.
- Local users will lose their ability to sign in through insight.rapid7.com after they authenticate using SSO for the first time, but will retain their existing direct access (such as with product and role assignment).
- Users managed by your IdP cannot be converted back to local users.
Local users and IdP users can be differentiated within the User Management section of the Insight Platform, as IdP users will have a circled user badge beside their name.
Rapid7 recommends keeping at least one local Platform Administrator user to support external IdP configuration or troubleshooting.
You can still configure password policies for your users.
- If you choose to apply an MFA policy to the Insight Platform in addition to an IdP MFA policy, users may be prompted to authenticate twice when accessing the Insight Platform from the IdP.
- If you choose to apply a password policy, note that local users will encounter an authentication error when their Insight Platform password expires. If this occurs, reset the Insight Platform password at the insight.rapid7.com credential prompt.