Configure single sign-on access to the Command Platform

Configure single sign-on (SSO) to the Command Platform using an external identity provider (IdP). This feature allows you to authenticate and control user access to the Command 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 Command 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:

• https://samltest.id/ 
• https://www.samltool.com/ 

Accessing SSO Settings in the Command Platform

To access SSO Settings:

1. From the left menu of the Rapid7 Command Platform Home page, click the Administration link.
2. In the left menu of the Administration page, click Settings.
3. Click the SSO Settings tab in the Authentication Settings section.

Add an IdP certificate

The Command 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 a Command 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 Command Platform SSO Settings page to configure your IdP with the Command 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 Command Platform.

Attribute statements

The Command 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 Command Platform will be able to accept them.

If you choose to use our Group Synchronization feature, an additional attribute containing the name of the Command Platform User Groups you want your users to be assigned to upon login is required.

Configure the Command Platform

Once you finish configuring your IdP, gather the following information for the Command 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 Command Platform User Groups for each user. Your users will be automatically assigned to the corresponding groups in the Command Platform and will inherit the product, role, and resource access associated with those groups.

Configure user groups

As Group Synchronization requires the use of Command Platform User Groups, it is important that you have configured groups before activating. Read our Command Platform User Groups documentation for details on how to do this.

Users local to the Rapid7 Command Platform

If you purchased or trialed Rapid7 products, you may have several local users that can sign in to the Command 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 Command Platform Administration, as IdP users will have a circled user badge beside their name.

You can still configure password policies for your users.

• If you choose to apply an MFA policy to the Command Platform in addition to an IdP MFA policy, users may be prompted to authenticate twice when accessing the Command Platform from the IdP.
• If you choose to apply a password policy, note that local users will encounter an authentication error when their Command Platform password expires. If this occurs, reset the Command Platform password at the insight.rapid7.com  credential prompt.