Using SAML 2.0 with any 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 see the setup required in Litmos:
- Add the Metadata.xml from IdP provider
- Ensure the Litmos endpoint being used to integrate SAML with is:
This endpoint supports:
- Can pass TeamID with the assertion to assign users to a team upon user creation. (TeamID attribute is case sensitive.)
- Can pass RelayState as part of the SAML assertion
It's relatively easy to implement on the Litmos side, as all that is needed is metadata.xml from IdP
Important Note: SAML 2.0 setup with an IdP is not compatible with custom domains.
The IdP Configuration
Depending on your IdP’s requirements, you will need to provide different pieces of information. However, in most cases manually configuring an SP will have the necessary data needed to make a successful SAML assertion.
Destination: The destination URL will be your Litmos URL. Since you are using “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".
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">
<saml2:Attribute Name="Email" NameFormat=“urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified">
The following attributes can be passed through the SAML assertion:
FirstName, LastName, Email, TeamID, RelayState
The casing on the attributes are very important. Any misspelled or an incorrect casing may result in a failed assertion.
Logging in to Litmos will need to take place from an IdP initiated Sign-On URL. Litmos support can setup a URL redirect on your Litmos login URL so anytime a user is not signed in, they will be sent to the IdP login page. Furthermore, if you plan on allowing some users to sign in natively to Litmos, while wanting the rest of your users to sign in using SAML, you can add the IdP URL as a link on your Litmos home page. To add this link on your home page, please see the following steps:
- Sign in as an Account Owner.
- Click the wrench icon to access “Account” settings.
- Navigate to the “Messages & Settings” tab, and add your desired HTML code to the “Login” box. A template is shown below:
<a href="IDP_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.