Please note that this information was correct as of 14th November 2023 and Teamtailor is not responsible for any changes made within Okta. Any questions outside the scope of this article should be sent directly to Okta'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 Okta Admin portal, then Applications, then Create App Integration, and finally select SAML 2.0.
On the new page, give it a suitable name, a logo if you wish, leave the App visibility unticked, then click "Next".
Under the heading Configure SAML, you'll need to add the Single sign-on URL and Audience URI (SP Entity ID). These two URLs are found in your Teamtailor settings and need to be copied and pasted into the relevant fields.
In Okta, ensure that the Name ID format is Persistent and the Application username is Email. You can then scroll to the bottom and click Next. The next page is a Feedback page, which you can fill if you wish, then click "Finish".
On Okta, the next page that loads will be the "Sign On" part of your new integration, and here you'll find your Metadata URL. Copy this URL, then on Teamtailor, paste this into the field called IdP Metadata XML URL, then click Parse Metadata, then Finish setup.
Back in Okta, you will then need to assign a user to test your new application. To do this, click on Directory, then People, then the user that you would like to test, then Assign Applications, then by your new application click Assign, then Save.
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.
Upon clicking SSO, you should be redirected to the page where you can enter your Okta 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.
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, find your new app, then in the General tab, scroll down to SAML settings, then click Edit in the corner of that window. Skip to the Configure SAML step, then scroll down to the Attribute Statements (optional) section. The "Name" field is the field that you will need to give to Teamtailor and can be called anything. The "Value" field needs to have an existing value on your user profiles, e.g. user.title. A full list is available in the Profile Editor section of your Directory.
The final step is to let Teamtailor know the name of the 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 name = 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 Okta People settings, you have not added your application to this user. To solve this, please follow step 6 of the article above.
This usually means that you have entered your Single sign-on URL and Audience URI (SP Entity ID) incorrectly. Please ensure that you have entered this information correctly from Teamtailor.
This error, displayed in your Teamtailor SSO settings, usually means that your Okta certificate has expired. To generate a new one, find your new app, go to the Sign On subheading, then scroll to the bottom where you will see SAML Signing Certificates. Here, you just need to generate a new certificate.