Configure Azure as an SSO source for the Command Platform

This article covers how to configure a Rapid7 Command Platform single sign-on (SSO) source for use with Azure.

Create the Rapid7 Command Platform application in Azure

To create a new enterprise application in Azure:

  1. In Azure, navigate to Enterprise Applications > New Application > Create your own Application.
  2. In the application wizard on the right 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 Create.

Basic SAML configuration in Azure

Before you can download your SAML Certificate, you must first complete the Basic SAML Configuration in Azure.

To complete the Basic SAML Configuration:

  1. In the Basic SAML Configuration section in Azure, click Edit.
  2. In the Command Platform, navigate to Company Settings > Authentication Settings > SSO Settings.
  3. From the Select your identity provider (IdP) dropdown, select Azure.
  4. From the section titled Copy the following data into your external IdP, copy the Identifier (Entity ID) and replace the default URL in Azure with this.
  5. Next, copy the Reply URL and paste this into Azure.
  6. Finally, copy the Relay State and paste this into Azure and click Save.

Now that the Basic SAML Configuration is complete, your SAML Certificate becomes downloadable.

Add the Azure certificate to the Command Platform

To download the certificate:

  1. Ensure you have completed the Basic SAML Configuration section in Azure.
  2. In the SAML Signing Certificate section, click Download next to Certificate (Base64).

To add the IdP certificate to the Command Platform:

  1. From the left menu of the 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.
  4. Drag and drop your IdP certificate, or click Browse to search for it on your local machine.

Attributes and claims

Attribute statements are mandatory for authentication to the Command Platform.

To configure these attribute statements:

  1. Click Edit on the Attributes and Claims section in Azure.
  2. Leave Unique User Identifier (Name ID) unchanged.
  3. Edit the user.mail claim by changing the Name value to Email and removing the Namespace value, then click Save.
  4. Edit the user.givenname claim by changing the Name value to FirstName and removing the Namespace value, then click Save.
  5. Edit the user.surname claim by changing the Name value to LastName and removing the Namespace value, then click Save.
  6. Close the Attributes and Claims window.

Configure the Command Platform

Next, you will need to configure the Command Platform with fields from Azure.

To complete the Command Platform configuration:

  1. From the section Set up Command Platform (or your chosen name for the app) in Azure, copy the URL labeled Azure AD Identifier and paste it into the corresponding field in the SSO Settings tab in the Command Platform.
  2. Copy the field labeled Login URL and paste it into the corresponding field in the SSO Settings tab in the Command Platform.

The Command Platform should now be fully configured as an SSO-enabled enterprise app in your deployment of Azure AD, and you can now test SSO to verify this. Ensure you test the connection with a user that has been assigned to the Command Platform app in Azure.

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 in Azure. 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 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

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.

Adding the Group Attribute

To synchronize groups from Azure, the name of your Command Platform user groups must not contain any spaces.

In Azure, the first step is to create App Roles that will map to your Command Platform user groups.

To create App Roles:

  1. In Azure Active Directory, navigate to App Registrations > All Applications.
  2. Search for your Rapid7 application.
  3. Click App Roles, then click Create app role.
  4. Give your Role a display name, then select Users and Groups as the Allowed member type.
  5. In the Value field, enter the name of the corresponding Command Platform user group.

The Value field is the value that will be included in the SAML assertion, and so it must be the same as the name of the Command Platform user group this role corresponds to. As Azure forces this value to contain no spaces, ensure your Command Platform user groups also do not contain spaces.

  1. Enter a description for this role, then click Apply.
  2. Repeat this for all your Command Platform user groups.

The next step is to assign the appropriate App Roles to your users.

To assign App Roles:

  1. In Azure Active Directory, navigate to Enterprise Applications and select your Rapid7 application.
  2. Navigate to Users and Groups.
  3. To begin assigning roles to users, click Add user/group.
  4. Search for and select the users and groups that should be assigned a given role.
  5. Select the role that represents this group of users in the Command Platform.
  6. Click Assign.

Once your App Roles are configured and assigned to users and groups, you now need to add an attribute to the SAML assertion containing the names of the groups each user is assigned to.

To add this attribute to your SAML assertion in Azure:

  1. In Azure Active Directory, navigate to Enterprise Applications and select your Rapid7 application.
  2. Click Single sign-on, then click Edit in the Attributes and Claims section.
  3. Click Add new claim and name it rbacGroups.
  4. Select user.assignedroles as the Source attribute.
  5. Click Save.

Group Attribute in Azure

All the information we require from your IdP to synchronize users to Command Platform user groups will now be included when users authenticate using SSO.

Activate Group Synchronization

If you have your Command Platform user groups configured with corresponding IdP user groups included in the SAML configuration, you are ready to activate Group Synchronization.

Once Group Synchronization is activated, users will have their group memberships synced on each sign-in. This means that changes to group membership in your IdP will not be reflected in the Command Platform until the next time the user signs in.

The Command Platform does not support SCIM provisioning, so users removed from your IdP will need to manually deleted in the Command Platform.

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.

Difference between IdP and Local users

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 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.