Configure single sign-on access to the Command Platform
Copy link

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
Copy link

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:

Accessing SSO Settings in the Command Platform
Copy link

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
Copy link

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
Copy link

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
Copy link

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
Copy link

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
Copy link

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
Copy link

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.

⚠️

With Group Sync enabled, IdP users will be removed from any Command 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
Copy link

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.