Using SAML 2.0 SSO with an Identity Provider (IdP)
If you are using SAML with an IdP that has not been documented (Okta, OneLogin, ADFS, Azure), you can still integrate with Litmos by following the general steps required to configure SAML 2.0.
The majority of the configuration will be done on the IdP server, with very little information needed in Litmos. Below you can follow the steps required for the first IdP connection in Litmos:
- Go to Account Settings
- Click on “Integrations”
- Click on “SAML 2.0 (Single Sign On)”
- Add the Metadata.xml from your IdP provider
- Ensure the Litmos endpoint being used to integrate SAML with is: “…/integration/splogin
- Check if your IdP supports encrypted assertions.
If so, enable them within the IdP configuration, and enable “Verify assertion encryption” in the SAML tile in Litmos. If your IdP supports assertion
The SP metadata for this feature can be download by selecting “Click here to download service-provider SAML metadata (expires on Month, Date, Year)”.
The public key used for this feature can also be found below:
-----BEGIN CERTIFICATE----- MIIFETCCAvmgAwIBAgIUOCrlbfq3jcNUukERzGeQLpHbieowDQYJKoZIhvcNAQEL BQAwGDEWMBQGA1UEAwwNZ28ubGl0bW9zLmNvbTAeFw0yMDEwMjExNzAwMTdaFw0y MjEwMjExNzAwMTdaMBgxFjAUBgNVBAMMDWdvLmxpdG1vcy5jb20wggIiMA0GCSqG SIb3DQEBAQUAA4ICDwAwggIKAoICAQChZDbToFyefgkquw/CvgvtzM7TjCewJRkO oLI37edkfrUaXjudNlV0E4ovPsgpYrTDH7Iq4LLQpKOGNwnfi4/+v3tsNCfuLzBL 6pxUPjrWiuxRM6TeUNxn/pZuCjYJ+I8E6em94OF39SzAaqG4zp/wVpoJ1xpAqIUv Jjhl/RdxXUSCnujfNtKek2ecpMWiMAPL4wA5gq/dUd8uNpClPOqDrhzS8ugDZ0ne ttYLE55HE0/WYrp5jgKsz+0ghh9FWClw+B9rch1d0qztrnair27m6MYoxITgMLYd n4T6sJgJMN/8b7w83NKKfNDbAySTKayhLo4SfIYr9sQiFAgUqj4qrwsh1S/TYIiL y/Nnpm+XuM2941QHpAoDdro7kyBueSXNC1Gg8U2Bcu6/IzbCVgY9xCE2ny+1XvbX V5VO4QxtcTdIjwcJwSF5VNStf02YcA6AfOqLT4+5kvC8nBND5wqkR/wc6JgqeGYY NVNh+ExCZELXnWIdmJDrumX6rnFq9o/LkdaX5hyZVyI2PFqHrqwoDSBgf0XJF9Aa vVYTMQ1NndeaGqkK5deuw4avuQwks9x11EsI8sLv0d8+FJNC21yNEFN07kuOwMxB m2ntzFyaWmPajSCwHdSdJF8MQfY3B/I1r5tLWG16DdMHdaSyiPBS53BLH56uWVjl cHlnbF69rwIDAQABo1MwUTAdBgNVHQ4EFgQUfaeHFNsXhgt0I4iD0Rxsu/LRHQow HwYDVR0jBBgwFoAUfaeHFNsXhgt0I4iD0Rxsu/LRHQowDwYDVR0TAQH/BAUwAwEB /zANBgkqhkiG9w0BAQsFAAOCAgEAComDZ1ZwuwK43KP8rdBW1Vs3kEjNYsfnLbAH NnprIW3ekN50D/xMCyovs593sNhf/CTpflXWMm07AToN5EinICsUBcXOqd16bZE7 Arcj/aG8ch8Gx7SuR53aAzposiFcAnXf6Fpi3V7K4nAZX67qT1qwl9D7ZuCA9Cb7 /XrXGMtJ4qUA5/rZKzy1v7m7OhK05HjAoM6xIwUKV+xR8+y//7FeiT5MSxJdlbmW zqynAiXe/IDsiYKDQe2MeAPao+GnrItvETHGkmIAyDZPioAq2pVJrnl4v34e9ud7 n+tLKlaPlEMHXeKjdkOl+VutN7nkOBAs7lug4WQleflZH+nsoH8paV4dhfie6Hh/ gYb88ezp6cfLuQW/+7QtVuquyPQscNZqgrc22Olwkdgvuw7pZKc2m0118HRkuZmV +DlmQ8qVOrnSszlcxiO5KS4WedA7NIq/mkDHjH8+oqg7WVtofCHLDPO/+zKCFrh5 Wga04WbGRWKTz1YX6UWxT7q7L996Mag9Bm8IL8AmJ9jkzHGSsx93AzC/Gnfq4bsS k/gsA8xauzHnSaV/xtPGApMG4Ldvoh1YuSy4pn+iKvBSJveIXWVClgsoYbsrUIuS V3bego9WuZEXJaP1BKcbgUC62czdoa/V2ujLNR/9LOm34YkuNkZf93ELOevCjYWV bkRN2FM= -----END CERTIFICATE-----
Note: If your IdP supports encrypted assertions, we strongly recommend you that you enable ‘Verify assertion signatures’ and use the Litmos Public Key to ensure the highest level of security for your SAML assertions.
If you are not sure about your IdP’s capabilities, please reach out to their support team to confirm.
Important Note: If your IdP doesn’t support encrypted assertions, make sure “Verify assertion encryption” is unchecked or you will encounter an error when attempting to login to Litmos.
If your IdP supports encrypted assertions, but you are encountering an error when “Verify assertion encryption” is enabled, please ensure you are using the Litmos Public Key mentioned above in Step 6.
Enabling Service-Provider (SP) Initiated Single Sign On from Litmos
The service-provider initiated SSO flow from Litmos is designed to redirect a user’s SAML login request from the service provider to an Identity Provider (through the browser), where the user’s identity is recognized, verified, and granted access to the service provider.
To enable this flow, click the setting “Enable Service Provider Initiated Single-Sign On from Litmos” for the IdP record and then fill in the corresponding details:
- IdP Descriptor (What a user reads and clicks to gain access to the Identity Provider….i.e. “Customer SSO Portal)
- IdP Login URL (The identity provider, where the user will be redirected from the Litmos Login Page)
- IdP Logut URL (The identity provider designated page where a user lands after logging out of the target application).
- IdP Image (A logo or icon that is associated to the IdP portal).
Important Note: As with the IdP initiated SAML login, the SP initiated SAML login flow requires the identity provider system to obtain a copy of the service provider’s metadata. Therefore, you will need to “Click here to download service-provider SAML metadata (expires on Month, Date, Year)”. The metadata that is downloaded will need to be uploaded or entered into the Identity Provider system for the service provider record created for Litmos as a target system for single sign-on.
Once this has been enabled and saved, the Litmos account login page will display a new button titled, “Login with SSO”:
When an end-user clicks on this button, he/she will see a pop-up with a prompt “Login to your Account”. Below will show one or more Identity Providers (depending on which IdP records are enabled for sp-initiated login in the customer Litmos account). The end user can attempt to initiate SSO using one of the listed identity provider records listed on the page.
Add an Additional SAML 2.0 SSO Identity Provider (IdP)
IdP initiated SAML SSO can now be configured for 15 separate identity providers enabling organizations to SSO unique sets of users from different providers with ease.
The additional IdP endpoint will be listed as Idp 1, Idp 2, Idp 3, ect. The additional IdP can be added and deleted as needed without affecting the existing, original IdP connection. Ensure you add valid SAML metadata XML before adding an additional IdP connection.
Below are the steps to add the additional IdP:
- Go to Account Settings > Integrations > SAML 2.0 (Single Sign On)
- Click on the ‘Add Additional IDP’ button. Enter the XML metadata in the pop window and then click on ‘Add New IDP’
Important! Remove the following line if it appears in the first row of the SAML Metadata you entered:
<?xml version=”1.0″ encoding=”UTF-8″?>
- Litmos will generate an error if it is included in the SAML Metadata
- Return to see a drop down with the IDP connections: IDP 0 – IDP 15. Select to view the specific connection
- An IDP can be deleted by clicking on ‘Delete this IDP’.
Important note :
- It is recommended there is only one identity provider per user profile. Users that require more than one profile should have two logins.
- If the same user connects from both IdPs with same credentials, information will be created based on the first IdP connected and updated based on the most recent connection.
- SAML endpoints for each of these IdP configurations is slightly different, but the configuration requirements are identical.
Endpoint for IdP 0 – https://domain.litmos.com/integration/splogin
Endpoint for IdP 1 – https://domain.litmos.com/integration/splogin?idp=1
The Litmos SAML endpoints supports:
- SHA-256
- Passing the TeamID attribute in the assertion to assign users to Teams upon user creation with “Auto-generate Users”. The TeamID is found in the Team settings and is the numbers (Ex: 1383512) before “-TeamName”(TeamID attribute is case sensitive). Multiple Teams can be assigned by separating their IDs with commas (12345, 678910, 111213, ect…)
- Passing a RelayState parameter as part of the SAML assertion for deep-linking
- Auto Generating/Auto Provisioning of users upon the SAML assertion if a matching user does not exist in Litmos and the checkbox for “Autogenerate users” is marked.
Important Note: The <Createdby> value for users created through this process will be the ID of the most recent Account Owner to click “Save Changes” on the SAML 2.O Integrations tile. This ID value will not change until a new Account Owner clicks the “Save Changes” button even if the original profile is deactivated, demoted or deleted**
It’s relatively easy to implement on the Litmos side, as all that is needed is the SAML metadata.xml from your IdP.
Important Note: SAML 2.0 setup with an IdP is compatible with custom domains as of June 21st, 2019.
The IdP Configuration
Depending on your IdP’s requirements, you will need to provide different pieces of information. However, in most cases manually configuring Litmos as the SP will have the necessary data needed to make a successful SAML assertion.
Destination: The destination URL will be your Litmos URL. If you are using the “/integration/splogin” endpoint and are providing your IdP metadata in Litmos, the destination URL will be your endpoint as well. For example, the full URL will be
“https://domain.litmos.com/integration/splogin” or “https://domain.litmos.com/integration/splogin?idp=1” depending on the IdP connection required.
Recipient: Apply your SAML endpoint for the recipient, as you have for destination.
AudienceRestriction: Apply your Litmos endpoint to this attribute, as well.
SAML attributes: SAML attribute statement can either be unspecified or basic format.
<saml:Attribute Name=”Email” NameFormat=”urn:oasis:names:tc:SAML:2.0:attrname-format:basic”>
OR:
<saml2:Attribute Name=”Email” NameFormat=“urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified”>
The attributes below can be passed and updated through the SAML assertion:
| Litmos Field | Data Type |
| FirstName | String |
| LastName | String |
| Title | String |
| CompanyName | String |
| PhoneWork | String |
| PhoneMobile | String |
| Skype | String |
| String | |
| Website | String |
| Street1 | String |
| Street2 | String |
| City | String |
| State | String |
| Country | String |
| PostalCode | String |
| CustomField1 | String |
| CustomField2 | String |
| CustomField3 | String |
| CustomField4 | String |
| CustomField5 | String |
| CustomField6 | String |
| CustomField7 | String |
| CustomField8 | String |
| CustomField9 | String |
| CustomField10 | String |
| TeamID* | String |
Important Note: The casing of these attributes is extremely important. Any misspelled word or incorrect casing may result in a failed assertion.
*TeamID is only processed when the profile is first created using “Auto-generate” users. After that, it is ignored. Multiple Teams can be assigned by separating their IDs with commas (12345, 678910, 111213, ect…)
Logging In using SSO
Logging in to Litmos will need to take place from an IdP initiated SSO URL. Litmos support can setup a SSO Login redirect on your Litmos login account so that anytime a user is not authenticated by SSO, they will be sent to the IdP login page. Furthermore, if you plan on allowing some users to login manually to Litmos, while wanting the rest of your users to login in using SAML SSO, you can add the IdP URL as a link on your Litmos login screen. To add this link on your Litmos login page, please see the following steps:
- Sign in as an Account Owner.
- Go to “Account Settings”
- Navigate to the “Messages & Settings” tab and add your desired HTML code to the “Login” box. section. An example HTML code for a simple hyperlink is shown below:
<a href="IDP_INITIATED_SSO_URL_HERE">Click here</a>to login using your network credentials. - Scroll to the bottom of the page and click “Save” to store your changes.
- Next time you logout of your Litmos account, you will see the message appear in the login box
Deep Link into a Course or Learning Path with SAML
Take advantage of the RelayState query param to redirect users to a specific page, or any other page in Litmos after a user has been authenticated.
In order to take advantage of this approach, your IdP must pass the RelayState parameter along with the rest of the SAML assertion. If you are unsure whether your IdP is passing the RelayState, check the URL address bar to confirm it is still present in the address bar after signing into your IdP, but before being redirected to Litmos.
The RelayState parameter must be appended to your Litmos IdP login URL. By itself, this URL will take you to the IdP sign in page where you will be asked to sign in using your AD credentials, and once authenticated will send you into Litmos. An example RelayState link can be seen below for a Course:
https://IdP-sign-in.your-idp.com/saml/idp/litmos?RelayState=https://domain.litmos.com/Course/12345
As seen in the example, the link above is compiled of two separate URL’s, brought together using the query parameter. First, we have the specific IdP URL in green where we specify Litmos’ sign in URL from the IdP. Again, this URL by itself should sign you into Litmos. The second portion highlighted in red notes the URL we want the user to be redirected into, once they are signed in.
Learning Path:
https://IdP-sign-in.your-idp.com/saml/idp/litmos?RelayState=https://domain.litmos.com/home/LearningPath/123456