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.
Majority of the configuration will be done on the IdP server, with very little information needed in Litmos. Below you can see a list of thing you need to add to Litmos:
- Metadata.xml from IdP provider
- Origin URI (This is the SP specific URL from your IdP - usually available once an SP has been added to your IdP)
- x.509 certificate
Litmos has two endpoints which you can integrate SAML with. Below is a description of each endpoint:
- Can pass TeamID with the assertion to assign users to a team upon user creation. (TeamID attribute is case sensitive.)
- Easier to implement as all that is needed is metadata.xml from IdP
- Can pass RelayState as part of the SAML assertion
- This is a legacy endpoint that uses SHA-1 certificate(not recommended)
- Requires Origin URI
- Requires x.509 certificate
- Can’t pass TeamID
- Does not accept RelayState with the assertion
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. If 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". If you are using the “integration/samllogin” endpoint your destination will be “https://domain.litmos.com/integration/samllogin"
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">
Attributes that can be passed over using SAML are as follows:
FirstName, LastName, Email, TeamID, RelayState
The casing on the attributes are very important, and a misspelled, or an incorrect casing may result in a failed assertion.
Loggin 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.