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 setup 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 see the setup required for the first IdP connection in Litmos:

1. Go to Account Settings
2. Click on "Integrations"
3. Click on "SAML 2.0 (Single Sign On)"
4. Add the Metadata.xml from your IdP provider
5. Ensure the Litmos endpoint being used to integrate SAML with is:

     “…/integration/splogin”

Add an Additional SAML 2.0 SSO Identity Provider (IdP)

IdP initiated SAML SSO can now be configured for two separate identity providers enabling organizations to SSO unique sets of users from different providers with ease.

The additional IdP endpoint will be listed as Idp1. 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 the second IdP connection.

Below are the steps to add the additional IdP:

1. Go to Account Settings > Integrations > SAML 2.0 (Single Sign On)
2. Click on the ‘Add Additional IDP’ button. Enter the XML metadata in the pop window and then click on ‘Add New IDP’
3. Return to see a drop down with the 2 IDP connection – IDP 0 and IDP 1. Select to view the specific connection
4. IDP 1 can be deleted by clicking on ‘Delete this IDP’.

Important note :

1. It is recommended there is only one identity provider per user profile. Users that require more than one profile should have two logins.
2. 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.
3. 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:

1. SHA-256
2. Passing the TeamID attribute in the assertion to assign users to a team upon user creation. The TeamID is found in the Team settings and is the numbers (Ex:1383512) before "-TeamName". (TeamID attribute is case sensitive.)
3. Passing a RelayState parameter as part of the SAML assertion for deep-linking
4. 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:

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. 

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:

1. Sign in as an Account Owner.
2. Go to “Account Settings"
3. 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.
4. Scroll to the bottom of the page and click “Save” to store your changes.
5. Next time you logout of your Litmos account, you will see the message appear in the login box.