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

# Group Mapping

Keep Dispel group membership in sync with groups in your identity provider. Map Microsoft Entra ID or Okta groups to Dispel groups over OAuth (OIDC) or SAML.

## Overview

Dispel streamlines group membership management by supporting direct mapping between identity provider (IdP) groups and Dispel groups. When groups are mapped, changes made in the IdP are reflected in Dispel on the next scheduled sync, usually within a few minutes. For example, adding or removing users from an IdP group updates their membership in the corresponding Dispel group, with the exceptions described in [How sync works](#how-sync-works). This integration allows organizations to manage users and groups through a single, centralized solution that is intuitive and inherently auditable.

Setting up group mapping takes two steps:

1. [Configure your identity provider](https://docs.dispel.com/integrate-and-administer/integrations/group-mapping/configure-your-identity-provider.md) so Dispel can read group membership.
2. [Map groups](https://docs.dispel.com/integrate-and-administer/integrations/group-mapping/map-groups.md) to Dispel groups in the Dashboard.

{% hint style="info" %}
Active Directory has its own group mapping, set up as part of the integration. See [Map AD groups to Dispel groups](https://docs.dispel.com/pages/UNsFWkhiPRCo6cVziQwK#id-8.-map-a-d-groups-to-dispel-groups).
{% endhint %}

## Supported identity providers

| Sign-in protocol | Identity provider  | How groups are matched                                              |
| ---------------- | ------------------ | ------------------------------------------------------------------- |
| OAuth (OIDC)     | Microsoft Entra ID | By group name                                                       |
| OAuth (OIDC)     | Okta               | By group name                                                       |
| SAML             | Microsoft Entra ID | By the Entra ID group itself (its object ID), chosen through search |

## How sync works

* **Sync runs on a schedule.** Dispel checks your IdP every few minutes, so changes appear within one sync cycle.
* **Adding someone to the IdP group adds them to the Dispel group.** If a user already belongs to your Dispel organization, they're added on the next sync. If they don't, the user is invited, and they receive access the first time they sign in with SSO.
* **Removing someone from the IdP group removes them from the Dispel group on the next sync**, unless another mapped IdP group still includes them. Until that sync runs, they keep their Dispel access.
* **Sync never removes anyone when it can't read your IdP.** If a group can't be read, its members are left until a later sync succeeds.
* **With SAML, an empty or deleted group removes nobody.** Sync treats an empty result as a possible read failure, so the group's synced members keep their access. With OIDC, an empty or deleted group removes its synced members.

{% hint style="warning" %}
**Removing the last member of a SAML-mapped group doesn't revoke their access.** The group comes back empty, so sync leaves its members in place. To revoke access, remove the user from the Dispel group by hand, or unmap the group in Dispel, which removes everyone synced from it.
{% endhint %}

## OIDC and SAML compared

Both protocols sync on a schedule, but their setup and membership-removal behavior differ. See [What happens after you map a group](https://docs.dispel.com/integrate-and-administer/integrations/group-mapping/map-groups.md#what-happens-after-you-map-a-group) for the sync differences. The setup differences are summarized below:

|                                                             | OAuth (OIDC)                                                                                | SAML                                                                |
| ----------------------------------------------------------- | ------------------------------------------------------------------------------------------- | ------------------------------------------------------------------- |
| **Credentials used**                                        | Entra ID: the same app registration you use for SSO. Okta: an Okta API token                | A separate Entra ID app registration, just for group sync           |
| **Mapping groups**                                          | Type the IdP group names                                                                    | Search your Entra ID groups and select the ones to map              |
| **Enabled by**                                              | Dispel, on request                                                                          | You, in the SAML settings                                           |
| **Members added by hand**                                   | Not allowed: a mapped group must contain only synced members                                | Allowed: sync leaves them alone                                     |
| **If a mapped group can't be read**                         | Nobody is removed                                                                           | Nobody is removed                                                   |
| **If a mapped group comes back empty**                      | Everyone synced through that group is removed                                               | Nobody is removed                                                   |
| **If a mapped group is deleted**                            | Everyone synced through that group is removed                                               | Nobody is removed. Remove the mapping if the group is gone for good |
| **If a mapped group is renamed**                            | Everyone synced through that group is removed until you update the mapping to the new name  | No action necessary: the mapping follows the group                  |
| **If someone leaves a group before accepting their invite** | Their invite is withdrawn only if Dispel has also turned on user sync for your organization | Their invite is withdrawn                                           |

For more on what each change does, see [What happens after you map a group](https://docs.dispel.com/integrate-and-administer/integrations/group-mapping/map-groups.md#what-happens-after-you-map-a-group).

## Benefits

1. **Centralized access management**
   * Administrators manage user roles directly in the IdP, eliminating the need to configure permissions in individual applications.
   * Application permissions are tied to IdP groups, ensuring a consistent and streamlined workflow.
2. **Automated provisioning**
   * User access is updated on the next scheduled sync after changes are made in the IdP.
   * Group sync applies membership changes on a schedule, subject to the [protocol-specific sync rules](https://docs.dispel.com/integrate-and-administer/integrations/group-mapping/map-groups.md#what-happens-after-you-map-a-group). Empty or deleted SAML groups do not automatically remove their synced members.
3. **Enhanced Security**
   * Centralized controls minimize risks of misconfigurations and stale permissions.
   * Permissions are synchronized with IdP group memberships on a regular schedule, so stale access is cleaned up without manual review.
4. **Scalability**
   * Permissions are managed at the group level, making it easy to apply changes across large user bases.
   * Adding or removing users from a group updates access for multiple applications in bulk, simplifying management for growing organizations.
5. **Improved User Experience**
   * Users automatically receive permissions based on their group assignments, requiring no additional configuration.
   * Once authenticated, they gain seamless access to applications with the correct roles already in place.
6. **Compliance and Audit Readiness**
   * Role-to-group mapping ensures clear and consistent audit trails.
   * IdPs often log group membership changes, making it easier to trace and verify access permissions for compliance purposes.

By integrating group mapping, organizations gain a scalable, secure, and efficient way to manage access, while simplifying compliance and providing users with a seamless experience.

## Next Steps

[Step 1: Configure the identity provider for group mapping](https://docs.dispel.com/integrate-and-administer/integrations/group-mapping/configure-your-identity-provider.md)

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

## Related

* [Identity Providers](https://docs.dispel.com/secure-and-govern/identity-providers.md)
* [Microsoft Entra ID](https://docs.dispel.com/secure-and-govern/identity-providers/microsoft-entra-id.md)
* [Okta](https://docs.dispel.com/secure-and-govern/identity-providers/okta.md)
* [Organization Groups](https://docs.dispel.com/manage-users-and-access/groups/organization-groups.md)


---

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