SAML 2.0 authentication

Read this first! Do you intend to enable InsightVM Platform Login?

InsightVM Platform Login is a newer, consolidated InsightVM product experience that permanently shifts authentication responsibility from the Security Console to the Insight Platform. Security Console-based authentication sources like the one detailed on this page are not usable with InsightVM Platform Login.

If you intend to enable InsightVM Platform Login soon for your user account, feel free to skip the procedure detailed on this page and head over to the InsightVM Platform Login documentation for enablement instructions and information on what external authentication sources the Insight Platform supports.

NOTE

The Security Console supports IdP initiated login using SAML 2.0 with the email address as the NameID.

Complete the following steps to configure a SAML 2.0 integration as an external authentication source. This procedure involves configuring both the Security Console (the Service Provider) and your chosen Single sign-on application (the Identity Provider) concurrently.

Terminology going forward

  • IdP = Identity Provider
  • SP = Service Provider
  • SSO = Single sign-on

Step 1: Open the SAML source configuration window

IMPORTANT

Before starting this procedure, take note of the hostname being used to access the Security Console. Since the SP URL and metadata are automatically generated when the Security Console is first accessed, you must ensure that this hostname remains consistent when accessing the console going forward.

If the hostname being used to access the Security Console changes at any time, you will need to restart the console with the original hostname or reconfigure your SAML authentication source entirely.

If your network configuration frequently causes this condition, consider specifying a Base Entity URL override according to #5 detailed below.

  1. Open your Security Console.
  2. On the Administration page, click Console > Authentication: 2FA and SSO.
  3. On the Security Console Configuration screen, click the Authentication tab.
  4. If desired, specify a Base Entity URL in the provided field.
  • When used, this URL will override the SP URL that is automatically generated by the initial Security Console request.
  1. Under SAML Authentication Source, click the Configure SAML Source button.

NOTE

You can only define one SAML authentication source. Defining a new SAML source will overwrite the current source definition, if it exists.

The SAML Configuration window will provide a template version of the SSO URL and a complete Entity ID.

  1. Copy both of these values at this time, as they are required to complete your IdP configuration.

Step 2: Create an IdP application

In a separate browser window, navigate to your desired IdP that you intend to use. Instructions are available for the following providers:

REQUIRED

You must have administrator privileges in your IdP to complete this procedure.

Okta

  1. Navigate to your Okta administrator dashboard and click the Applications tab.
  2. Click Add Application.
  3. Click Create New App.
  4. Specify the Sign on method as SAML 2.0.
  5. Click Create.
  6. Name the application and provide a logo if desired.
  7. Click Next.
  8. In the Single sign on URL field, paste the template SSO URL that you copied from the Security Console.

IMPORTANT

Make sure to substitute <console-hostname> and <console-port> with the appropriate values.

  1. In the Audience URI (SP Entity ID) field, paste the entity ID that you copied from the Security Console.
  2. Set Name ID format to EmailAddress.
  3. Set Application username to Email.
  4. Click Next.
  5. Click Finish.
  6. Navigate to the Sign On tab of your newly configured Okta application.
  7. Under Settings, click View Setup Instructions.
  8. Scroll to the Optional section. Copy the contents of the IDP metadata field.

Assign your application to users

Newly configured Okta applications must be assigned to users before they can access them:

  1. Navigate to the Assignments tab of your Okta application.
  2. Click Assign.
  3. Click Assign to People or Assign to Groups.
  4. Specify who will have access to the application.

IMPORTANT

Take note of the email address attached to each of your users on this screen. All users being assigned the application must have a corresponding user account in the Security Console with a matching email address.

Success!

Proceed to Step 3 when ready.

Centrify

  1. Navigate to your Centrify Admin Portal menu and click the Apps tab.
  2. Click Add Web Apps.
  3. Click the Custom tab.
  4. Scroll to the SAML app and click Add.
  5. Click Yes to confirm.

TIP

Centrify apps are considered Deployed when all required fields have been validated and user access has been assigned. All necessary configuration steps will be completed from the named tabs listed here.

Leave any fields or tabs not listed in this procedure to their default value or blank state.

Settings page

  1. Name and describe the app.
  2. Provide a logo if desired.

Trust page

  1. Set Identity Provider Configuration to Metadata.
  2. Set Service Provider Configuration to Manual Configuration. This action will produce additional fields.
  3. In the Assertion Consumer Service (ACS) URL field, paste the template SSO URL that you copied from the Security Console.

IMPORTANT

Make sure to substitute <console-hostname> and <console-port> with the appropriate values.

  1. In the SP Entity ID / Issuer / Audience field, paste the entity ID that you copied from the Security Console.
  2. Leave the Recipient field blank, but make sure the “Same as ACS URL” box is checked.
  3. Set “NameID Format” to emailAddress.
  4. Click Save.
  5. Return to the Identity Provider Configuration metadata section and click Copy XML.
  • You can also click Download Metadata File as an alternate method for Security Console upload later.

"User Access" page

  1. Click Add.
  2. Specify any individuals or groups that will have access to the app.

IMPORTANT

