SAML 组同步

使用 SAML 组同步功能，可根据用户在 SAML 身份提供者（IdP）中的组分配，将具有特定角色的用户分配到现有的 GitLab 组中。通过此功能，您可以在 SAML IdP 组与 GitLab 组之间建立多对多映射关系。

例如，如果用户 @amelia 在 SAML IdP 中被分配到 security 组，您可以使用 SAML 组同步功能，将 @amelia 分配到具有维护者（Maintainer）角色的 security-gitlab 组，以及分配到具有报告者（Reporter）角色的 vulnerability 组。

注意：SAML 组同步不会创建组。您必须先创建组，再建立映射关系。

在 GitLab.com 上，SAML 组同步默认已配置。在 GitLab 自托管版中，您需要手动配置。

角色优先级

组同步会确定用户在映射组中的角色和成员类型。

多个 SAML IdP

当用户登录时，GitLab 会执行以下操作：

• 检查所有已配置的 SAML 组链接。
• 根据用户在不同 IdP 中所属的 SAML 组，将用户添加到对应的 GitLab 组中。

GitLab 中的组链接映射不绑定到特定 IdP，因此您必须配置所有 SAML IdP，使其在 SAML 响应中包含组属性。这意味着无论用户使用哪个 IdP 登录，GitLab 都能匹配 SAML 响应中的组。

例如，您有两个 IdP：SAML1 和 SAML2。

在 GitLab 中，您在某个组上配置了两个组链接：

• gtlb-owner => 所有者（Owner）角色
• gtlb-dev => 开发者（Developer）角色

在 SAML1 中，用户属于 gtlb-owner 组，但不属于 gtlb-dev 组。

在 SAML2 中，用户属于 gtlb-dev 组，但不属于 gtlb-owner 组。

当用户使用 SAML1 登录某个组时，SAML 响应显示用户属于 gtlb-owner 组，因此 GitLab 将该用户在该组中的角色设置为 所有者。

用户随后退出登录，并使用 SAML2 重新登录该组。SAML 响应显示用户属于 gtlb-dev 组，因此 GitLab 将该用户在该组中的角色设置为 开发者。

现在修改上述示例，假设在 SAML2 中用户既不属于 gtlb-owner 也不属于 gtlb-dev：

• 当用户使用 SAML1 登录组时，用户在该组中被赋予 所有者 角色。
• 当用户使用 SAML2 登录时，由于用户不属于任何已配置的组链接，用户将被从组中移除。

多个 SAML 组

如果用户属于多个映射到同一 GitLab 组的 SAML 组，用户将被赋予这些 SAML 组中最高的角色。

例如，如果用户在一个组中具有访客（Guest）角色，在另一个组中具有维护者（Maintainer）角色，则最终将被赋予维护者角色。

成员类型

如果用户在 SAML 组中的角色高于其在某个子组中的角色，其成员身份将根据其在映射组中分配的角色而不同：

• 如果通过组同步被分配了更高的角色，用户将成为该组的直接成员。
• 如果被分配了相同或更低的角色，用户将成为该组的继承成员。

自动成员移除

组同步后，不属于映射 SAML 组的用户将被从组中移除。在 GitLab.com 上，顶级组的用户将被分配默认成员角色，而非被移除。

例如，在以下图中：

• Alex Garcia 登录 GitLab 后，由于不属于 SAML 组 C，被从 GitLab 组 C 中移除。
• Sidney Jones 属于 SAML 组 C，但由于尚未登录，未被添加到 GitLab 组 C。

%%{init: { "fontFamily": "GitLab Sans" }}%%
graph TB
accTitle: 自动成员移除
accDescr: 如果配置了组同步，用户登录前如何确定组成员身份。

   subgraph SAML 用户
      SAMLUserA[Sidney Jones]
      SAMLUserB[Zhang Wei]
      SAMLUserC[Alex Garcia]
      SAMLUserD[Charlie Smith]
   end

   subgraph SAML 组
      SAMLGroupA["组 A"] --> SAMLGroupB["组 B"]
      SAMLGroupA --> SAMLGroupC["组 C"]
      SAMLGroupA --> SAMLGroupD["组 D"]
   end

   SAMLGroupB --> |成员|SAMLUserA
   SAMLGroupB --> |成员|SAMLUserB

   SAMLGroupC --> |成员|SAMLUserA
   SAMLGroupC --> |成员|SAMLUserB

   SAMLGroupD --> |成员|SAMLUserD
   SAMLGroupD --> |成员|SAMLUserC

