Single Sign-On

Configure single-sign (SSO) on 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.

Some of the popular SAML 2.0 compliant identity providers are:

You can also configure Multi-factor Authentication options for both local and IdP users.

If you decide to use SSO authentication, platform administrators will no longer be able to add users to the Insight platform. All new users must be added through your external identity provider.

Before You Begin

Security Assertion Markup Language (SAML) is a standard for logging users into applications based on their sessions in another context. This single sign-on (SSO) login standard has significant advantages over logging in using a username/password: No need to type in credentials.

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 free SAML testing tools, such as the following:

Your certificate must be base64-encoded X.509 certificate chain with DER encoding. If you have a certificate with CER encoding, you can convert following these instructions: https://knowledge.digicert.com/solution/SO26449.html

Get Started

To use an identity provider:

  1. Add the IdP Certificate
  2. Configure SAML Settings
  3. Configure the Insight Platform
  4. Add Users to the IdP
  5. Review Users Local to the Insight Platform

In the following instructions for configuring an external identity provider, this documentation uses Okta as the IdP example.

However, the same procedure should apply when setting up any SAML 2.0 compliant IdP.

Add an IdP Certificate

Before you can configure IdP settings in the Insight platform, you need to:

  1. Download an IdP certificate
  2. Add the Certificate to the Insight platform

Download the Certificate

You must be an admin of your IdP to download this certificate. Additionally, you must also be a Platform Admin for the Insight platform. Read about what you can do with Insight platform user profile.

The following steps are explicit instructions for those using Okta as their IdP.

To download the Okta IdP certificate you must first create an application on your external IdP that will represent the Rapid7 Insight Platform.

To do so:

  1. Log in to Okta.
  2. Select the Admin button from the top right corner.
  3. On the Okta Dashboard, ensure that the top right link says “Classic UI.”
  4. Expand the “Applications” dropdown and select the Applications page.
  5. Click the green Add Application button.
  6. Click the green Create New App button. The “Create a New Application Integration” window appears.
  7. In the Platform field, ensure that the “Web” option is selected.
  8. For “Sign on method,” select the SAML 2.0 option and then click the Create button.
  9. Give your app a name, and optionally add an App logo and choose from app visibility options.
  10. Click the Next button.
  11. Click the Download Okta Certificate button.

Add the IdP Certificate

After you download the certificate, navigate to the Insight platform.

To add the Okta IdP certificate to the Insight platform:

  1. Log in to the Insight platform.
  2. On the left hand menu, select the Settings page.
  1. Select the Authentication Settings tab.
  2. Select the SSO Settings tab.
  3. Turn on SSO by clicking the Enable toggle.
  4. Drag and drop your IdP certificate, or click the Browse link to search for it on you local machine.
  1. Click the Upload button to add your certificate.

You will see green check marks which confirm the upload is complete. If the certificate is invalid, you will see a red error message.

Configure SAML Settings

Use the information provided on the Insight platform SSO page to configure your IdP with the Insight platform.

To do so:

  1. On the "SSO Settings" tab within My Account on the Insight platform, click the Copy button to copy the value from the “ACS URL” field.

Assertion Consumer Service (ACS) is the service provider's endpoint (URL) that is responsible for receiving and parsing a SAML assertion. Some service providers may use different terms for the ACS.

  1. Return to Okta or your IdP and paste the value into the “Single sign on URL” field.
  2. Return to the Insight platform and click the Copy button to copy the value from the “Audience URL” field.

The value within the Audience URL is a SAML assertion that specifies the singular user for whom the assertion is intended for. "Audience" indicates the service provider. Some service providers may use different terms.

  1. Return to Okta or your IdP and paste the value into the “Audience URI (SP Entity ID)” field.
  2. Return to the Insight platform > SSO Settings tab and click the Copy button to copy the value from the “Default Relay State” field.
  3. Return to Okta or your IdP and paste the value into the “Default RelayState” field.
  4. In the Okta “Attribute Statements” section, or equivalent within your IDP, add the following attribute statements. These are are mandatory for authentication to the Insight platform.