Take note of the email address attached to each of your users on this screen. All users being assigned the application must have a corresponding user account in the Security Console with a matching email address.

"Account Mapping" page

  1. Click Directory Service Field.
  2. In the “Directory Service field name” field, enter mail.
  3. Click Save.

Your app should now display a status of Deployed.

Success!

Proceed to Step 3 when ready.

Active Directory Federation Services 3.0

  1. In your AD FS directory view, expand the Trust Relationships folder. Click Relying Party Trusts.
  2. Under Actions, click Add Relying Party Trust.
  3. Click Start.
  4. Select Data Source.
  • Select Enter data about the relying party manually.
  • Click Next.
  1. Specify Display Name.
  • Provide the Relying Party Trust with a display name. Add a description in the Notes field if desired.
  • Click Next.
  1. Choose Profile.
  • Select AD FS profile. This option will explicitly list the SAML 2.0 protocol in its description.
  • Click Next.
  1. Configure Certificate.
  • No configuration is required here.
  • Click Next.
  1. Configure URL.
  • Check the Enable support for the SAML 2.0 WebSSO protocol box.
  • In the Relying party SAML 2.0 SSO service URL field, paste the template SSO URL that you copied from the Security Console. Click Next.

IMPORTANT

Make sure to substitute <console-hostname> and <console-port> with the appropriate values.

  1. Configure Identifiers.
  • In the Relying party trust identifier field, paste the entity ID that you copied from the Security Console. Click Add.
  • Click Next.
  1. Configure Multi-factor Authentication Now?.
  • Do not enable at this time.
  • Click Next.
  1. Choose Issuance Authorization Rules.
  • Select Permit all users to access this relying party.
  • Click Next.

IMPORTANT

All users being given permission to access the Relying Party Trust must have a corresponding user account in the Security Console with a matching email address.

  1. Ready to Add Trust
  • You can review all your configuration steps at this point in the wizard.
  • Click Next when ready.
  1. "Finish"
  • Ensure that the Open the Edit Claim Rules box is checked.
  • Click Close.

Configure Claim Rules

The “Edit Claim Rules” configuration window should display automatically after finishing the Relying Party Trust process. If it doesn’t, select (or right-click) your new Relying Party Trust and click Edit Claim Rules.

You will need to create two Claim Rules to properly configure your Relying Party Trust:

IMPORTANT

The Claim Rules must be configured in the correct order. Ensure that you follow these steps carefully. Verify that the order is correct when finished.

First rule: LDAP claims

  1. On the Issuance Transform Rules tab, click Add Rule.
  2. Choose Rule Type.
  3. Select Send LDAP Attributes as Claims.
  4. Click Next.
  5. Configure Claim Rule.
  6. Name the rule.
  7. Set Attribute store to Active Directory.
  8. Set LDAP Attribute to E-Mail-Addresses.
  9. Set Outgoing Claim Type to E-Mail Address.
  10. Click Finish.

Second rule: Email to Name

  1. Click Add Rule again.
  2. Choose Rule Type.
  3. Select Transform an Incoming Claim.
  4. Click Next.
  5. Configure Claim Rule.
  6. Name the rule
  7. Set Incoming claim type to E-Mail Address.
  8. Set Outgoing claim type to Name ID.
  9. Set Outgoing name ID format to Email.
  10. Make sure Pass through all claim values is selected.
  11. Click Finish.

Click Apply when you’ve finished configuring the Claim Rules.

Download metadata

Metadata for Active Directory Federation Services must be downloaded in an XML file from a direct link. Use the following template:

 
1
https://<adfs-hostname>/FederationMetadata/2007-06/FederationMetadata.xml
  1. Substitute <adfs-hostname> with the appropriate value.
  2. Open a new browser window and search the complete metadata link.
  3. A successful connection will automatically trigger a metadata XML file download.

Success!

Proceed to Step 3 when ready.

Azure

Requirements

  • Azure administrator privileges
  • InsightVM Global Administrators
  • ROOT/Administrator privilege access to HOST running InsightVM

Instructions

  1. In Azure, search for Enterprise Applications.
  2. Click on New Application.
  3. Click Create your own application.
  4. In the application wizard on the right-hand side, give the application a name such as Rapid7.
  5. Select the option Integrate any other application you don't find in the gallery.
  6. Click on Create.
  7. Go to Users and groups in the menu on the left.
  8. Click Add user/group.
  9. Follow the wizard instructions for adding your user to the application.
  10. Click on Single Sign-on on the left-hand menu and select SAML to configure SSO.

The application requires users to be added to it for members of your organization to log into Rapid7, for now we just need to add your user (the rest can be added later).

Basic SAML Configuration

  1. In Section 1, Basic SAML Configuration, click Edit.
  2. Click on the Administration tab.
  3. Under Authentication click Manage console authentication: 2FA and SSO.
  4. Click CONFIGURE SAML SOURCE.
  5. Copy the Entity id found in the SAML Configuration window and paste into Azure’s Identifier (Entity ID).
  6. Click the Configure SAML Source button.

