Please note that this information was correct as of 13th November 2023 and Teamtailor is not responsible for any changes made within Google. Any questions outside the scope of this article should be sent directly to Google'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 Google Admin console, then under Apps, click on Web and mobile apps, then click on Add app, then Add custom SAML app.
On the new page, give it a suitable name, a description, and an icon if you wish, then click "Continue".
On the next page, you'll have two options. We recommend clicking "Download Metadata" and saving the XML file in your Downloads, then click Continue.
Next, you'll need to provide the Service provider details. These are the ACS URL and Entity ID that are provided in your Teamtailor SSO Settings:
In Google, you can ignore the Start URL, but on the Name ID field, make sure to select "Persistent" as the Name ID format, then click Continue.
In Teamtailor, you can then upload the XML file that you downloaded in Step 3 into the field where it says "Upload IdP metadata file". Select your XML file, click the Parse data button, then finally Finish setup.
Back in Google, you can then also click on "Finish", and then you'll see your new Teamtailor SSO appear in your Apps under the Web and mobile apps setting.
To test it, you'll first need to give access to the users in your organization. This can be done before finishing the setup, or afterward. To edit this setting, click on your new App, then User access, then switch the setting to "ON for everyone" and then Save.
Then, in the same place where you clicked User access previously, click "Test SAML Login". This will then direct you to Teamtailor to log in and check if it's working properly. 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 to previously.
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
Note that this section only applies to companies that have more than one Teamtailor account and would like to use the same SSO setup across all their accounts.
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 attribute, which we can use to identify to which account the new user should be added.
To add a new claim, click on your new App, then "Configure SAML attribute mapping", then Add Mapping. This will give you two fields to fill in:
"Google Directory attributes" is the list of attributes that exist for your users within your Google Admin, and is the attribute that you plan to use as an identifier to tell Teamtailor which account you would like the new user to be added. This could be anything, but most commonly is Country, Organization, or Department.
"App attributes" is a free-text box and is where you can choose the name of the claim that you send to Teamtailor. Again, this could be anything. The only important thing here is that you tell Teamtailor what you have chosen as the App attribute, as this is the detail that Teamtailor will use to differentiate your users.
The final step is to let Teamtailor know the name of the App attribute 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:
attribute = 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 Google settings, you have not added this user group under "User access". To solve this, please follow step 8 of the article above.
2.
This means that you have the wrong ACS URL or Entity ID URL in your Google account. Please check your Teamtailor account that it matches.