SAML 群组同步

  • 私有化部署实例中此功能引入于极狐GitLab 15.1。
caution 添加或更改群组同步配置可以从映射的极狐GitLab 群组中移除用户。 如果群组名称与 SAML 响应中的 groups 列表不匹配，则会进行移除。 在进行更改之前，您需要确保 SAML 响应包含 groups 属性并且 AttributeValue 的值与极狐GitLab 中的 SAML 群组名称匹配，或者您确保从极狐GitLab 中移除所有群组以禁用群组同步。

SAML 群组同步允许用户根据 SAML 身份提供商（IdP）中的群组分配将用户分配到预存在的极狐GitLab 群组，并为用户分配特定权限。此功能允许您创建 SAML IdP 群组和极狐GitLab 群组之间的多对多映射。例如，如果用户 @amelia 在 SAML IdP 中分配到 security 群组，SAML 群组同步允许您将 @amelia 分配到 security-gitlab 和 vulnerability 极狐GitLab 群组，分别分配 maintainer 和 reporter 权限。SAML 群组同步不会创建群组。您必须单独创建群组，然后创建映射。

配置 SAML 群组链接

如果群组有一个或多个 SAML 群组链接，则 SAML 群组同步仅管理单个群组。

  • 私有化部署实例必须已经配置了 SAML 群组同步。JihuLab.com 实例已经配置了 SAML 群组同步，不需要额外配置。

当启用 SAML 时，具有所有者角色的用户会在群组的 设置 > SAML 群组链接 中看到一个新的目录项目。

  • 您可以配置一个或多个 SAML 群组链接 来映射 SAML IdP 群组名称到极狐GitLab 角色。
  • SAML IdP 群组的成员会在下次 SAML 登录时被添加到极狐GitLab 群组中。
  • 每次用户使用 SAML 登录时都会评估群组成员身份。
  • SAML 群组链接可以配置在顶级群组或任何子群组。
  • 如果创建然后删除 SAML 群组链接，且存在其他 SAML 群组链接，则被删除的群组链接的用户将被自动从群组中移除。
    • 对于已配置的 SAML 组链接，在同步期间，处于已删除的组链接中的用户会被自动从该组中移除。
    • 如果没有其他 SAML 群组链接，则用户将保持在群组中，必须手动从群组中移除。

要链接 SAML 群组：

  1. 在 SAML 群组名称，输入 SAML 响应中的 saml:AttributeValue 的值。输入的值必须与 SAML 响应中发送的值完全匹配。对于一些 IdP，这可能是群组 ID 或对象 ID（Azure AD）而不是友好群组名称。
  2. 选择 默认角色 或 自定义角色。
  3. 选择 保存。
  4. 如果需要，重复添加其他 SAML 群组链接。

SAML Group Links

具有多个 SAML 身份供应商的私有化部署实例

当用户登录极狐GitLab 时：

  • 会检查所有配置的 SAML 群组链接。
  • 根据用户在不同 IdP 中的群组成员身份，将用户添加到对应的极狐GitLab 群组中。

极狐GitLab 中的群组链接映射并不与特定的身份提供商（IdP）绑定，因此你必须将所有的 SAML 身份提供商配置为在 SAML 响应中包含群组属性。这意味着，无论使用哪个身份提供商进行登录，极狐GitLab 都能够匹配 SAML 响应中的群组。

作为示例，您有两个身份提供商：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 时，用户将被从群组中移除，因为用户不是 gtlb-owner 或 gtlb-dev 的成员。

角色优先级

多个映射到 SAML 群组的成员

如果用户是映射到相同极狐GitLab 群的多个 SAML 群组的成员，则用户从群组中获取最高的角色。比如，如果一个群组链接为 Guest，另一个群组链接为 Maintainer，那么用户将获得 Maintainer 角色。

父群组角色高于子群组

用户被授予：

  • 具有更高角色的 Group Sync 会显示为该组的直接成员。
  • 具有较低或相同角色的 Group Sync 会显示为该组的继承成员。

使用 API

  • 引入于极狐GitLab 15.3。

您可以使用极狐GitLab API 列举、添加和删除 SAML 群组链接。

配置 SAML 群组同步

note 如果你使用了 SAML 组同步并且有多个极狐GitLab 节点，例如在分布式或高可用架构中，那么除了在 Rails 应用程序节点上之外，所有 Sidekiq 节点上也需要包含 SAML 配置块
caution 要阻止用户因为意外从极狐GitLab 群组中被移除，在极狐GitLab 启用群组同步前，请严格遵循指南。

要为 私有化部署的极狐GitLab 实例 配置 SAML 群组同步：

  1. 配置 SAML OmniAuth Provider。

  2. 确保您的 SAML 身份提供商发送一个属性声明，其名称与 groups_attribute 设置的值相同。可参阅如下示例：

    gitlab_rails['omniauth_providers'] = [
  {
    name: "saml",
    label: "Provider name", # optional label for login button, defaults to "Saml",
    groups_attribute: 'Groups',
    args: {
      assertion_consumer_service_url: "https://gitlab.example.com/users/auth/saml/callback",
      idp_cert_fingerprint: "43:51:43:a1:b5:fc:8b:b7:0a:3a:a9:b1:0f:66:73:a8",
      idp_sso_target_url: "https://login.example.com/idp",
      issuer: "https://gitlab.example.com",
      name_identifier_format: "urn:oasis:names:tc:SAML:2.0:nameid-format:persistent"
    }
  }
]

要为 JihuLab.com 实例 配置 SAML 群组同步：

  1. 查看 JihuLab.com 群组 SAML SSO。
  2. 确保您的 SAML 身份提供商发送一个名为 Groups 或 group 的属性声明。
note SAML 响应中的 Groups 或 group 值可以是群组名称或 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示例。

Microsoft Azure Active Directory 集成

引入于极狐GitLab 16.3。

note Azure AD 在群组声明中发送最多 150 个群组。当用户是超过 150 个群组的成员时，Azure AD 会在 SAML 响应中发送群组超额声明属性。然后必须使用 Microsoft Graph API 获取群组成员身份。

要集成 Microsoft Azure AD，您需要：

  • 配置 Azure AD 以使极狐GitLab 能够与 Microsoft Graph API 进行通信。
  • 配置极狐GitLab。

极狐GitLab 设置为 Azure AD 字段

极狐GitLab 设置 Azure 字段
租户 ID Directory (tenant) ID
客户端 ID Application (client) ID
客户端 Secret Value (on Certificates & secrets page)

配置 Azure AD

  1. 在 Azure 门户 中，转到 Azure Active Directory > App registrations > All applications，然后选择您的极狐GitLab SAML 应用程序。
  2. 在 Essentials 下，显示 Application (client) ID 和 Directory (tenant) ID 值。复制这些值，因为您需要它们来进行极狐GitLab 配置。
  3. 在左侧导航中，选择 Certificates & secrets。
  4. 在 Client secrets 选项卡上，选择 New client secret。
    1. 在 Description 文本框中，添加描述。
    2. 在 Expires 下拉列表中，设置凭证的过期日期。如果 secret 过期，极狐GitLab 集成在凭证更新之前都不再起作用。
    3. 要生成凭据，请选择 *Add。
    4. 复制凭证的 Value。该值仅显示一次，您需要它来进行极狐GitLab 配置。
  5. 在左侧导航中，选择 API permissions。
  6. 选择 Microsoft Graph > Application permissions。
  7. 选择复选框 GroupMember.Read.All 和 User.Read.All。
  8. 选择 Add permissions 进行保存。
  9. 选择 Grant admin consent for <application_name>，然后在确认对话框中选择 Yes。两个权限的 Status 列应更改为带有 Granted for <application_name> 的绿色复选标记。

配置极狐GitLab

为 JihuLab.com 群组配置：

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

为私有化部署配置：

  1. 配置实例的 SAML SSO。
  2. 在左侧边栏中，选择 搜索或转到。
  3. 选择 管理中心。
  4. 选择 设置 > 通用。
  5. 在 Microsoft Azure 集成 部分中，选中 为此群组启用 Microsoft Azure 集成 复选框。
  6. 输入之前在 Azure 门户中配置 Azure Active Directory 时获取的 租户 ID、客户端 ID 和 客户端 secret。
  7. 可选。如果使用 Azure AD China，请输入相应的 登录 API 端点 和 Graph API 端点。默认值适用于大多数组织。
  8. 选择 保存更改。

使用此配置，如果用户使用 SAML 登录并且 Azure 在响应中发送群组超额声明，极狐GitLab 会启动群组同步作业来调用 Microsoft Graph API 并检索用户的群组成员身份。 然后，极狐GitLab 群组成员身份将根据 SAML 群组链接进行更新。

全局 SAML 群组成员身份锁定

  • 引入于极狐GitLab 15.10。

极狐GitLab 管理员可以使用全局 SAML 群组成员资格锁定功能来防止群组成员邀请新成员加入其成员资格与 SAML 群组链接同步的子群组。

全局群组成员身份锁定仅适用于配置了 SAML 群组链接同步的顶级群组的子群组。任何用户都不能修改为 SAML 群组链接同步配置的顶级群组的成员身份。

启用全局群组成员身份锁定时：

  • 只有管理员可以管理任何群组的成员身份，包括访问级别。
  • 用户不能：
    • 与其他群组共享项目。
    • 邀请成员加入在群组中创建的项目。

要启用全局群组成员身份锁定：

  1. 为您的私有化部署极狐GitLab 实例配置 SAML。
  2. 在左侧导航栏，底部，选择 管理员。
  3. 在左侧边栏中，选择 设置 > 通用。
  4. 展开 可见性和访问控制 部分。
  5. 确保选中 将成员身份锁定到 SAML 同步 复选框。

自动成员移除

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

例如，在下图中：

  • Alex Garcia 登录极狐GitLab 并从极狐GitLab 群组 C 中移除，因为他们不属于 SAML 群组 C。
  • Sidney Jones 属于 SAML 群组 C，但未添加到极狐GitLab 群组 C 中，因为他们尚未登录。
graph TB subgraph SAML users SAMLUserA[Sidney Jones] SAMLUserB[Zhang Wei] SAMLUserC[Alex Garcia] SAMLUserD[Charlie Smith] end subgraph SAML groups SAMLGroupA["Group A"] --> SAMLGroupB["Group B"] SAMLGroupA --> SAMLGroupC["Group C"] SAMLGroupA --> SAMLGroupD["Group D"] end SAMLGroupB --> |Member|SAMLUserA SAMLGroupB --> |Member|SAMLUserB SAMLGroupC --> |Member|SAMLUserA SAMLGroupC --> |Member|SAMLUserB SAMLGroupD --> |Member|SAMLUserD SAMLGroupD --> |Member|SAMLUserC
graph TB subgraph GitLab users GitLabUserA[Sidney Jones] GitLabUserB[Zhang Wei] GitLabUserC[Alex Garcia] GitLabUserD[Charlie Smith] end subgraph GitLab groups GitLabGroupA["Group A (SAML configured)"] --> GitLabGroupB["Group B (SAML Group Link not configured)"] GitLabGroupA --> GitLabGroupC["Group C (SAML Group Link configured)"] GitLabGroupA --> GitLabGroupD["Group D (SAML Group Link configured)"] end GitLabGroupB --> |Member|GitLabUserA GitLabGroupC --> |Member|GitLabUserB GitLabGroupC --> |Member|GitLabUserC GitLabGroupD --> |Member|GitLabUserC GitLabGroupD --> |Member|GitLabUserD
graph TB subgraph GitLab users GitLabUserA[Sidney Jones] GitLabUserB[Zhang Wei] GitLabUserC[Alex Garcia] GitLabUserD[Charlie Smith] end subgraph GitLab groups after Alex Garcia signs in GitLabGroupA[Group A] GitLabGroupA["Group A (SAML configured)"] --> GitLabGroupB["Group B (SAML Group Link not configured)"] GitLabGroupA --> GitLabGroupC["Group C (SAML Group Link configured)"] GitLabGroupA --> GitLabGroupD["Group D (SAML Group Link configured)"] end GitLabGroupB --> |Member|GitLabUserA GitLabGroupC --> |Member|GitLabUserB GitLabGroupD --> |Member|GitLabUserC GitLabGroupD --> |Member|GitLabUserD

属于多个 SAML 群组的用户自动从极狐GitLab 群组中移除

将 Azure AD 与 SAML 结合使用时，如果组织中的用户是 150 多个群组的成员，并且您使用 SAML 群组同步，则该用户可能会失去其群组成员身份。 有关更多信息，请参阅 Microsoft 群组超额的相关内容。

极狐GitLab 具有 Microsoft Azure Active Directory 集成 功能，可为拥有 150 多个群组成员身份的用户的组织启用 SAML 群组同步。此集成使用 Microsoft Graph API 来获取所有用户成员资格，且不限于 150 个群组。

否则，您可以通过更改群组声明以使用 Groups assigned to the application 选项来解决这个问题。

Manage Group Claims.