%%{init: { "fontFamily": "GitLab Sans" }}%%
graph TB
accTitle: 自动成员移除
accDescr: 当 Sidney 未登录组 C 且组 B 未配置组链接时的用户成员身份。

    subgraph GitLab 用户
      GitLabUserA[Sidney Jones]
      GitLabUserB[Zhang Wei]
      GitLabUserC[Alex Garcia]
      GitLabUserD[Charlie Smith]
    end

   subgraph GitLab 组
      GitLabGroupA["组 A<br> (已配置 SAML)"] --> GitLabGroupB["组 B<br> (未配置 SAML 组链接)"]
      GitLabGroupA --> GitLabGroupC["组 C<br> (已配置 SAML 组链接)"]
      GitLabGroupA --> GitLabGroupD["组 D<br> (已配置 SAML 组链接)"]
   end

   GitLabGroupB --> |成员|GitLabUserA

   GitLabGroupC --> |成员|GitLabUserB
   GitLabGroupC --> |成员|GitLabUserC

   GitLabGroupD --> |成员|GitLabUserC
   GitLabGroupD --> |成员|GitLabUserD

%%{init: { "fontFamily": "GitLab Sans" }}%%
graph TB
accTitle: 自动成员移除
accDescr: Alex Garcia 登录启用组链接的组后，其成员身份如何生效。

   subgraph GitLab 用户
      GitLabUserA[Sidney Jones]
      GitLabUserB[Zhang Wei]
      GitLabUserC[Alex Garcia]
      GitLabUserD[Charlie Smith]
   end

   subgraph GitLab 组（Alex Garcia 登录后）
      GitLabGroupA[组 A]
      GitLabGroupA["组 A<br> (已配置 SAML)"] --> GitLabGroupB["组 B<br> (未配置 SAML 组链接)"]
      GitLabGroupA --> GitLabGroupC["组 C<br> (已配置 SAML 组链接)"]
      GitLabGroupA --> GitLabGroupD["组 D<br> (已配置 SAML 组链接)"]
   end

   GitLabGroupB --> |成员|GitLabUserA
   GitLabGroupC --> |成员|GitLabUserB
   GitLabGroupD --> |成员|GitLabUserC
   GitLabGroupD --> |成员|GitLabUserD

配置 SAML 组同步

添加或更改组同步配置时，如果 SAML 响应中的 groups 与列出的组名不匹配，可能会导致用户从映射的 GitLab 组中被移除。为避免此问题，在配置组同步前，请确保以下任一条件满足：

• SAML 响应包含 groups 属性，且 AttributeValue 值与 GitLab 中的 SAML 组名 完全匹配。
• 移除 GitLab 中的所有组以禁用组同步。

如果您使用 SAML 组同步且拥有多个 GitLab 节点（例如在分布式或高可用架构中），除了 Rails 应用节点外，还必须在所有 Sidekiq 节点上包含 SAML 配置块。

SAML 响应中 Groups 或 groups 的值可以是组名或 ID。例如，Azure AD 发送的是 Azure 组对象 ID 而非名称。在配置 SAML 组链接 时，请使用 ID 值。

<saml:AttributeStatement>
  <saml:Attribute Name="Groups">
    <saml:AttributeValue xsi:type="xs:string">Developers</saml:AttributeValue>
    <saml:AttributeValue xsi:type="xs:string">Product Managers</saml:AttributeValue>
  </saml:Attribute>
</saml:AttributeStatement>

其他属性名称（如 http://schemas.microsoft.com/ws/2008/06/identity/claims/groups）不被接受为组来源。

有关在 SAML 身份提供者设置中配置所需组属性名称的更多信息，请参考 Azure AD 和 Okta 的示例配置。

配置 SAML 组链接

仅当组包含一个或多个 SAML 组链接时，SAML 组同步才会管理该组。

前提条件：

• 您的 GitLab 自托管实例必须已配置 SAML 组同步。

启用 SAML 后，具有所有者（Owner）角色的用户会在组 设置 > SAML 组链接 中看到新的菜单项。

• 您可以配置一个或多个 SAML 组链接，将 SAML IdP 组名映射到 GitLab 角色。
• SAML IdP 组成员将在下次 SAML 登录时被添加为 GitLab 组成员。
• 每次用户通过 SAML 登录时，都会评估组成员身份。
• SAML 组链接可为顶级组或任何子组配置。
• 如果创建了 SAML 组链接后又被移除，且：
  • 配置了其他 SAML 组链接，则属于被移除组链接的用户在同步期间会自动从组中移除。
  • 未配置其他 SAML 组链接，用户在同步期间仍保留在组中，需手动移除。

