Set up single sign-on with Okta

(Edited )
Table of Contents

Agents then sign in to Taiwa with their Okta account. You need an Okta administrator who can create app integrations, and the administrator role in Taiwa.

Before you start

  • Ask Taiwa to verify the email domains of your organisation. Taiwa refuses a sign-in from an email domain that is not verified.
  • Each agent needs a primary email address in Okta, in one of those domains. Taiwa signs in a user only when Okta says that this email address is verified.

1. Create the app integration

  1. In the Okta Admin Console, go to Applications > Applications, and select Create App Integration.
  2. For Sign-in method, select OIDC - OpenID Connect. For Application type, select Web Application. Select Next.
  3. For App integration name, enter Taiwa.
  4. Under Grant type, keep Authorization Code.
  5. For Sign-in redirect URIs, enter https://api.taiwa.cx/v1/auth/sso/callback. Remove any sign-out redirect URI.
  6. Under Assignments, choose who can use Taiwa. Select Save.

2. Copy the client details

  1. On the General tab, under Client Credentials, copy the Client ID.
  2. Under Client authentication, keep Client secret. Copy the client Secret.
  3. If Require PKCE as additional verification is selected, clear it. Taiwa does not send PKCE, and Okta then refuses the sign-in.

3. Assign people

On the Assignments tab, assign the people or groups that use Taiwa. Okta refuses a sign-in from a person who is not assigned.

4. Connect Okta in the admin portal

  1. In the admin portal, open SSO & Provisioning.
  2. For Issuer URL, enter your Okta domain, for example https://acme.okta.com. Use the domain without -admin.
  3. For Client ID and Client secret, enter the values from Okta.
  4. Select Save connection.

If your organisation uses a custom authorization server in Okta, enter its issuer instead, for example https://acme.okta.com/oauth2/default.

5. Test

Sign in to the admin portal in a private browser window. Select Sign in with SSO, enter your Organisation ID, and sign in with an Okta account that you assigned.

Directory sync with SCIM (optional)

An Okta OIDC app integration cannot use SCIM. Make a second app integration for directory sync.

  1. In the admin portal, under Directory sync (SCIM 2.0), copy the SCIM base URL, and select Generate token. Copy the token at once.
  2. In Okta, create a second app integration, for example Taiwa provisioning, as Okta's guide for SCIM provisioning describes.
  3. On its General tab, under App Settings, select Edit. For Provisioning, select SCIM, and select Save.
  4. On the Provisioning tab, under Integration, enter the SCIM base URL as the SCIM connector base URL. For Unique identifier field for users, enter userName.
  5. For the authentication mode, select HTTP Header, and enter the token as the bearer token.
  6. Select Test Connector Configuration, and save.
  7. Turn on Create Users, Update User Attributes and Deactivate Users, and assign the same people as in the sign-in app integration.

If sign-in fails

When a sign-in fails after the identity provider, the browser shows a page on api.taiwa.cx with the reason. The reason is in English.

Reason What to check
SSO id_token email is not verified Okta has not verified the primary email of the user.
SSO token exchange failed The client secret is wrong, or PKCE is required on the app integration.
SSO discovery failed or SSO discovery issuer mismatch The Issuer URL is your Okta domain, without -admin and with no path, or the issuer of your custom authorization server.
Email domain is not verified for this tenant Ask Taiwa to verify the email domain.
Okta says that the user is not assigned Assign the user on the Assignments tab.
Was this helpful?