Single Sign-On (SSO) via SAML 2.0

Purpose

The following has been documented to advise how to enable Single Sign-On (SSO) using their Active Directory Federation Service (ADFS).

Gearbox support single sign-on (SSO) logins through SAML 2.0. A SAML 2.0 identify provider can take many forms, one of which is using Active Directory Federation Services (ADFS) server.

High-Level Workflow

Requirements

To use ADFS to log into you businesses Gearbox account you will need the following:

  1. An active directory instance where all users have an email address attribute
  2. A Gearbox account
  3. A SSL certificate to sign your ADFS login page

Setup

Step 1 – Setting up Gearbox

First off click on the User icon (1), then click on Settings (2), and within the Settings page click on Integrations (3).

Scroll down to panel ‘SAML Single sign-on’, and click the panel (1) to reveal the settings

Enable (1) SAML single sign-on, then enter the metadata URL (2) of your identify provider for Gearbox to contact (this URL must use HTTPS). Lastly, paste in the full signing certificate (3) from your identify provider and click save (4).

Once successfully saved, the following information will be provided to assist with setting up the identity provider.

Step 2 – Adding a Relying Party Trust

Select the Relying Party Trusts folder from AD FS Management, and add a new Standard Relying Party Trust from the Actions sidebar. This starts the configuration wizard for a new trust. In the Select Data Source screen, select the first option, Import data about the relying party published online or on a local network. On the next screen, enter a Display name that you’ll recognise in the future, and any notes you want to make.

On the next screen, you may configure multi-factor authentication but this is beyond the scope of this guide.

On the next screen, select the Permit all users to access this relying party radio button.

On the next two screens, the wizard will display an overview of your settings. On the final screen use the Close button to exit and open the Claim Rules editor.

Once the relying party trust has been created, you can create the claim rules which are required to map user data from active directory to the SAML 2.0 message.

To create a new rule, click on Add Rule. Create a Send LDAP Attributes as Claims rule.

On the next screen, using Active Directory as your attribute store, do the following:

  1. From the LDAP Attribute column, select E-Mail Addresses.
  2. From the Outgoing Claim Type, select E-Mail Address.
  3. From the LDAP Attribute column, select Given-Name.
  4. From the Outgoing Claim Type, enter First Name.
  5. From the LDAP Attribute column, select Surname.
  6. From the Outgoing Claim Type, enter Last Name.
  7. Click on OK to save the new rule.

Create another new rule by clicking Add Rule, this time selecting Transform an Incoming Claim as the template.

On the next screen:

  1. Select E-mail Address as the Incoming Claim Type.
  2. For Outgoing Claim Type, select Name ID.
  3. For Outgoing Name ID Format, select Email.
  4. Leave the rule to the default of Pass through all claim values.
  5. Click OK to create the claim rule, and then OK again to finish creating rules

Step 5 – Retrieve AD FS signing certificate

Navigate to ADFS certificates (1), click on token-signing certificate (2) to view certificate (3)

Copy certificate to file.

Choosing Base-6 encoded X.509 (.CER)

Copy the contents of the saved file and paste it to Gearbox’s SAML full signing certificate.