> For the complete documentation index, see [llms.txt](https://docs.dispel.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.dispel.com/integrate-and-administer/integrations/group-mapping/configure-your-identity-provider.md).

# Configure your identity provider

Give Dispel permission to read group membership from Microsoft Entra ID or Okta, so mapped groups stay in sync.

## Overview

Follow the instructions below to configure Dispel and your identity provider to support group mapping.

* [OAuth (OIDC) with Microsoft Entra ID](#oauth-oidc-with-microsoft-entra-id)
* [OAuth (OIDC) with Okta](#oauth-oidc-with-okta)
* [SAML with Microsoft Entra ID](#saml-with-microsoft-entra-id)

## Before you begin

* You'll need to be an **organization administrator** in Dispel.
* You'll also need administrative access to your identity provider: in Entra ID, an administrator who can grant admin consent; in Okta, one who can create API tokens.
* Your identity provider must already be connected for sign-in. See [Microsoft Entra ID](https://docs.dispel.com/secure-and-govern/identity-providers/microsoft-entra-id.md) or [Okta](https://docs.dispel.com/secure-and-govern/identity-providers/okta.md).

## OAuth (OIDC) with Microsoft Entra ID

OIDC group mapping uses the app registration you already set up for SSO.

#### 1. Add a groups claim

1. In the Microsoft Entra admin center, open the app registration you use for Dispel SSO.
2. Go to **Token configuration** and click **Add groups claim**.
3. Choose the group types to include, for example **Security groups**.
4. Include the groups in the **ID** token.
   * If your app is multi-tenant, please be sure to add a fallback for groups when the maximum limit of groups in a token is reached.
5. Click **Save**.

#### 2. Add API permissions

1. Go to **API permissions** and click **Add a permission**.
2. Choose **Microsoft Graph** and add these permissions:

| Permission             | Type        | Used for                                  |
| ---------------------- | ----------- | ----------------------------------------- |
| `GroupMember.Read.All` | Delegated   | Reading a user's groups when they sign in |
| `GroupMember.Read.All` | Application | Scheduled sync                            |
| `User.Read.All`        | Application | Scheduled sync                            |

3. Click **Grant admin consent for** ***your organization***.

#### 3. Ask Dispel to turn on group sync

OIDC group sync is turned on by Dispel. Contact your Dispel representative, or use the chat bubble in the Dashboard.

## OAuth (OIDC) with Okta

Okta group mapping reads your groups and users with an Okta API token.

#### 1. Add a groups claim

1. In the Okta Admin Console, open the app integration you use for Dispel SSO.
2. On the **Sign On** tab, edit **OpenID Connect ID Token**.
3. Name the claim `groups`, then choose a **Groups claim type**:
   * **Filter**: include groups that match a rule. For example, to include all groups, choose **Matches regex** and enter `.*`.
   * **Expression**: use Okta Expression Language to choose which groups to include.
4. Click **Save**.
5. **Refresh Application Data**
   * Return to the **Applications** list.
   * From the **More** button dropdown menu, select **Refresh Application Data** to ensure the changes take effect.

{% hint style="info" %}
Dispel matches groups by name, so whichever type you choose, the claim must contain the names of the groups you'll map.
{% endhint %}

#### 2. Create an API token

1. Go to **Security → API → Tokens** and click **Create token**.
2. Name it something you'll recognize, for example **Dispel group sync**.
3. Copy the token value now. Okta won't show it again.

{% hint style="warning" %}
**An Okta API token has the same permissions as the admin who created it.** Create it as an admin who can read users and groups, for example a **Read-only Administrator**. If that admin is deactivated, or the token goes unused for 30 days, Okta revokes the token and group sync stops.
{% endhint %}

#### 3. Ask Dispel to turn on group sync

Contact your Dispel representative and send them the API token through a secure channel. Dispel adds it to your organization and turns on group sync.

## SAML with Microsoft Entra ID

SAML sign-in doesn't give Dispel any access to your directory, so group sync uses a separate Entra ID app registration that can read your groups and users.

{% hint style="info" %}
**Save your SAML settings first.** Group sync can only be set up for a saved SAML configuration. See [Connect with SAML](https://docs.dispel.com/secure-and-govern/identity-providers/microsoft-entra-id.md#connect-with-saml).
{% endhint %}

#### 1. Create an app registration for group sync

{% hint style="info" %}
Already have an app registration you'd like to use for group sync? Skip this step. Copy the **Application (client) ID** from its **Overview** page, then continue with step 2 below.
{% endhint %}

1. In the Microsoft Entra admin center, go to **App registrations → New registration**.
2. Name it something you'll recognize, for example **Dispel group sync**.
3. For **Supported account types**, choose **Accounts in this organizational directory only**.
4. Leave **Redirect URI** blank and click **Register**.
5. On the app's **Overview** page, copy the **Application (client) ID**.

#### 2. Add API permissions

1. Go to **API permissions** and click **Add a permission**.
2. Choose **Microsoft Graph → Application permissions**, and add:
   * `GroupMember.Read.All`
   * `User.Read.All`
3. Click **Grant admin consent for** ***your organization***.

#### 3. Create a client secret

1. Go to **Certificates & secrets** and click **New client secret**.
2. Add a description, choose an expiry, and click **Add**.
3. Copy the secret's **Value** now. Entra ID won't show it again.

{% hint style="warning" %}
**When the secret expires, group sync will be paused** until a new one is created. Set a reminder to rotate it before the expiry date.
{% endhint %}

#### 4. Turn on group sync in Dispel

1. In Dispel, go to **Settings → Authentication** and open your SAML settings.
2. Open the **Group sync** section.
3. Paste the **Application (client) ID** and **Client secret**.
4. Click **Test credentials**. The test checks that the app registration can sign in to Entra ID and read groups and users. If a permission is missing, the test names it.
5. Turn on **Enable group sync**.

{% hint style="info" %}
With group sync on, organization administrators can search the names of all groups in your Entra ID tenant to map them.
{% endhint %}

#### How SAML group sync matches users

Each member of a mapped Entra ID group is matched to a Dispel account by the same identifier your SAML sign-in uses. With the default, `nameID`, that's the user's **user principal name**. If a member has no usable value there, Dispel tries their **mail**, then their **user principal name**.

Only users who are direct members of a mapped group are synced. Nested groups and devices are ignored.

## Next steps

[Map groups](https://docs.dispel.com/integrate-and-administer/integrations/group-mapping/map-groups.md) to Dispel groups in the Dashboard.

## Related

* [Group Mapping](https://docs.dispel.com/integrate-and-administer/integrations/group-mapping.md)
* Microsoft: [Configure group claims for applications](https://learn.microsoft.com/en-us/entra/identity/hybrid/connect/how-to-connect-fed-group-claims)


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

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

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.dispel.com/integrate-and-administer/integrations/group-mapping/configure-your-identity-provider.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

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.
