Leapsome supports single sign-on (SSO) logins through SAML 2.0. A SAML 2.0 identity provider (IDP) can take many forms, one of which is a self-hosted Active Directory Federation Services (ADFS) server. ADFS is a service provided by Microsoft as a standard role for Windows Server that provides a web login using existing Active Directory credentials.
If you're using Azure Active Directory, please refer to this tutorial instead.
Requirements
To use ADFS to log in to Leapsome, you need the following components:
- An Active Directory instance where all users have an email address attribute.
- A server running Microsoft Server 2012 or 2008.
- A SSL certificate to sign your ADFS login page and the fingerprint for that certificate.
After you meet these basic requirements, you need to install ADFS on your server. Configuring and installing ADFS is beyond the scope of this guide, but is detailed in a Microsoft KB article.
When you have a fully installed ADFS installation, note down the value for the 'SAML 2.0/W-Federation' URL in the ADFS Endpoints section. If you chose the defaults for the installation, this will end with '/adfs/ls/'.
Step 1 - Adding a Relying Party Trust
At this point you should be ready to set up the ADFS connection with your Leapsome account. The connection between ADFS and Leapsome is defined using a Relying Party Trust (RPT).
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.
1. In the Select Data Source screen, select the last option, Enter Data About the Party Manually.
2. On the next screen, enter a Display name that you'll recognize in the future (e.g. 'Leapsome Login').
3. On the next screen, select the ADFS FS profile radio button.
4. On the next screen, leave the certificate settings at their defaults.
5. On the next screen, check the box labeled Enable Support for the SAML 2.0 WebSSO protocol. The service URL will be
https://www.leapsome.com/api/users/auth/saml/ACCOUNT_ID/assert
replacing ACCOUNT_ID with your Leapsome account ID. You can find the service URL in your Leapsome account under "Admin settings" / "SSO" in the "Reply URL" field.
6. On the next screen, add a Relying party trust identifier of "https://www.leapsome.com".
7. Skip the step to set up 'multi-factor authentication'.
8. On the next screen, select the Permit all users to access this relying party radio button.
9. 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.
Step 2 - Creating claim rules
Once the relying party trust has been created, you can create the claim rules and update the RPT with minor changes that aren't set by the wizard. By default the claim rule editor opens once you created the trust.
1. To create a new rule, click on Add Rule. Create a Send LDAP Attributes as Claims rule.
2. On the next screen, using Active Directory as your attribute store, do the following:
3. Create a new rule by clicking Add Rule, selecting Transform an Incoming Claim as the template.
4. On the next screen, using Active Directory as your attribute store, do the following:
a) From the LDAP Attribute column, select E-Mail Addresses.
b) From the Outgoing Claim Type, select E-Mail Address.
c) Click on OK to save the new rule.
d) Repeat these steps for 'firstname', 'lastname' and 'picture', if desired.
5. Create another new rule by clicking Add Rule, this time selecting Transform an Incoming Claim as the template.
a) Select E-mail Address as the Incoming Claim Type.
b) For Outgoing Claim Type, select Name ID.
c) For Outgoing Name ID Format, select Email.
Leave the rule to the default of Pass through all claim values.
6. Confirm your claim rules by clicking OK one last time.
Step 3 - Adjusting the trust settings
You still need to adjust a few settings on your relying party trust. To access these settings, select Properties from the Actions sidebar while you have the RPT selected.
In the Advanced tab, make sure SHA-256 is specified as the secure hash algorithm.
Note: Your instance of ADFS may have security settings in place that require all Federation Services Properties to be filled out and published in the metadata. Check with your team to see if this applies in your instance. If it is, be sure to check the Publish organization information in federation metadata box.
Step 4 - Configuring Leapsome
After setting up ADFS, you need to configure your Leapsome account to authenticate using SAML.
You'll use your full ADFS server URL with the SAML endpoint as the SSO Login URL.
The certificate is token signing certificate installed in your ADFS instance. You can get the certificate by running the following PowerShell command on the system with the installed certificate:
C:\> Get-AdfsCertificate
Fill out these values, check 'Enable SAML-Based SSO' and hit 'Update SSO settings'. After you're done, the 'Integration' / 'Single Sing-On' page in the Leapsome should look like this:
You should now have a working ADFS SSO implementation for Leapsome.