THIS FEATURE REQUIRES A BUSINESS PLAN
Please note that single-sign-on (SSO) is only available on Business plans. This feature is not available on smaller plans (such as Lite). 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 ADFS 3.0 and have established it as your Identity Provider. These instructions should also work with ADFS 2.0.
Please note that there are sometimes unique characteristics of your ADFS infrastructure which may require some changes from the below procedures, however, we have found the following procedures work with the majority of ADFS 3.0 environments.
1 - Obtain your Tribal Habits SSO URL
Log in to your Tribal Habits portal as a Super Admin and navigate to Admin → Account → Security, then click "Manage" next to "Enable SAML Single-Sign-On (SSO)". Your SAML SSO URL will be located in the Identity Provider Config panel. It is typically https://yourorganisation.tribalhabits.com/saml/auth.
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.
2 - Add Tribal Habits as a relying party trust in ADFS.
Select the Relying Party Trusts folder from ADFS Management, and add a new Standard Relying Party Trust from the Actions sidebar. This starts the configuration wizard for a new trust.
In the Select Data Source screen, select the last option, Enter Data About the Party Manually.
On the next screen, enter a Display name (Tribal Habits) that you'll recognise in the future, and any notes you want to make.
On the next screen, leave the certificate settings at their defaults and proceed to the next screen.
Check the box Enable Support for the SAML 2.0 WebSSO protocol. In the box for the SSO service URL, enter your Tribal Habits SSO URL which we obtained in step one.
On the next screen, select your relying party URL.
On the next screen for access control, select 'Permit everyone'.
On the next two screens, the wizard will display an overview of your settings. On the final screen, use the 'Close' button to exit and open the Claims rule editor.
3 - Creating your claim rules
Once the relying party trust has been created, you can create the claim rule. By default the claim rule editor opens once you created the trust. Start by clicking 'Add Rule' and then create a 'Send LDAP Attributes as Claims' rule.
On the next screen, using Active Directory as your attribute store, add your claim rules for Tribal Habits.
First, create outgoing claims for...
FirstName -> Your matching LDAP attribute (like Given Name)
LastName -> Your matching LDAP attribute (like Surname)
Email -> Your matching LDAP attribute (like Email Address)
Second, select the LDAP attribute which is the unique identifier in your organisation. This will be used as the UserName in Tribal Habits - the unique identifier for each user. We recommend using a fixed identifier where possible, such as an employee ID, rather than email address. See our main SSO article for why this matters. In any case, map your selected LDAP attribute to an outgoing claim called TEMP (as we will transform this attribute claim in the next rule). Then save that claim, which should look something like this.
Now add a second claim rule. This time using the template 'Transform an incoming claim'.
In this claim, we are going to transform your chosen unique identifier (email or employee ID, or whatever attribute to mapped to TEMP.
For incoming claim type, select TEMP.
For Outgoing claim type, select Name ID.
For Outgoing name ID format, select Transient Identifier.
Leave Pass through all claims as the default.
Then save this second claim.
4 - Adjust the trust settings
You still need to adjust a few settings on your relying party trust. To access these settings, select Properties from the Actions sidebar while you have the RPT selected. In the Advanced tab, make sure SHA-1 is specified as the secure hash algorithm.
Apply those changes and move to the Endpoints tab. Click on add SAML to add a new endpoint. For the Endpoint type, select SAML Assertion Consumer. For the Binding, choose POST. For the Trusted URL, ensure your Tribal Habits SSO URL back in Step 1 is correct.
5 - Configure Tribal Habits
Now we are ready to configure Tribal Habits. Go back to Admin → Account → Security in Tribal Habits and open your SSO settings via "Manage". You then need to obtain specific information from your ADFS set-up.
For Identity Provider Entity ID, enter your Issuer URL. This will be something like http://identityproviderurl.com/adfs/services/trust.
For Identity Provider SSO URL: enter your Single Sign On service endpoint. This will be something like https://identityproviderurl.com/adfs/ls
You then need to obtain and enter your Identity Provider x.509 Certificate.
Update your SAML Configuration and you should be good to go.
Before you go live
Once SSO is working, review the Authentication settings in Admin → Account → Security, covered in our main SSO article. In particular, decide whether to prevent auto-provisioning of new users via SSO, since any HR sync or identity management integration should usually create and populate users before their first SSO login.
If you run into problems, see our troubleshooting article for common SSO errors and fixes.