> 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/documentation/documentation-zh/ji-cheng-yu-guan-li/integrations/group-mapping.md).

# 组映射

让 Dispel 组成员身份与身份提供商中的组保持同步。通过 OAuth (OIDC) 或 SAML 将 Microsoft Entra ID 或 Okta 组映射到 Dispel 组。

## 概述

Dispel 通过支持身份提供商 (IdP) 组与 Dispel 组之间的直接映射，简化了群组成员管理。完成群组映射后，在 IdP 中所做的更改会在下一次计划同步时反映到 Dispel 中，通常只需几分钟。例如，将用户添加到 IdP 组或从中移除用户，会更新他们在相应 Dispel 组中的成员身份，但 [同步的工作方式](#how-sync-works)中所述的例外情况除外。此集成让组织能够通过一个直观且天然支持审计的集中式解决方案来管理用户和群组。

设置群组映射分为两步：

1. [配置身份提供商](https://docs.dispel.com/documentation/documentation-zh/ji-cheng-yu-guan-li/integrations/group-mapping/configure-your-identity-provider.md) 以便 Dispel 能够读取群组成员信息。
2. [映射群组](https://docs.dispel.com/documentation/documentation-zh/ji-cheng-yu-guan-li/integrations/group-mapping/map-groups.md) 以在仪表板中取消对群组的配置。

{% hint style="info" %}
Active Directory 有自己的群组映射，可在集成过程中完成设置。请参阅 [将 AD 组映射到 Dispel 组](https://docs.dispel.com/pages/5560d095fc7be8d11b1b55e8ef44002f74dcd0cf#id-8.-map-a-d-groups-to-dispel-groups).
{% endhint %}

## 支持的身份提供商

| 登录协议         | 身份提供商              | 群组匹配方式                           |
| ------------ | ------------------ | -------------------------------- |
| OAuth (OIDC) | Microsoft Entra ID | 按群组名称                            |
| OAuth (OIDC) | Okta               | 按群组名称                            |
| SAML         | Microsoft Entra ID | 按 Entra ID 群组本身（其对象 ID）匹配，通过搜索选择 |

## 同步的工作方式

* **同步按计划运行。** Dispel 每隔几分钟检查一次 IdP，因此更改会在一个同步周期内生效。
* **将某人添加到 IdP 组后，该用户也会被添加到 Dispel 组。** 如果用户已属于你的 Dispel 组织，他们会在下次同步时被添加。如果尚未加入，该用户会收到邀请，并在首次使用 SSO 登录时获得访问权限。
* **从 IdP 组中移除某人后，该用户会在下次同步时从 Dispel 组中移除**；但如果其他已映射的 IdP 组仍包含该用户，则不会移除。在同步运行前，他们仍保有 Dispel 访问权限。
* **如果无法读取 IdP，同步绝不会移除任何人。** 如果无法读取某个群组，其成员会保留在原处，直到之后某次同步成功。
* **对于 SAML，群组为空或已删除时，不会移除任何人。** 同步会将空结果视为可能的读取失败，因此该群组中已同步的成员仍保有访问权限。对于 OIDC，群组为空或已删除时，会移除其中已同步的成员。

{% hint style="warning" %}
**移除 SAML 映射群组中的最后一名成员，不会撤销其访问权限。** 该群组会以空群组的形式返回，因此同步会保留其成员。若要撤销访问权限，请手动将用户从 Dispel 组中移除，或在 Dispel 中取消群组映射；取消映射会移除所有从该群组同步来的成员。
{% endhint %}

## OIDC 与 SAML 的比较

这两种协议都按计划同步，但设置方式和移除成员的行为有所不同。同步方面的差异请参阅 [映射群组后会发生什么](https://docs.dispel.com/documentation/documentation-zh/ji-cheng-yu-guan-li/integrations/group-mapping/map-groups.md#what-happens-after-you-map-a-group) 。设置方面的差异总结如下：

|                     | OAuth (OIDC)                              | SAML                      |
| ------------------- | ----------------------------------------- | ------------------------- |
| **所用凭据**            | Entra ID：用于 SSO 的同一个应用注册。Okta：Okta API 令牌 | 单独的 Entra ID 应用注册，仅用于群组同步 |
| **映射群组**            | 输入 IdP 群组名称                               | 搜索 Entra ID 群组并选择要映射的群组   |
| **启用方**             | 由 Dispel 按需启用                             | 由你在 SAML 设置中启用            |
| **手动添加的成员**         | 不允许：映射群组只能包含同步的成员                         | 允许：同步不会影响他们               |
| **无法读取映射群组时**       | 不会移除任何人                                   | 不会移除任何人                   |
| **映射群组返回为空时**       | 会移除通过该群组同步的所有成员                           | 不会移除任何人                   |
| **映射群组被删除时**        | 会移除通过该群组同步的所有成员                           | 不会移除任何人。如果该组已永久停用，请删除映射   |
| **如果已映射的组被重命名**     | 通过该组同步的所有用户都会被移除，直到你将映射更新为新名称             | 无需采取任何操作：映射会跟随该组          |
| **如果有人在接受邀请前离开某个组** | 只有当 Dispel 也为你的组织启用了用户同步时，才会撤回该用户的邀请      | 该用户的邀请会被撤回                |

有关每项变更的具体影响，请参阅 [映射组后会发生什么](https://docs.dispel.com/documentation/documentation-zh/ji-cheng-yu-guan-li/integrations/group-mapping/map-groups.md#what-happens-after-you-map-a-group).

## 优势

1. **集中式访问管理**
   * 管理员可直接在 IdP 中管理用户角色，无需在各个应用中单独配置权限。
   * 应用权限与 IdP 组关联，确保工作流程一致且顺畅。
2. **自动配置**
   * 在 IdP 中进行变更后，用户访问权限会在下一次计划同步时更新。
   * 组同步会按计划应用成员变更，但需遵循 [特定于协议的同步规则](https://docs.dispel.com/documentation/documentation-zh/ji-cheng-yu-guan-li/integrations/group-mapping/map-groups.md#what-happens-after-you-map-a-group)。空的或已删除的 SAML 组不会自动移除已同步的成员。
3. **增强安全性**
   * 集中式控制可降低配置错误和权限过期带来的风险。
   * 权限会按计划与 IdP 组成员关系同步，因此无需人工审核即可清理过期访问权限。
4. **可扩展性**
   * 权限在组级别进行管理，因此可以轻松地对大量用户应用变更。
   * 在组中添加或移除用户，即可批量更新其在多个应用中的访问权限，简化不断发展的组织的管理工作。
5. **改善用户体验**
   * 用户会根据其所属组自动获得相应权限，无需额外配置。
   * 完成身份验证后，用户即可顺畅访问已配置正确角色的应用。
6. **满足合规要求并做好审计准备**
   * 角色与组的映射可确保审计记录清晰且一致。
   * IdP 通常会记录组成员关系变更，从而更便于追踪和核验访问权限，以满足合规要求。

通过集成组映射，组织能够以可扩展、安全且高效的方式管理访问权限，同时简化合规工作并为用户提供顺畅的体验。

## 后续步骤

[步骤 1：配置身份提供商以进行组映射](https://docs.dispel.com/documentation/documentation-zh/ji-cheng-yu-guan-li/integrations/group-mapping/configure-your-identity-provider.md)

[步骤 2：在 Dispel 控制面板中映射组](https://docs.dispel.com/documentation/documentation-zh/ji-cheng-yu-guan-li/integrations/group-mapping/map-groups.md)

## 相关

* [身份提供商](https://docs.dispel.com/documentation/documentation-zh/bao-hu-yu-zhi-li/identity-providers.md)
* [Microsoft Entra ID](https://docs.dispel.com/documentation/documentation-zh/bao-hu-yu-zhi-li/identity-providers/microsoft-entra-id.md)
* [Okta](https://docs.dispel.com/documentation/documentation-zh/bao-hu-yu-zhi-li/identity-providers/okta.md)
* [组织群组](https://docs.dispel.com/documentation/documentation-zh/guan-li-yong-hu-he-fang-wen/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/documentation/documentation-zh/ji-cheng-yu-guan-li/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.
