Please note that this information was correct as of 2nd November 2023 and Teamtailor is not responsible for any changes made within Azure. Any questions outside the scope of this article should be sent directly to Azure's support team.
Setting up SSO on a single account
To set up SSO on Teamtailor, the first step that you will need to take is to let our support team or your dedicated CSM know that you would like to go ahead with this. They will then activate it for you, and it will become available for you to set up in your Settings > Security > Single Sign-on (SSO). Note that this will need to be completed by a user with Company Admin access. Then, please follow the next steps below:
Go to your Azure Portal, then under Azure services, you'll find the option "Enterprise applications".
Create a new application, then select "Create your own application", give it a suitable name, then you can leave the default setting ticked for non-gallery, then click "Create".
3. Once your new application has been created, click "Set up Single on", select SAML, then you'll be presented with the following screen:
4. Your Identifier (Entity ID) and your Reply URL (Assertion Consumer Service URL) are the only required fields and can be found in your Teamtailor settings. In Azure, click "Edit" in the top-right corner of this step, then for each field, add the relevant URLs provided in your Teamtailor settings, then click Save.
5. Next, you'll need to add the App Federation Metadata URL, which is found under Step 3 SAML Certificates in Azure. Copy this value, then paste it into Teamtailor under the title "IdP Metadata xml URL."
6. In Teamtailor, click "Parse metadata". This will complete the setup on Teamtailor's side, so now you'll need to test that it's working as expected.
7. To test it, you'll first need to add the user to your Azure settings. On the left-hand side above Single Sign-on, click on "Users and groups", then "Add user/group". At this point of testing, we recommend adding one user as opposed to a group, so click on "None selected" under Users, and then add the email address that you'll use for testing, then Select, then Assign.
8. To test that it is working, head to your careers site, then scroll to the bottom where you'll have "SSO" listed in the footer.
9. Upon clicking SSO, you should be redirected to the page where you can enter your credentials. Once completed, you'll be directed to the homepage of your Teamtailor dashboard. If you are a new user, this will as a Default User, and if you are an existing user, this will be at the level that you were added as previously.
10. To complete the setup, you can add more users and groups on your side, then in Teamtailor, click "Enforce SSO", then your users will only be able to log in with SSO going forward. You can also ask our support team or CSM to add auto-join domains for you so that your team can log in via https://tt.teamtailor.com/en/login/sso instead.
Setting up SSO on a group account
When setting up a group solution, you'll need to ensure that you complete all of the steps above, making sure that on Teamtailor this is all set up on the "parent" account.
In Teamtailor, by default, if a new user logs in for the first time without having been added to any existing account previously, they will automatically be added to the parent account. To avoid this, you will need to send us an additional claim, which we can use to identify to which account the new user should be added.
To add a new claim, find your new enterprise account in your Azure portal, then click on Single sign-on. From here, it's the second box that you need to edit:
Click Edit, then "Add new claim". You'll then to have add a name, which could be anything, such as "country" or "company, or you could follow a pattern similar to the other claims and call it something along the lines of "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/country".
Once you have added the Name, you'll need to choose the Source. Select Attribute, then choose a relevant one from the dropdown list. If you have chosen "company" as your claim, then this attribute would most likely be user.companyname. It's important to ensure that you choose an attribute that is completed for your existing users. Again, it doesn't matter which one you choose, it just needs to be an attribute that you can safely use to differentiate users between the Teamtailor accounts that they should be joining.
Click "Save", and then you'll see your list of additional claims:
The next step is to let Teamtailor know the name of the claim that you have created, alongside the possible values that would be used as the identifier for your Teamtailor account, as well as any auto-join domains linked to those accounts. This could look something like this:
claim = country
Teamtailor account A: value = TeamtailorA, domain = @teamtailora.com
Teamtailor account B: value = TeamtailorB, domain = @teamtailorb.com
To test this, you can follow the same steps as previously for a single account, but ensure that your user is then logged into the correct account.
It's important to note here that this is only for new users. Existing users will automatically log in to the accounts where they are already set up.
Additionally, using Group SSO does not mean that all users will then have access to the other accounts. New users will only automatically be added to one account, but if they need access to more than one, they will need to be manually added in the Employees tab of the other accounts.
Common error messages
This means that in your SSO Azure settings, you have not added this user to the Users and Groups settings. To solve this, please follow step 7 of the article above.
You have added the Entity ID incorrectly. Please double-check this in your Teamtailor settings and ensure that it perfectly matches what you have in your Azure AD.
This error, displayed in your Teamtailor SSO settings, usually means that your SAML Signing Certificate has expired or is invalid. To create a new one, go to your Azure AD settings, find the Enterprise app that you have created, and then Single Sign-on. From here, it's Step 3 SAML Certificates that you need to edit. Click Edit, then + New Certificate, then Save. By default, this will then add a further 3 years to your certificate and fix the issue.