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. 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
   6. Check if your IDP supports encrypted assertions, if so, enable them within the IDP configuration and check the "Verify assertion signatures and encryption" checkbox under the SAML tile in Litmos. The SP metadata for this feature can be download by selecting "Click here for SP metadata". The public key used for this feature can also be found below:

Note: We strongly recommend you do this 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. 

-----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-----

Important Note: If your IDP doesn't support encrypted assertions, make sure "Verify assertion signatures and encryption" is unchecked or you will encounter an error.

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:

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 IDP connections: IDP 0 - IDP 15. Select to view the specific connection
4. An IDP 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.