Okta connects through OpenID Connect. These are the steps in the order that worked, with Okta's names beside Tamaat's. Okta changes its console from time to time; if a label differs, look for the one closest to it.
Before you begin
- You are an Admin of the Tamaat organization, on the Professional plan or above.
- You are an administrator of the Okta organization.
- At least one Okta user is assigned to the application you create below. That person's email address matches the address they are invited to Tamaat with.
- To let people start from their work email, you can add a DNS record to your email domain. This is optional; the "Sign-in address" works without it.
- To require single sign-on later, the Admin who will be the recovery person has a Tamaat password and two-factor authentication.
1. Create the application in Okta
In the Okta Admin Console, choose Applications → Applications → Create App Integration. Choose the Classic experience if Okta offers it beside the Okta Integration Wizard, then OIDC - OpenID Connect and Web Application, then Next.
| Okta setting | Value |
|---|---|
| App integration name | A name you will recognise, such as Tamaat |
| Client definition | Use the client ID that Okta generates |
| Require Demonstrating Proof of Possession (DPoP) | Off |
| Authorization Code | On |
| Client Credentials | Off |
| Refresh Token | Off |
| Sign-in redirect URIs | Leave Okta's suggested address for now. You replace it in step 4. |
Allow wildcard * in sign-in redirect URI | Off |
| Sign-out redirect URIs | Empty |
| Trusted Origins / Base URIs | Empty |
| Controlled access | Skip group assignment for now |
Save the application. On its General tab, copy the Client ID and the Client secret. Tamaat authenticates with the client secret.
2. Assign people in Okta
Okta only lets assigned people sign in to the application.
- 1
Open the application's Assignments tab and choose Assign → Assign to People.
- 2
Find the person, choose Assign, then Save and Go Back, and finish the dialog.
The search box on the main Assignments page searches people who are already assigned. An empty result does not mean the person is missing from Okta; use Assign to People to add them.
3. Add the connection in Tamaat
- 1
Open Settings and choose Organization → Single sign-on. Under Connection, choose "Add connection".
- 2
Under "Identity provider", choose Okta.
- 3
Under "From Okta", fill in:
- "Connection name": what your people will see when they sign in, such as your company's name.
- "Issuer": your Okta organization's address, in the form
https://<your-okta-organization>.okta.com. Use the address people use to sign in to Okta, without the-adminpart of the administration address and without an activation or enrollment path. The issuer that worked for us was this organization address, not an authorization server ending in/oauth2/default; use that only if you have a reason to and the test passes. - "Client ID": copied from the Okta application.
- "Client secret": copied straight from Okta. Do not retype it.
- "Secret expiry date (optional)": leave empty, or enter the day the secret ends.
- 4
Leave the group and advanced discovery fields empty.
- 5
Choose "Save". The form says "Saved." and shows a new step, "Copy into Okta".
4. Put the redirect address in Okta
"Copy into Okta" shows two addresses, each with a "Copy" button. Use the buttons; do not build the addresses by hand.
| Address | What it is for |
|---|---|
| "Redirect URI" | Where Okta sends the browser back to Tamaat. It has the form https://<tamaat-app-host>/api/auth/federation/<connection-id>/oidc/callback. It goes in Okta. |
| "Sign-in address" | Starts a sign-in through this connection. It has the form https://<tamaat-app-host>/api/auth/federation/<connection-id>/start. It is a link or bookmark for your people. It does not go in Okta. |
- 1
In Okta, open the application's General tab and choose Edit under General Settings.
- 2
Replace the Sign-in redirect URIs entry with the "Redirect URI" from Tamaat. Leave Login initiated by on App Only. Save.
Do this before you test or sign in. The address Okta suggested at the start only lets you create the application; it is not Tamaat's address, and none should remain once you finish.
5. Test the connection
- 1
In Tamaat, choose "Save and test". You are sent to Okta. Sign in as an assigned person.
- 2
You come back to the result, which says "The test did not sign anyone in." A passing test proves Okta accepts the connection and shows what Okta sent. It does not sign anyone in to Tamaat and does not link any account.
- 3
On "Passed", check the lines: "Permanent ID received", "Email received" and "Sign-in time received" should all be present. For Okta, the test also reported two-factor and a notice that people confirm their email with a code the first time.
- 4
Choose "Enable connection". The connection reads "Active".
- 5
Under Sign-in policy, choose "Optional": "Password or single sign-on".
6. Sign in once, in a private window
Open the "Sign-in address" in a private browser window, so no earlier session gets in the way, and sign in through Okta.
If the person already has a Tamaat account with the same email address, Tamaat asks "Link your accounts?". Check that both accounts are the person's, then choose "Link accounts". Passwords still work.
Signing out of Tamaat does not sign you out of Okta. Okta keeps its own session, so the next time Tamaat sends you there you may come straight back without seeing a password prompt. How long that lasts, and when Okta asks again, is set by your Okta policies. Test in a private window, or sign out of Okta too, when you want to see the full sign-in.
7. Start from a work email (optional)
Without a verified domain, people use the "Sign-in address". If someone types their work email under Sign in with your organization and sees "Use the sign-in address your organization gave you.", the domain is not verified yet. Optional single sign-on is not broken.
- 1
Under Domains, choose "Add domain" and enter the domain alone, such as
example.com. - 2
Choose "Show record". Tamaat shows a TXT record:
Field Value Type TXTName _tamaat-sso.<your-domain>Value tamaat-sso-verification=<generated-token>Publish it where your domain's DNS is actually managed. That is the provider of your domain's name servers, which may not be the provider of your website or your email. Some DNS tools want only the relative name,
_tamaat-sso; others want the full name. Use whichever your tool expects. - 3
Choose "Check now" until the domain reads "Verified". DNS can take a while, and some resolvers keep an earlier "not found" answer for a time. If it does not verify at once, wait and check again.
A verified domain sends people to your sign-in. It does not add members; joining stays by invitation.
The three policies
| Policy | What happened in our tests |
|---|---|
| Optional | Both worked: a Tamaat password with its two-factor step, and Okta, including starting from the work email once the domain was verified. |
| Required | The checklist passed after a real Okta sign-in. See below. |
| Off | Work-email sign-in stopped offering the connection. |
Changing a sensitive setting
Changing the policy, and the other sensitive settings in this section, needs a proof that only Tamaat can give. From a session that Okta opened, a password alone does not count. Tamaat tells you: "Your organization’s sign-in opened this session, so your password alone cannot confirm this change. Sign out, then sign in with your password and your second step." Do that, return to the settings and try again. Until the change shows as saved, it has not been saved. Turn on two-factor authentication under Account → Security & sign-in before you need it.
Requiring Okta
Follow Require Single Sign-On. The order that worked:
- Turn on two-factor authentication on the Admin's Tamaat account and sign in with the password and second step.
- Open the readiness list and choose "Make me the recovery person".
- Complete a real sign-in through Okta from the list.
- When every line reads "Ready", choose "Require single sign-on", type the organization's name, and give the confirmation Tamaat asks for.
The list includes a check that requiring single sign-on is available for your Tamaat deployment. If it reads "Not ready", nothing in Okta can fix it; contact the operator of your Tamaat deployment. Once it is required, a person who signs in with a password still cannot open the organization's work until they continue to Okta.
If something does not work
| What you see | Check |
|---|---|
| "The identity provider refused our request. Check the client ID, the client secret and the redirect URI." | The "Redirect URI" from Tamaat, exactly, is the Sign-in redirect URI in Okta, and the client ID and secret are from this application. |
| "The provider’s discovery document names a different issuer. Check the issuer address." | The "Issuer" is https://<your-okta-organization>.okta.com, as people see it, not the -admin address. |
| Okta says the person is not assigned | Assign them in step 2. |
| "Use the sign-in address your organization gave you." | The domain is not verified. See step 7, or use the "Sign-in address". |
Troubleshoot Single Sign-On lists every sentence.