# Integrating Your Identity Provider

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).


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.trusst.ai/product-guides/integrating-your-identity-provider.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.