Azure SSO SAML

Configure single sign-on (SSO) using Azure to authenticate and control user access to the Insight Platform. You can create a default profile template with specified permission levels for new users who sign up to the Insight Platform.

Before you begin

In order to configure Azure SSO SAML, you must have Azure administrator privileges and Rapid7 Platform administrator privileges.

Configure Azure SSO SAML

Step 1: Add an application and manage users in Azure

  1. In Azure, navigate to Enterprise Applications > New Application > Create your own Application.
  2. In the application wizard on the right-hand side of the screen, give your application an identifiable name such as “Rapid7”. Select the option “Integrate any other application you don’t find in the gallery” and click on Create.
  3. Add a user by navigating to Users and groups in the left menu and clicking Add user/group. Follow the wizard instructions to add your user to the application. Azure requires that a user be added in order for members of your organization to log into Rapid7. You should also note that:
    • You are able to add a user that is already in the system or create a new user with a default profile.
    • Anyone who has access to your instance of Azure will also be able to access the Insight Platform, even if they don’t have an existing profile in the Platform. The user will be created and assigned to the default policy.

Step 2: Add a certificate in Azure

  1. In Azure, navigate to Single Sign-on in the left menu and select SAML.
  2. In section 3 of the Azure SAML configuration, click on Add a certificate. You will need to generate a certificate that can be imported to the Rapid7 Insight Platform. Select these settings:
    • Signing Option: set to Sign SAML Response and Assertion.
    • Signing Algorithm: leave as Sha-256.
    • Click + New Certificate > Save. Azure SSO Certificate
  3. Click on the ellipses next to the Certificate thumbprint and download the “Base64 Certificate”.

Step 3: Enable SSO in the Insight Platform

  1. In the Insight Platform, navigate to the Settings > Authentication Settings > SSO Settings.
  2. Turn on SSO by clicking the Enable toggle.
  3. Add the X.509 certificate. Drag and drop the certificate you downloaded from Azure, or click Browse to locate the file and upload.

You will see green check marks which confirm the upload is complete. If you see a red error message, follow the instructions in Step 2: Add a certificate in Azure to generate a new certificate, then upload it to the Insight Platform.

Step 4: Configure Azure SSO Settings

  1. Navigate back to the Azure SAML configuration.
  2. In section 1, click Edit to configure these settings:
    • Identifier (Entity ID): copy and paste the "Audience URL" found on the Rapid7 Platform SSO Settings page.
    • Reply URL (Assertion Consumer Service URL): copy and paste the “ACS URL” from the Rapid7 Platform SSO Settings page.
    • Relay State: copy and paste the “Default Relay State URL” from the Rapid7 Platform SSO Settings page.
    • Press Save. Azure SSO Settings
  3. In section 2 (User Attributes & Claims), click Edit to configure these settings:
    • Required claim (Unique User Identifier - Name ID): these settings can be left unchanged.
    • User.mail: remove the namespace value to leave it blank. Change name from "emailaddress" to "Email". Press Save.
    • User.givenname: remove the namespace value to leave it blank. Change name from "given name" to "FirstName". Press Save.
    • User.surname: remove the namespace value to leave it blank. Change name from "surname" to "LastName". Press Save.
  4. Return to the SAML configuration.

Step 5: Set up Azure SSO in the Insight Platform

  1. Navigate back to the Insight Platform to the SSO Settings page.
  2. In section 4 of the Azure SAML configuration, copy the “Azure AD Identifier”. In the Insight Platform, paste this value into the “Issuer URL” field.
  3. In the Azure Enterprise Application, navigate to Properties on the left menu and copy the "User Access URL". In the Insight Platform, paste this value into the "Single Sign-On URL" field. Azure SSO Properties
  4. Step 5 of the Rapid7 Platform SSO configuration page allows you to create a default profile template for new users who sign up to the platform. New users will be automatically assigned access to products with the permission level you specify here.
  5. Click Submit.

Verify your configuration

Test the sign-in flow from Azure by signing in from your Rapid7 application to verify that your connection is successful.

Disable SSO

To disable SSO on the Insight Platform, follow these steps:

  1. In the Insight Platform, navigate to My Account > SSO Settings.
  2. Toggle the button to Disable SSO. Azure SSO Disable Button

Troubleshoot

Below are some possible errors and how to troubleshoot them.

Token error

  1. Download the “base64 certificate” again from Azure, located on the SAML page. Reupload this file to the Insight platform by following the instructions in Step 3: Enable SSO in the Insight Platform.
  2. Try testing another user.

400 request error

  1. Ensure that you have removed the namespace value in the “User Attribute and Claims” section of your Azure SAML configuration according to Step 4: Configure Azure SSO Settings. Azure SSO 400 Error
  2. Check that you have selected the “SAML Response and Assertion” Signing Option according to Step 2: Add a certificate in Azure. If you did not select this option, follow the steps to generate a new certificate with the correct settings.
  3. If all data looks correct, try logging into the Rapid7 app you made in the application library.

Other errors

If you cannot identify the issue, create a new app and follow the steps to Configure Azure SSO again.