Configure AD FS as an SSO source for the Command Platform

This article covers how to configure a Command Platform single sign-on (SSO) source for use with Active Directory Federation Services (AD FS).

Add the AD FS certificate to the Command Platform

The Command Platform requires an X.509 Certificate from AD FS to enable SSO.

Download the AD FS certificate

To download the certificate from AD FS:

1. On the AD FS server, open AD FS Management.
2. Go to AD FS > Service > Certificates.
3. Right-click on the token-signing certificate you want to save, and select View Certificate.
4. Click Details and click Copy to File….
5. Complete the Certificate Export Wizard.
6. Select Base-64 encoded X.509.
7. Click Location.
8. Click Finish.

Upload the certificate to the Command Platform

To upload the certificate:

1. In the Command Platform, navigate to the SSO Settings  tab.
2. From the Select your identity provider (IdP) dropdown, select AD FS.
3. In the section titled Add your IdP certificate, drag and drop your certificate, or click the Browse button to search for it on your machine.

Relying Party configuration

The Command Platform needs to be configured in AD FS as a Relying Party Trust.

To configure this Relying Party Trust:

1. On the AD FS server, go to AD FS Management > AD FS.
2. Right-click and select Relying Party Trust > Add Relying Party Trust….
3. Select Claims Aware.
4. Click Start.
5. Select Enter data about the relying party manually.
6. Click Next and enter the display name.
   • Rapid7 Command Platform is recommended.
7. Click Next, and click Next again.
8. Enable the Enable support for the SAML 2.0 WebSSO protocol option.
9. In the field labeled Relying party SAML 2.0 SSO service URL, copy and paste the corresponding URL from the Command Platform SSO Settings page.
10. Click Add.
11. In the field labeled Relying party trust identifier, copy and paste the corresponding URL from the Command Platform SSO Settings page.
12. Click Add.
13. Click Next.
14. Select the Access Control Policy you want to use.
15. Click Next, and click Next again.
16. Enable the Configure claims issuance policy for this application option.
17. Click Close.

Attributes and claims

This procedure covers how to configure attributes and claims in the Edit Claim Rules window.

To configure attributes and claims:

1. Select Add Rule…
2. Choose Rule Type:
   • Send LDAP Attributes as Claims should be selected by default, so click Next.
3. Configure Claim Rule:
   • In the field labeled Claim rule name, enter LDAP Mandatory Claims.
4. In the Attribute store dropdown, select Active Directory.
5. In the next table under LDAP Attribute, select Given-Name from the dropdown. Under Outgoing Claim Type, manually enter FirstName.
6. In the next row under LDAP Attribute, select Surname from the dropdown. Under Outgoing Claim Type, manually enter LastName.
7. In the next row under LDAP Attribute, select User-Principle-Name from the dropdown. Under Outgoing Claim Type, manually enter Email.
8. In the next row under LDAP Attribute, select User-Principle-Name from the dropdown. Under Outgoing Claim Type, manually enter Name ID.
9. Click Finish.

Configure the Command Platform

Next, you need to add the Federation Service Identifier and Single Sign-On URL from AD FS to the Command Platform.

To add these values:

1. On the AD FS server, right-click and select Service > Edit Federation Service Properties.
2. Copy the Federation Service Identifier URL and paste it into the corresponding field in the Command Platform.
3. To create a Single Sign-on URL, paste the Federation Service Identifier URL into a text editor, and change the following values:
   • Modify http to https.
   • Remove services/trust.
   • Add adfs/ls.
4. In AD FS, ensure the following endpoints are enabled:
   • /adfs/ls
   • /adfs/services/trust/artifactresolution

Before finishing in AD FS, you need to enable the relay state parameter for IdP and SP-initiated sign-on.

Enable the relay state parameter for IDP-initiated sign-on

To enable the relay state parameter on Windows Server 2012 R2+ and Windows Server 2016 Standard:

1. Open Powershell as an Administrator.
2. Run the following command: Set-AdfsProperties -EnableRelayStateForIdpInitiatedSignOn $true
3. Run the following command to verify that the command was applied: (Get-AdfsProperties).RelayStateForIdpInitiatedSignOnEnabled

To enable the relay state parameter on older versions of AD FS:

1. In the C:\Windows\ADFS folder, create a copy of the Microsoft.IdentityServer.Servicehost.exe.config file.
2. Add _old to the end of the copied file name.
3. Open Notepad as Administrator.
4. Open the Microsoft.IdentityServer.Servicehost.exe.config file.
5. In the <microsoft.identityServer.web> section, add the the following line: <useRelayStateForIdpInitiatedSignOn enabled="true" />
6. Save the Microsoft.IdentityServer.Servicehost.exe.config file.
7. Restart the AD FS service.

Generate the relay state URL

After following these steps for your version of AD FS, you will now be able to sign in to the Command Platform directly from your IdP using a relay state URL. You can create a relay state URL with this utility: https://jackstromberg.com/adfs-relay-state-generator/ 

The IDP URL String mentioned in that utility is simply the Relying Party SAML 2.0 service URL provided by the Command Platform earlier in the configuration process, with /idpinitiatedsignon.aspx appended. The other two fields are the same as provided.

Enable Service Provider-initiated sign-on

Contact Rapid7 Support for assistance on configuring Service Provider-initiated login.

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 AD FS. 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 labelled rbacGroups 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.

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.

Documentation from Microsoft on Claims and Attributes is available here: https://learn.microsoft.com/en-us/windows-server/identity/ad-fs/operations/create-a-rule-to-send-ldap-attributes-as-claims .