The values that provide this information may differ between IdP vendors. For example, some IdP vendors may use givenName instead of given_name. It is critical that the Name is always included in the SAML Assertion. The table below outlines the Names you need to include.

Name

Value

FirstName

user.firstName

LastName

user.lastName

Email

user.email

SAML Attribute Names

As previously mentioned, some service providers may use different terms for the same attribute. For example, the mandatory attribute FirstName may be referenced as given_name, givenName, or simply gn within your external IdP. LastName may be family_name, surname , or sn.

  1. Click the Next button and then click the Finish button.

While the Okta screen indicates that these fields are optional, they are mandatory. You must configure Attribute Statements for user values for your Insight platform SSO setup in order to map the SAML assertion to user values.

You will then see the single app dashboard for the App you just configured.

Configure the Insight Platform

Once you finish configuring your IdP, gather the following information for the Insight platform:

  • Issuer URL
  • Single Sign-On URL

To find these values:

  1. In the single app dashboard for your app, click the View Setup Instructions button beneath the “SAML 2.0” table. You will see a page titled “How to Configure SAML 2.0 for [Your App].”
  2. Copy the URL for second value, “Identity Provider Issuer,” and return to the Insight platform. This URL is a unique identifier of the Identity Provider who will issue the SAML2 security token.
  1. Return to the Insight platform and paste the value into the “Issuer URL” field.
  2. Copy the first value from the “Identity Provider Single Sign-On URL” field.
  3. Return to the Insight platform and paste the URL into the “Single Sign-On URL.”
  4. Click the Submit button to verify the IdP certificate. You will see a confirmation message.
  5. If your certificate expires, click the Change Certificate button to upload the new certificate.

You can remove or change the IdP certificate by clicking the Change Certificate or Delete buttons. Note that when you click the delete button at the bottom of the page, it will permanently delete the previous IdP configuration.

Add Users to the IdP

After completing the configuration add users to your IdP and connect them to the Rapid7 Insight platform.

In your IdP, you need to grant users access to the Insight platform.

To add access for users in Okta:

  1. Select the Directory dropdown and choose the People option.
  2. Find and select the user you want to provide access, or add a new user.
  3. Once you select the user, click the Assign Application button.
  4. Search for the application you previously created and click the Assign button.
  5. Check that the username is correct, and then click the Save and Go Back button.
  6. Click the Done button.

The user should now have access from the IdP to the Insight platform.

For the user to access the Insight platform, they should:

  1. Log in to the IdP.
  2. If applicable, choose and answer security questions.
  3. Click the Create My Account button.

The user should see the Insight platform app after logging in. For Okta users, this app is located on the Okta dashboard.

  1. Click the Insight platform application. The Insight platform will load with the user logged in.
  2. If the user does not have access to any Insight products, click on the Request Access button on any product the organization owns.
  3. The same local user who configured the IdP settings for the Insight platform, and who is a Platform Admin, should then grant access to the user.

On the User Management page, you will see an icon next to usernames that were added from the identity provider. These users can only log in through the IdP, and cannot login locally to the Insight platform.

Set Up a Default Access Profile

If your organization has a large user base, you can set up a default access profile to streamline the process of adding users to the Insight platform from your external identity provider (IdP). A default access profile specifies predefined permissions and product assignments that you can easily use to provision new users.

Users Local to the Insight Platform

If you purchased or trialed Rapid7 products, you may have several local users that can log in to the Insight platform through insight.rapid7.com. These users can also login through your identity provider if they have the same login email address.

Rapid7 recommends deleting local users via the Insight platform User Management feature and instead configuring these users to access the Insight platform from your external IdP.

However, please maintain 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 policies, note that local users will encounter an authentication error when their Insight platform password expires. If this occurs, reset the Insight platform password at insight.rapid7.com