要链接 SAML 组：

1. 在 SAML 组名称 中输入相关 saml:AttributeValue 的值。此处输入的值必须与 SAML 响应中发送的值完全匹配。对于某些 IdP，这可能是组 ID 或对象 ID（如 Azure AD），而非友好的组名。
2. 在 访问级别 中选择默认角色或自定义角色。
3. 选择 保存。
4. 如需添加更多组链接，请重复上述步骤。

管理 GitLab Duo 座位分配

前提条件：

• 有效的 GitLab Duo 增值订阅

SAML 组同步可根据 IdP 组成员身份管理 GitLab Duo 座位的分配和移除。仅在订阅中仍有剩余座位时才会分配座位。

Microsoft Azure Active Directory 集成

有关使用 Microsoft Azure 进行组同步的演示，请观看 演示：SAML 组同步。

Azure AD 在 groups 声明中最多发送 150 个组。当使用 Azure AD 和 SAML 组同步时，如果用户在组织中属于超过 150 个组，Azure AD 将在 SAML 响应中为组超额发送 groups 声明属性，用户可能会被自动移除组。

为避免此问题，您可以使用 Azure AD 集成，它具有以下优势：

• 不受 150 个组的限制。
• 使用 Microsoft Graph API 获取所有用户成员身份。Graph API 端点仅接受用户对象 ID或 userPrincipalName 作为 Azure 配置的 唯一用户标识符（名称标识符）属性。
• 仅支持使用组唯一标识符（如 12345678-9abc-def0-1234-56789abcde）配置的组链接。

或者，您可以将组声明更改为分配给应用程序的组选项。

配置 Azure AD

集成过程中，您必须允许 GitLab 与 Microsoft Graph API 通信。

配置 Azure AD 的步骤：

1. 在 Azure 门户 中，转到 Microsoft Entra ID > 应用注册 > 所有应用程序，并选择您的 GitLab SAML 应用。
2. 在 基本信息 下，显示 应用程序（客户端）ID 和 目录（租户）ID 值。请复制这些值，因为您需要在 GitLab 配置中使用它们。
3. 在左侧导航栏中，选择 证书和密码。
4. 在 客户端密码 选项卡上，选择 新建客户端密码。
   1. 在 描述 文本框中添加描述。
   2. 在 过期 下拉列表中，设置凭据的过期日期。如果凭据过期，GitLab 集成将停止工作，直到凭据更新。
   3. 选择 添加 生成凭据。
   4. 复制凭据的 值。此值仅显示一次，您需要在 GitLab 配置中使用它。
5. 在左侧导航栏中，选择 API 权限。
6. 选择 Microsoft Graph > 应用程序权限。
7. 勾选 GroupMember.Read.All 和 User.Read.All。
8. 选择 添加权限 保存。
9. 选择 为 <application_name> 管理员同意，然后在确认对话框中选择 是。两个权限的 状态 列应变为绿色勾选，并显示 已授予 <application_name>。

配置 GitLab

配置 Azure AD 后，您必须配置 GitLab 以与 Azure AD 通信。

通过此配置，如果用户使用 SAML 登录且 Azure 在响应中发送 group 声明，GitLab 将启动组同步作业，调用 Microsoft Graph API 获取用户的组成员身份，然后根据 SAML 组链接更新 GitLab 组成员身份。

下表列出了 GitLab 设置及对应的 Azure AD 配置字段：

全局 SAML 组成员身份锁定

您可以强制执行全局 SAML 组成员身份锁定。此锁定限制谁可以向与 SAML 组链接同步的子组邀请新成员。

锁定组成员身份时：

• 您无法将组或子组设置为代码所有者。更多信息请参见与全局 SAML 组成员身份锁定的不兼容性。
• 只有管理员可以管理组成员身份并更改其访问级别。
• 组成员无法：
  • 将项目与其他组共享。
  • 邀请成员到组中创建的项目。
  • 修改已配置 SAML 组链接同步的顶级组的成员身份。

锁定组成员身份

前提条件：

• 必须已配置 GitLab 自托管版的 SAML SSO。

将成员身份锁定到 SAML 组链接同步：

1. 在左侧边栏底部，选择 Admin。
2. 选择 设置 > 常规。
3. 展开 可见性和访问控制 部分。
4. 勾选 将成员身份锁定到 SAML 组链接同步 复选框。