> For the complete documentation index, see [llms.txt](https://docs.trusst.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.trusst.ai/product-guides/integrating-your-identity-provider.md).

# Integrating Your Identity Provider

This guide outlines how IT administrators can integrate an identity provider (IDP), such as Okta or Entra ID, with Trusst AI.

You’ll need to configure an application in your IDP using the **Trusst AI Single Sign-On setup link** provided to you.\
This link launches a guided, self-service configuration flow to connect your identity provider (Okta or Microsoft Entra ID) with Trusst AI.

Trusst AI reads user roles from the `roles` claim by default.\
If your identity provider does not include a `roles` claim, Trusst AI will also accept a `role` (singular) or `groups` claim.\
Both must be arrays of strings.

***

#### Step 1: Configure Single Sign-On

Use the **Configure Single Sign-On** link sent to you by Trusst AI.

This self-service setup will:

1. Guide you through creating a new application in your IDP.
2. Provide your unique Client ID, Client Secret, and Callback URL.
3. Establish the OIDC/SAML connection.
4. Test and confirm authentication between your IDP and Trusst AI.

Once complete, you will have a configured Trusst AI application in your IDP.

***

#### Step 2: Create Role Keys in Your IDP

Create roles (Entra ID) or groups (Okta) in your identity provider matching these **Trusst AI role keys** exactly:

* `trusst_ai_viewer`
* `trusst_ai_analyst`
* `trusst_ai_editor`
* `trusst_ai_admin`

**Okta:**\
Directory → Groups → Add Group → (Role key)

**Entra ID:**\
Microsoft Entra ID → App registrations → *(Trusst AI App)* → App roles → Add app role → (Role key)

***

#### Step 3: Assign Users to Roles

Assign users to the role groups or app roles that correspond to their level of access.

**Okta:**\
Directory → Groups → *(Role group)* → People → Assign People

**Entra ID:**\
Enterprise Applications → *(Trusst AI App)* → Users and groups → Add user/group → Assign to role

***

#### Step 4: Expose Role or Group Claims in the Token

Ensure your ID token includes either a `roles` or `groups` claim.

**Okta:**\
Applications → *(Trusst AI App)* → Sign On → Claims → Edit\
Claim name: `roles`\
Groups claim type: `Filter`\
Filter: `Starts with` → `trusst_ai`

**Entra ID:**\
Roles are automatically included in the `roles` claim once users or groups are assigned to app roles.

***

#### Step 5: Verify Access

After setup, sign in with a user assigned to one or more Trusst AI roles.\
If successful, the correct permissions will appear within Trusst AI.

If any issues occur, contact your Trusst AI integration contact.

***

**Note:**

* Trusst AI reads the `roles` claim first, falling back to `role` (singular) or `groups` if missing.
* Claims must be arrays of strings containing valid Trusst AI role keys.
* For detailed role definitions, see [Trusst AI Roles and Permissions](https://docs.trusst.ai/product-guides/user-roles-and-permissions).