Skip to main content

Single Sign On (SAML 2.0)

Updated

Single Sign On is an authentication method that allows users to authenticate to many different services with a single set of credentials. Truework supports setting up Single Sign On using the SAML 2.0 protocol.

This document is written for IT administrators to enable the setup of Single Sign On for your Truework team.

Before you begin

  • You must have administrative access to your Truework account

  • You must be able to set up a new application in your Identity Provider

  • We have vendor-specific documentation available for Okta and OneLogin, which may provide more specific information on how to get set up for your particular vendor.

  • Note: Enabling SSO for your account will prevent users from logging in with their Truework username and password.

Terminology

SAML is, unfortunately, full of slightly different names that refer to the same concepts or values. We’ve done our best to choose the most standard name for each value or concept and provide that mapping here.

  • IDP - The Identity Provider (IDP) is a service, such as Okta, One Login, Google Workspace, or Azure AD that acts as the source of truth for authentication information for your users.

  • SP - A Service Provider (SP) is the name for the application that the user wants to sign into. In this case, it’s Truework!

  • ACS - Assertion Consumer Service. Sometimes also called the Single Sign On URL. This value is unique for each customer and must be retrieved from the SAML settings in your Truework account.

    • At Truework, this same URL is both the Recipient and the Destination address. You probably won’t need to know this, but just in case you do.

  • Entity ID - Sometimes also called the Audience URI when referencing SPs or Issuer when referencing IDPs. This allows the IDP and the SP to identify with one another. Truework's SP Entity ID is https://sso.truework.com/

  • x509 Certificate - A cryptographic certificate, typically beginning with -----BEGIN CERTIFICATE-----, that is used to sign requests between the IDP and the SP. Your IDP should give you a certificate that you provide to Truework.

  • Name ID Format - This is the name that the IDP provides Truework to identify a user. This must be set to EmailAddress, and the values sent to Truework need to be email addresses.

  • Attribute Statements - Attributes allow your IDP to send additional data to Truework with each authentication. Verifiers may optionally send first_name and last_name attributes using one of the synonyms below, which we will automatically use to set users' names on first sign-on if they are available.

    • Accepted synonyms for first_name:

      • firstName

      • firstname

      • first_name

      • givenName

      • givenname

      • given_name

      • urn:oid:2.5.4.42

      • User.FirstName

      • http://schemas.xmlsoap.org/ws/2005/05/identity/claims/givenname

    • Accepted synonyms for last_name:

      • lastName

      • lastname

      • last_name

      • surname

      • sur_name

      • urn:oid:2.5.4.4

      • User.LastName

      • http://schemas.xmlsoap.org/ws/2005/05/identity/claims/surname

  • SAML Bindings: SAML Bindings refer to the way the IDP and the SP talk to one another. At this time, Truework supports the HTTP-POST binding.

Supported Features

Truework’s SAML implementation supports a limited set of features, outlined here.

  • IDP-initiated SSO - Login to Truework directly from your IDP.

  • SP-initiated SSO - Login to Truework by visiting app.truework.com and entering your email address, which will redirect you to your IDP.

  • Create Users - In limited scenarios, Truework will create new users automatically upon their first sign in attempt. For our HR customers, employee users are created automatically using the employee records we have on file. For our verifier customers, a new user will be created upon successful login after being invited to a team.

Procedure

  1. Login to Truework as an administrator

  2. Go to your team settings page

  3. Under team settings, you can enable Single Sign-On, which will pop up a new modal.

  4. From the SAML modal, take the information generated by Truework to your IDP and set up the application. This process will look different for each vendor, however, we do provide vendor-specific documentation for a couple of popular vendors.

    1. You’ll need to copy the ACS URL and the SP Entity ID over to your IDP and make sure that the Name ID Format is set to EmailAddress. You may also need to specify that you need to use the HTTP-POST SAML Binding.

  5. Once you’ve set up the application in your IDP, you should be given a Single Sign On URL, an Entity ID, and an x509 Certificate. These values will need to be copied into Truework’s SAML Settings form. This is the same form that provided you the information necessary in step 4.

  6. Save your settings in Truework to enable SSO authentication for your Truework team.

  7. While still logged in as your administrator user, it is advised that you open another browser or an incognito window and ensure that logging into Truework from your IDP correctly logs you into Truework. Doing this in another browser will help ensure that if something is wrong, you are able to still access your account in your primary window.

  8. Once you’ve verified that logging into Truework from your IDP works successfully, you’ve successfully completed setting up SAML for Truework!

Unsupported Features

In order to provide the most clarity about what we do and don’t support, we thought it would be helpful to include a list of some of the more common features that we don’t currently support. If you want or need one of these features, or other features not listed here, please let us know!

  • Single Log Out

  • SCIM

  • Update User Attributes

  • Deactivate Users

Known Caveats

Entra Audience Entity ID Uniqueness

Audience: Entra administrators for companies with more than one Truework Team.

Microsoft's Entra requires that each application in a given tenant has a unique Entity ID when setting it up (as seen in the picture below). This can cause problems for organizations with more than one Truework Team using SSO, as Truework only has a single Entity ID - "https://sso.truework.com/".

Screenshot 2024-11-29 at 10.12.46 AM.png

In order to account for this, Entra is aware that some applications (such as Truework) may not provide a unique Entity ID for different resources within the application. They have some documentation on how to configure "App Multi-instancing" that calls this out and mentions an "Override Audience Claim" option that can be used to account for this. 

When setting up the application for a team, set the Entity ID to something like "https://sso.truework.com/2" or "https://sso.truework.com/teamidentifier". Just make sure it's unique among your other Truework applications. Then in the "Attributes & Claims" section of the SSO configuration for the app, under "Advanced SAML claims options" make sure to set "Audience Override" to "https://sso.truework.com/" as seen below.

 

Screenshot 2024-11-29 at 10.18.43 AM.png

Related articles