This guide will walk through the steps needed to configure ADFS with Litmos. Following the steps outlined in this article, you will be able to configure Litmos as an SP with ADFS using the Relying Party Trust Wizard. The total time estimated for this configuration is about 25-50 minutes.
Important Note: SSO Integration is not compatible with Custom Domains.
Section 1 - Get your Litmos SSO Endpoint (we will come back to this when building SP Metadata in the next section):
1) Sign in to your Litmos account with an Account Owner profile.
2) Click the wrench icon to access "Account" settings. If you do not see this icon, you are not signed in as an Account Owner.
3) Click "Integrations" and scroll down to "SAML 2.0".
4) If you see only 1 text area, you are in the right place. Save the Litmos endpoint displayed in red, we will need this in section 2 of this guide.
5) If you see an Origin URI and x.509 certificate option, disable SAML, click save, and navigate back to SAML settings. You should see the empty metadata text area.
6) The litmos endpoint should look like "https:/[domain].litmos.com/integration/splogin"
Section 2 - Create SP Metadata to import in ADFS
- Begin by going to the following URL: https://developers.onelogin.com/saml/online-tools/build-metadata/sp
- Add your Litmos Endpoint to the “EntityId” and “Attribute Consume Service Endpoint (HTTP-POST)” fields.
- Keep all other settings as their default values. The EntityId and ACS values are the only fields that should be filled.
- Scroll to the bottom of the page and click “Build SP Metadata”
- Copy the generated metadata to a text file.
- Name the file "LMS_SP_Metadata.xml" and save it to a preferred folder on your machine. We'll need this file on step 7 of section 3.
- In the SP Metadata above, make sure you confirm the ValidUntil date is updated to a future date to avoid any issues with SSO. We can manually update the Validuntil date and use it for integration.
Section 3 - Add Litmos as a Relying Party to ADFS
- Open your AD FS Management tool.
- Click "Trust Relationships” to populate the Relying Party Trust tree, then click “Relying Party Trusts”.
- Now we will add a relying party trust. On the right hand side by clicking “Add Relying Party Trust...”
- Click “Start” to begin the Relying Party Trust Wizard.
- Choose "Import data about the relying party from a file".
- Navigate to the SP metadata that you generated earlier by clicking "Browse".
- Name your Relying Party Trust, and add a quick note if possible.
- Choose whether you’d like to configure Multi-factor Authentication and click “Next”.
- Choose who can access this Relying Party Trust, then click “Next”.
- Review the Identifiers tab to confirm it shows your Litmos url ending with “/integration/splogin”
- Review the Endpoints tab to confirm it shows your Litmos url ending with “/integration/splogin”
- Confirm configuration and click “Close”.
- This will launch the “Claim Rule” settings.
- Click “Add Rule” to edit the Claim Rules for your party trust.
- Once the “Add Transform Claim Wizard” dialog appears, choose “Send LDAP Attributes as Claims” and click "Next".
- Copy the following mapping. Please note, the Outgoing Claim Type is case sensitive.
*Name ID will be the Litmos username. You can map any attribute from your LDAP as the user's username. If you are unsure which attribute to choose, we recommend "E-Mail-Addresses" LDAP attribute of the user to be used for Name ID.
Please Note: If Name ID is an attribute other than 'E-Mail-Addresses' (eg sAMAccountName), please ensure that you select the 'Autogenerate Users' option mentioned below in Section 4 - Step 10.
- Once finished, please click “Ok” to save changes.
Section 4 - Adding your ADFS IdP Metadata in Litmos
Once Litmos is added as a Relying Party in ADFS, we need to let Litmos know which IdP to accept when a POST assertion is made. If you are familiar with how to obtain your ADFS federated metadata, you can skip steps 1-6 in this section.
- Open your AD FS Management tool.
- Click "Services" to populate the services options.
- Click "Endpoints" to populate the list of available Endpoints for your AD FS.
- Scroll down to the "Metadata" section.
- You can obtain your ADFS metadata by appending the URL path of the "Federation Metadata" to your ADFS base URL, e.g. "https://your.adfs-domain-url.com/FederationMetadata/2007-06/FederationMetadata.xml"
- Copy the metadata. If the metadata saved to your computer automatically, please open the file and copy its content to your clipboard.
- Proceed to your Litmos account and sign in as an Account Owner.
- Click the wrench icon to access "Account" settings.
- Click the "Integration" tab and scroll to "SAML 2.0" settings.
- Paste the metadata into the metadata text area of your Litmos SAML settings. (*ensure the first line of the XML starts with "<EntityDescriptor..." and not "<?xml version="1.0" encoding="UTF-8"?>").
- Click "Save changes" to confirm the changes. If you see an "Oops" error, your XML is not formatted correctly. Please use an XML formatter and try again. Google search for XML Formatter, here.
- Log out of your Litmos account so that we can test the connection.
- Access your ADFS IdP Sign In Page to sign into the Relying Party we configured in section 3.
Section 5 - Sign in through ADFS
You are now ready to sign in, the IdP initiated login link for your ADFS should look similar to the following with your specific supplied domain name: