极狐 GitLab Logo

SAML 群组同步

  • Tier: 专业版，旗舰版
  • Offering: JihuLab.com，私有化部署
History
    • 在极狐GitLab 15.1 中，为私有化部署引入。

使用 SAML 群组同步根据用户在 SAML 身份提供者（IdP）中的群组分配，将具有特定角色的用户分配到现有的极狐GitLab 群组中。通过 SAML 群组同步，您可以在 SAML IdP 群组和极狐GitLab 群组之间创建多对多的映射。

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

SAML 群组同步不会创建群组。您必须首先创建一个群组，然后创建映射。

在 JihuLab.com 上，SAML 群组同步默认配置。在极狐GitLab 私有化部署中，您必须手动配置它。

角色优先级#

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

多个 SAML IdP#

  • Offering: 私有化部署

当用户登录时，极狐GitLab：

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

极狐GitLab 中的群组链接映射与特定 IdP 无关，因此您必须配置所有 SAML IdP 在 SAML 响应中包含群组属性。这意味着极狐GitLab 能够匹配 SAML 响应中的群组，无论使用哪个 IdP 登录。

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

在极狐GitLab 上，针对特定群组，您配置了两个群组链接：

  • gtlb-owner => Owner role。
  • gtlb-dev => Developer role。

在 SAML1 中，用户是 gtlb-owner 的成员，但不是 gtlb-dev 的成员。

在 SAML2 中，用户是 gtlb-dev 的成员，但不是 gtlb-owner 的成员。

当用户使用 SAML1 登录到群组时，SAML 响应显示该用户是 gtlb-owner 的成员，因此极狐GitLab 将用户在该群组中的角色设置为 Owner。

然后用户注销并使用 SAML2 重新登录到该群组。SAML 响应显示用户是 gtlb-dev 的成员，因此极狐GitLab 将用户在该群组中的角色设置为 Developer。

现在我们改变之前的例子，使得用户在 SAML2 中既不是 gtlb-owner 也不是 gtlb-dev 的成员。

  • 当用户使用 SAML1 登录到群组时，用户在该群组中被授予 Owner 角色。
  • 当用户使用 SAML2 登录时，由于他们不是任何配置群组链接的成员，用户被从群组中移除。

多个 SAML 群组#

如果用户是多个 SAML 群组的成员，这些群组映射到同一个极狐GitLab 群组，则用户会被分配这些 SAML 群组中最高的角色。

例如，如果用户在一个群组中具有访客角色，而在另一个群组中具有维护者角色，则他们被分配维护者角色。

成员类型#

如果用户在 SAML 群组中的角色高于其在子群组中的角色，那么其在映射的极狐GitLab 群组中的成员基于其在映射群组中分配的角色是不同的。

如果通过群组同步用户被分配：

  • 更高的角色，他们是群组的直接成员。
  • 相同或更低的角色，他们是群组的继承成员。

自动成员移除#

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

例如，在以下图示中：

  • Alex Garcia 登录到极狐GitLab 并被从极狐GitLab 群组 C 中移除，因为他们不属于 SAML 群组 C。
  • Sidney Jones 属于 SAML 群组 C，但没有被添加到极狐GitLab 群组 C，因为他们尚未登录。
Rendering chart...
Rendering chart...
Rendering chart...

配置 SAML 群组同步#

添加或更改群组同步配置可能会将用户从映射的极狐GitLab 群组中移除，如果群组名称与 SAML 响应中列出的 groups 不匹配。为避免用户被移除，在配置群组同步之前，请确保以下任一条件：

  • SAML 响应包括 groups 属性，并且 AttributeValue 值与极狐GitLab 中的 SAML 群组名称 匹配。
  • 所有群组都从极狐GitLab 中移除以禁用群组同步。

如果您使用 SAML 群组同步并且有多个极狐GitLab 节点，例如在分布式或高可用架构中，您必须在所有 Sidekiq 节点以及 Rails 应用程序节点上包含 SAML 配置块。

要配置 SAML 群组同步：

  1. 请参阅 极狐GitLab.com 群组的 SAML SSO。
  2. 确保您的 SAML 身份提供者发送名为 Groups 或 groups 的属性声明。

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

xml
1<saml:AttributeStatement>
2  <saml:Attribute Name="Groups">
3    <saml:AttributeValue xsi:type="xs:string">Developers</saml:AttributeValue>
4    <saml:AttributeValue xsi:type="xs:string">Product Managers</saml:AttributeValue>
5  </saml:Attribute>
6</saml:AttributeStatement>

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

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

配置 SAML 群组链接#

SAML 群组同步仅管理具有一个或多个 SAML 群组链接的群组。

先决条件：

  • 您的极狐GitLab 私有化部署实例必须已配置 SAML 群组同步。

当启用 SAML 时，具有所有者角色的用户会看到一个新的菜单项在群组 设置 > 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. 如有需要，重复添加其他群组链接。

Microsoft Azure Active Directory 集成#

History
    • 引入于极狐GitLab 16.3。

Microsoft 已宣布将 Azure Active Directory (AD) 重命名为 Entra ID。

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 Portal 中，转到 Microsoft Entra ID > 应用注册 > 所有应用程序，并选择您的极狐GitLab SAML 应用程序。
  2. 在 Essentials 下，显示 应用程序（客户端）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. 选择 Grant admin consent for <application_name>，然后在确认对话框中选择 是。两个权限的 状态 列应更改为绿色勾选，显示 Granted for <application_name>。

配置极狐GitLab#

在您配置 Azure AD 之后，您必须配置极狐GitLab 与 Azure AD 通信。

通过此配置，如果用户使用 SAML 登录并且 Azure 在响应中发送 group 声明，极狐GitLab 将启动群组同步作业以调用 Microsoft Graph API 并检索用户的群组成员资格。然后，根据 SAML 群组链接更新极狐GitLab 群组成员资格。

下表列出了极狐GitLab 设置和相应的 Azure AD 字段以进行配置：

极狐GitLab 设置Azure 字段
租户 ID目录（租户）ID
客户端 ID应用程序（客户端）ID
客户端密钥值（在 证书和密钥 页面上）

要为极狐GitLab.com 群组配置 Azure AD：

  1. 在左侧边栏中，选择 搜索或转到 并找到您的群组。该群组必须处于顶级。
  2. 选择 设置 > SAML SSO。
  3. 为群组配置 SAML SSO。
  4. 在 Microsoft Azure 集成 部分中，选择 为此群组启用 Microsoft Azure 集成 复选框。仅当为群组配置并启用 SAML SSO 时，此部分才可见。
  5. 输入在 Azure Portal 中配置 Azure Active Directory 时获得的 租户 ID、客户端 ID 和 客户端密钥。
  6. 可选。如果使用适用于美国政府或中国的 Azure AD，请输入适当的 登录 API 端点 和 Graph API 端点。默认值适用于大多数组织。
  7. 选择 保存更改。

全局 SAML 群组成员锁定#

  • Offering: 极狐GitLab 私有化部署，极狐GitLab 专属
History
    • 引入于极狐GitLab 15.10。

您可以强制执行 SAML 群组成员资格的全局锁定。此锁定限制谁可以邀请新成员加入与 SAML 群组链接同步的子群组。

锁定群组成员资格时：

  • 您不能将群组或子群组设置为代码所有者。有关更多信息，请参阅与全局 SAML 群组成员锁定不兼容。
  • 只有管理员可以管理群组成员并更改他们的访问级别。
  • 群组成员不能：
    • 与其他群组共享项目。
    • 邀请成员加入群组中创建的项目。
    • 修改为 SAML 群组链接同步配置的顶级群组的成员资格。

锁定群组成员资格#

先决条件：

要锁定成员资格以进行 SAML 群组链接同步：

  1. 在左侧边栏底部，选择 管理员。
  2. 选择 设置 > 常规。
  3. 展开 可见性和访问控制 部分。
  4. 选择 锁定成员资格以进行 SAML 群组链接同步 复选框。