Set-up Single-Sign-On (SSO / SAML) with Azure AD and Tribal Habits

THIS FEATURE REQUIRES A BUSINESS 50 PLAN OR LARGER

Please note that single-sign-on (SSO) is only available on Business 50 or larger plans. This feature is not available on smaller plans (such as Lite) or legacy plans (older monthly plans). Please contact our team at [email protected] if you would like access to this feature but it is not activated in your portal.

We assume you have a working understanding of Azure AD / Microsoft Entra and have it established as your identity provider.

1 - Obtain your Tribal Habits SSO URL

Note: If you get into trouble with your SSO set-up, you can always access your Tribal Habits portal at yourdomain.tribalhabits.com/accounts/sign_in_without_sso using your normal Tribal Habits login credentials. You may need to do this if your SSO is misconfigured.

Navigate to Admin → Accounts → SSO. Look for the Identity Provider Config panel at the end of that page. You will need the SSO URL and Log Out URL later.

2 - Set up Tribal Habits as an Enterprise application

Create a new Enterprise Application for Tribal Habits. In Azure Ad / Microsoft Entra, select Applications → Enterprise applications and then + New application.

Then select + Create your own application and name your application (something like Tribal Habits LMS).

3 - Enter Basic SAML Configuration

Select your new enterprise application, then Single sign-on and then SAML.

Edit the Basic SAML Configuration panel on the Single sign-on tab. You need to copy in three URLs from your Tribal Habits portal from step 1 in this process. The SSO URL goes into Identifier (Entity ID) and Reply URL. The Log Out URL goes into Logout URL.

4 - Enter the User Attributes and Claims

We now need to create four claims. Stay on the Single sign-on page in the the enterprise application and edit the second panel called Attributes & Claims.

There are two parts.

First is the Required claim, which will have the Unique User Identifier (Name ID). You need to edit this value and select the data you wish to send for the UserName field in Tribal Habits. We recommend using a fixed identifier where possible - like a user ID number or employee number. If possible, avoid using email, since email addresses can change over time and this field should ideally never change for the user. Your IT team can advise about the best field in Azure Ad / Microsoft Entra for this.

Note: If you have some existing users in Tribal Habits, then you may need to edit their Username fields to match whatever field you select for UUI (Name ID) in Azure AD / Microsoft Entra. If not, the claim will not match for the existing users and you will likely receive a 'Duplicate user error' when trying to login as one of those users. So check the existing users in Tribal Habits and their Username field to ensure it is correctly populated with data matching the field for UUI (Name ID).

Second are the Additional claims. We required three additional claims. You can delete any default claims and then use the + Add new claim button to add three new claims.

Note: Ensure you spell all the Names and Values correctly. Exactly as below with the same capitalisation.

Claim Name: Email
- Value: The field which has the user's email address in Azure Ad / Microsoft Entra. This may be user.email or may be user.primaryauthoratativeemail or something else.
Claim Name: FirstName
- Value: The field which has the user's first name. Likely to be user.givenname.
Claim Name: LastName
- Value: The field which has the user's last name. Likely to be user.surname.

You can leave all other settings as default in most cases. Your claims should look something like this.

5 - Save the SAML Signing Certificate

Now you need the SAML Signing Certificate. Save the Base 64 Certificate. Go to step 3 in the Single sign-on page in Azure Ad / Microsoft Entra and download the Base64 certificate.

Open the downloaded CER file in a plaintext editor. It will start with -----BEGIN CERTIFICATE-----, then have a long randomised set of characters, and then end with ----END CERTIFICATE-----.

Copy the entire file, including the BEGIN and END parts, to back to Tribal Habits and into Admin → Accounts → SSO. Now edit the Settings panel and enable SSO.

Then paste the entire certificate into the space for the certificate.

6 - Add the Identity Provider information

Final step! Now we need to copy the URLs in step 4 of the Azure AD / Microsoft Entra Single sign-on process to the matching fields in your Tribal Habits SSO page.

Login URL → Identity Provider SSO URL
Azure AD Identifier / Microsoft Entra ID Identifier → Identify Provider Entity ID
Logout URL → Identity Provider SLO URL

Save your SSO settings in Tribal Habits and you should be ready to test. Logout from Tribal Habits and reload the login page. The SSO process should start from here.