LiquidPlanner supports SAML 2.0 (Security Assertion Markup Language 2.0), which allows for the use of SSO (Single Sign-On) using enterprise identity providers such as Active Directory. Enabling SSO via SAML 2.0 means that user authentication is handled entirely outside of LiquidPlanner.
This article describes how to configure a self-hosted Active Directory Federation Services (ADFS) server to act as a SAML 2.0 identity provider (IDP). Once you’ve completed all of the steps in this article, you’ll then need to configure SSO in LiquidPlanner.
To use ADFS to log in to LiquidPlanner, it’s imperative that you work closely with your IT team to ensure all of the following:
- An Active Directory instance has been set up, where all users have an email address attribute and the email address is the same as their LiquidPlanner account.
- ADFS service has been fully installed and configured.
- You have a SSL certificate to sign your ADFS login page and the fingerprint of that certificate. (Also known as the SHA1 fingerprint of the SAML certificate or the certificate file (.crt) from your SAML server.)
- You know your ‘SAML 2.0/W-Federation’ URL (found in ADFS Endpoints). If your IT team used the defaults for the installation, this will be ‘/adfs’. (Also known as the Remote Login URL for your SAML server and sometimes called SAML Single Sign-On URL.)
- You have a LiquidPlanner workspace with the SSO feature enabled.
Setting up Single Sign-On using Active Directory with ADFS and SAML 2.0
Microsoft provides ADFS as a standard service for Windows Server that enables web login using existing Active Directory credentials.
To use ADFS to sign in to LiquidPlanner, you need the following:
- An Active Directory instance where all users have an email address attribute.
- A fully installed and configured ADFS service.
- A LiquidPlanner workspace with SSO capabilities.
- A LiquidPlanner configuration metadata xml file (optional)
- A server running Microsoft Server 2012 or 2008.
- An SSL certificate to sign your ADFS login page and the fingerprint of that certificate.
- Know your ‘SAML 2.0/W-Federation’ URL (found in ADFS Endpoints). If you chose the defaults for the installation, this will be ‘/adfs’.
Step 1 – Adding a Relying Party Trust
At this point, you should be ready to set up the ADFS connection with LiquidPlanner using a Relying Party Trust (RPT).
- Login to the ADFS Server
- Launch the ADFS Management Console
- On the left hand tree view, select “Relying Party Trusts”
- Right click and select “Add Relying Party Trust…”
- Select the Relying Party Trusts folder from AD FS Management, and add a new Add Relying Party Trust from the Actions sidebar on the right.
- On the Select Data Source screen:
- If you downloaded the LiquidPlanner configuration metadata xml file, select the second option: Import data about the relying party from a file.
- Click “Browse” and select the LiquidPlanner configuration metadata xml you saved.
- If you did not download the file, select the last option: Enter data about the relying party manually.
- On the next screen, enter a Display name that you will recognize in the future.
- If you imported data about the relying party from a file, go to step 13 of these instructions.
- On the next screen, select: AD FS profile.
- On the next screen, leave the defaults.
- On the next screen, check the box labeled: Enable support for the SAML 2.0 WebSSO protocol.
The service URL will be: http://app.liquidplanner.com/[LPspace_id]/auth/saml/callback
Note that there’s no trailing slash at the end of the URL. The LPspace_id is your workspace ID number, which can be found in LiquidPlanner by going to your User Menu > Settings > Workspace Summary.
- On the next screen, add a Relying party trust identifier named https://app.liquidplanner.com/[LPspace_id] and click “Add”.
- On the next screen, leave the defaults.
- On the next screen, select: Permit all users to access this relying party.
- On the next 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 exists, you can create the claim rules and update the Relying Party Trust with minor changes that are not set by the wizard.
- By default the Claim Rules editor opens once you created the trust.
To create a new rule, click on Add Rule.
- Select: Send LDAP Attributes as Claims rule.
- On the next screen, using Active Directory as your attribute store, do the following:
- From the LDAP Attribute column, select E-Mail Addresses.
- From the Outgoing Claim Type, select E-Mail Address.
- Click on Finish or OK to save the new rule.
- Create another new rule by clicking Add Rule.
This time, select: Transform an Incoming Claim as the template.
- On the next screen:
- Select E-mail Address as the Incoming Claim Type.
- For Outgoing Claim Type, select Name ID.
- For Outgoing Name ID Format, select Email.
- Leave the rule to the default of Pass through all claim values.
- Finally, click OK to create the claim rule, and then OK again to finish creating rules.
Step 3 – Adjusting the Trust Settings
Some settings on your Relying Party Trust will need to be adjusted. To access these settings, select Properties from the Actions sidebar on the right while you have the Relying Party Trust selected.
- In the Advanced tab, ensure the selection is: SHA-256.
- In the Endpoints tab, click on add SAML to add a new endpoint.
- For the Endpoint type, select SAML Logout.
- For the Binding, choose POST.
- For the Trusted URL, create a URL using:
- The web address of your ADFS server.
- The ADFS SAML endpoint you noted earlier.
- The string ‘wa=wsignout1.0’
- Leave the Response URL blank.
The Trusted URL should look something like this: https://sso.yourdomain.tld/adfs/ls/?wa=wsignout1.0
Step 4 – Configuring for use with LiquidPlanner
After setting up ADFS, you need to configure your LiquidPlanner workspace to authenticate using SAML 2.0.
Follow the steps in the documentation for enabling SAML 2.0.
Use your full ADFS server URL with the SAML 2.0 endpoint as the SSO URL, and the login endpoint you created as the logout URL. (This could be anything but the default for ADFS is the following: https://”yourdomain”/adfs/ls/)
The fingerprint will be the fingerprint of the token signing certificate installed in your ADFS instance. (In the Windows certificate utility, this is also referred to as the SHA-1 Thumbprint.)
You should now have a working ADFS SSO implementation for LiquidPlanner.
Configuring SSO in LiquidPlanner
Now that your ADFS SSO implementation is set up, you’ll need to follow just a few more steps to configure SSO in your LiquidPlanner workspace. Start with Step 1 in the help article below: