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. Click the Administration tab.
  3. Under“Authentication” window, click Manage console authentication: 2FA and SSO.
  4. On the “Security Console Configuration” screen, click the Authentication tab.
  5. 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.
  • Changing this setting requires a console restart.
  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. 7. 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”. Click Create.
  5. Name the application and provide a logo if desired. Click Next.
  6. 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. 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”
  • Select Send LDAP Attributes as Claims. Click Next.
  1. “Configure Claim Rule”
  • Name the rule.
  • Set “Attribute store” to Active Directory.
  • Set “LDAP Attribute” to E-Mail-Addresses.
  • Set “Outgoing Claim Type” to E-Mail Address.
  • Click Finish.

Second rule: Email to Name

  1. Click Add Rule again.
  2. "Choose Rule Type"
  • Select Transform an Incoming Claim. Click Next.
  1. "Configure Claim Rule"
  • Name the rule.
  • Set “Incoming claim type” to E-Mail Address.
  • Set “Outgoing claim type” to Name ID.
  • Set “Outgoing name ID format” to Email.
  • Make sure Pass through all claim values is selected.
  • 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.

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. In the “Users” window, click Manage users then click New User. All required configuration will take place on the General tab.
  3. Give the user a name.

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.

  1. Select your new SAML authentication method from the dropdown list.
  2. Provide a full name for your user.
  3. Specify the email address of the new user.

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.

  1. Password fields will be disabled.

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.

  1. Ensure that the “Account enabled” box is checked.
  2. Click Save when finished.

SAML configuration complete!

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