Azure’s Reply URL (Assertion Consumer Service URL) must contain the console case sensitive URL like this example, https://insightvmconsole:3780/saml/SSO.

If the console requires an IP or Public URL, you must amend the case sensitive /SAML/SSO after the access port port number.

If the console access port is not the default 3780, please make sure you reflect this in the URL (including if you changed it to 443) such as https://insightvmconsole:443/saml/SSO.

User Attributes & Claims

  1. In Section 2, User Attributes & Claims, click Edit.
  2. Under Additional claims, we will make the following changes:
    • Delete all Claim Names expect for 1.
    • Click on the claim you want to edit.
    • Name = Email.
    • Source Attribute = user.mail.

For the required attributes and claims, the Security Console requires only one Email or Email address.

SAML Certificates

  1. In Section 3, click SAML Certificates > Federation Metadata XML.
  2. Click Download.
  3. Click on the Administration tab.
  4. Under Authentication click Manage console authentication: 2FA and SSO.
  5. Click CONFIGURE SAML SOURCE.
  6. Click Choose File and select the metadata file
  7. Click Open.

Why the Security Console may require a restart

The Security Console requires a restart when the metadata or Base Entity URL is modified. The Base Entity URL should be modified if the DNS is used for the host. An example of a Base Entity URL is https://insightvmconsole:3780/saml/SSO.

  1. To restart, navigate to the Administration tab.
  2. Under Troubleshooting, click Run command.
  3. Type restart.

You should now be all set to use IdP-initiated single sign on. Users can now log into the IDP and have access to the InsightVM console using SSO.

Troubleshooting tips

Monitor logs
  1. SSH into console to check that the console is starting up.
  2. Type: sudo -i and then screen -x nexpose.
  3. Lines to look for:
  • Good: Overriding metadata generator entity base URL using NSC config: https://nexpose.companyname.com:3780 (you might see a period at the end of it but that’s fine)
  • Bad: authentication request failed: x.x.x.authenticaiton.AuthenticationServiceException: incoming SAML message is invalid. This means something is wrong with the actual principal
  • Bad: Setting DocumentBuilderFactor attribute ‘https://x.x.x… and on the next line it says incoming SAML message is invalid. This means it’s failing assertion. In this case, go back and log into the Azure portal. Look at the email of the user that is logged in. It should exactly match the email that is being used by the user on the console side (case sensitive). If you see that it does not match:
    • Make sure the SAML Message Decoder plugin is installed on the browser you are using
    • Navigate to the apps in Azure and click on the Nexpose app you created and select the user to login with. It should fail.
    • Now click on the SAML message that generates in the browser’s SAML Message Decoder plugin that you just installed. Make sure response ID is coming from the right place (from the right IDP). Also, ensure it has the right issuer (This would be specific to the IDP and is generated when you set up the account for Azure). Scroll down further and check that for NameID the email format is set to unspecified.
      • You can verify the metadata on the console in /opt/rapid7/nsc/saml and file is samlIDPmetadata.xml.
  1. You can also open another session and navigate to /opt/rapid7/nexpose/nsc/logs and then enter sudo tail auth.log -f.
If a user cannot authenticate
  1. Check that the user exists in the Security Console under Administration>Users.
  2. Ensure that they are set up with SAML.
Testing in Azure
  1. Check the destination and make sure it does not say insight.rapid7 (the platform).
  2. Clear browser cache.
  3. Delete the app and start over if it still does not work. Test it and send over logs.
  4. Click sign in as current user.
  5. Check out the SAML reader you installed on the browser.
Adding additional users

If you want to add more users to the platform side, you will need to disable SSO first and then add the users. Then reactivate sso and users will be able to login through the Azure app.

Step 3: Complete the SAML source configuration

Return to the SAML configuration window in your Security Console and perform the following steps:

  1. Paste (or upload via XML) the IdP metadata you copied in the previous step in the corresponding field. Click Save.

Is metadata viewable after initially saving it?

Previously saved metadata will NOT be viewable if you revisit the SAML source configuration, and therefore, metadata cannot be edited without replacing it entirely. However, bear in mind that previously saved metadata will still be in place even though you can’t see it.

If you need to replace the metadata at any point, you must restart the Security Console for those changes to take effect.

  1. Lastly, click Save again to finalize your external authentication sources.

IMPORTANT

DO NOT skip this step. The entire “Security Console Configuration” page must be saved in order for your new SAML source to be usable.

Step 4: Create user accounts

With your external authentication source defined, you must now create accounts for your users.

  1. Click the Administration tab.
  2. Click Manage users under the Users section.
  3. Click Add User
  4. Complete all fields as required.

For more information about creating user accounts read our Managing users and authentication docs.

Unique username required

Although your SAML source does not use the information from this field, the Security Console still requires all usernames to be unique.

External authentication sources

Password fields are disabled when external authentication sources are selected. The Security console does not control, or allow for, password changes for users authenticated by external sources.

Case sensitive credentials

The email address and NameID you specify here are case sensitive and must exactly match the email address and NameID of the corresponding user account defined in your IdP.

SAML configuration complete!

You should now be able to access the Security Console via your chosen IdP.