Set up single sign-on with Microsoft Entra ID

(Edited )
Table of Contents

Agents then sign in to Taiwa with their Microsoft work account. You need an account that can register applications in Microsoft Entra ID, for example an Application Administrator, 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 an email address in Entra ID, in a domain that is verified in your Entra tenant. Taiwa uses this email address to find or create the user. A user with no email address in Entra ID cannot sign in.

1. Register Taiwa in Entra ID

  1. Sign in to the Microsoft Entra admin center.
  2. Go to Entra ID > App registrations, and select New registration.
  3. For Name, enter Taiwa.
  4. For Supported account types, select Accounts in this organizational directory only.
  5. Under Redirect URI, select the platform Web, and enter https://api.taiwa.cx/v1/auth/sso/callback.
  6. Select Register.
  7. On the Overview page, copy the Application (client) ID and the Directory (tenant) ID.

2. Make a client secret

  1. Go to Certificates & secrets > Client secrets, and select New client secret.
  2. Enter a description and choose when the secret expires. Select Add.
  3. Copy the Value of the secret at once. Entra ID shows it one time only. Do not copy the Secret ID.

When the secret expires, sign-in stops. Make a new secret before that date, and enter it in the admin portal with Update connection.

3. Add the email claims

Taiwa signs in a user only when the identity provider says that the email address is verified. Entra ID says this with the optional claim xms_edov, and only when you add it.

  1. Go to Token configuration, and select Add optional claim.
  2. For Token type, select ID.
  3. Select email and xms_edov. Select Add.
  4. If Entra ID asks to turn on the Microsoft Graph email permission, select it, and select Add.

4. Check the permissions

  1. Go to API permissions.
  2. Make sure that the list has the Microsoft Graph delegated permissions openid, email and profile. Add any that is missing with Add a permission > Microsoft Graph > Delegated permissions.
  3. Select Grant admin consent for your organisation, so that agents are not asked to give consent.

To let only some people sign in, go to Entra ID > Enterprise apps > Taiwa > Properties, set Assignment required to Yes, and assign users or groups under Users and groups.

5. Connect Entra ID in the admin portal

  1. In the admin portal, open SSO & Provisioning.
  2. For Issuer URL, enter https://login.microsoftonline.com/ followed by your Directory (tenant) ID and /v2.0. For example: https://login.microsoftonline.com/00001111-aaaa-2222-bbbb-3333cccc4444/v2.0.
  3. For Client ID, enter the Application (client) ID.
  4. For Client secret, enter the secret Value.
  5. Select Save connection.

Use the tenant ID, not a domain name, and keep /v2.0 at the end. An issuer with common, organizations or no /v2.0 does not work.

6. 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 a Microsoft account of your organisation.

Directory sync with SCIM (optional)

Entra ID uses a separate enterprise application 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 the Microsoft Entra admin center, go to Entra ID > Enterprise apps, and select New application > Create your own application.
  3. Enter a name, for example Taiwa provisioning. Select Integrate any other application you don't find in the gallery, and select Add.
  4. Select Provisioning, and select New configuration.
  5. For Tenant URL, enter the SCIM base URL. For Secret Token, enter the token.
  6. Select Test Connection, and then select Create.
  7. Under Users and groups, assign the people that Taiwa must have.
  8. Select Start provisioning.

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 The xms_edov claim is missing from the ID token, or the email domain of the user is not verified in your Entra tenant.
SSO id_token missing sub/email The user has no email address in Entra ID, or the email claim is missing.
SSO discovery failed or SSO discovery issuer mismatch The Issuer URL must be https://login.microsoftonline.com/<Directory (tenant) ID>/v2.0.
SSO token exchange failed The client secret is wrong or expired.
Email domain is not verified for this tenant Ask Taiwa to verify the email domain.
Was this helpful?