Help us learn about your current experience with the documentation. Take the survey.

为 GitLab.com 组配置 SCIM

  • Tier: Premium, Ultimate
  • Offering: GitLab.com

您可以使用开放标准的跨域身份管理系统 (SCIM) 来自动：

  • 创建用户。
  • 移除用户（停用 SCIM 身份）。
  • 重新添加用户（重新激活 SCIM 身份）。

GitLab SAML SSO SCIM 不支持更新用户。

当为 GitLab 组启用 SCIM 时，该组成员身份将在 GitLab 和身份提供商之间同步。

内部 GitLab 组 SCIM API 实现了 RFC7644 协议 的部分内容。 身份提供商可以使用 内部 GitLab 组 SCIM API 来开发 SCIM 应用。

要在 GitLab 自托管版上设置 SCIM，请参阅 为 GitLab 自托管版配置 SCIM。

配置 GitLab

先决条件：

要配置 GitLab SAML SSO SCIM：

  1. 在左侧边栏，选择 搜索或跳转至 并找到您的组。
  2. 选择 设置 > SAML SSO。
  3. 选择 生成 SCIM 令牌。
  4. 为您的身份提供商配置，保存：
    • 您的 SCIM 令牌 字段中的令牌。
    • SCIM API 端点 URL 字段中的 URL。

配置身份提供商

您可以将以下之一配置为身份提供商：

其他提供商可以与 GitLab 协作，但它们未经测试且不受支持。您应该联系提供商获取支持。GitLab 支持可以通过查看相关日志条目来协助。

配置 Microsoft Entra ID（前身为 Azure Active Directory）

先决条件：

在为 Azure Active Directory 设置 单点登录 期间创建的 SAML 应用程序必须设置为支持 SCIM。示例配置请参见 示例配置。

您必须严格按照以下说明配置 SCIM 预配。如果配置错误，您将遇到用户预配和登录问题，这些问题需要大量精力才能解决。如果您在执行任何步骤时遇到问题或有疑问，请联系 GitLab 支持。

要为 Microsoft Entra ID 配置 SCIM：

  1. 在您的应用中，转到 预配 选项卡并选择 开始使用。
  2. 将 预配模式 设置为 自动。
  3. 使用以下值完成 管理员凭据：
    • GitLab 中的 SCIM API 端点 URL 作为 租户 URL 字段。
    • GitLab 中的 您的 SCIM 令牌 作为 机密令牌 字段。
  4. 选择 测试连接。如果测试成功，请在继续之前保存您的配置，或参阅 故障排除 信息。
  5. 选择 保存。

保存后，将出现 映射 和 设置 部分。

配置映射

在 映射 部分，首先预配组：

  1. 选择 预配 Microsoft Entra ID 组。

  2. 在属性映射页面上，关闭 已启用 开关。GitLab 不支持 SCIM 组预配。 保持组预配启用不会破坏 SCIM 用户预配，但会在 Entra ID SCIM 预配日志中导致错误，这些错误可能令人困惑和具有误导性。

    即使 预配 Microsoft Entra ID 组 已禁用，映射部分也可能显示"已启用：是"。此行为是显示错误，您可以安全地忽略。

  3. 选择 保存。

接下来，预配用户：

  1. 选择 预配 Microsoft Entra ID 用户。
  2. 确保 已启用 开关设置为 是。
  3. 确保 目标对象操作 全部启用。
  4. 在 属性映射 下，配置映射以匹配 已配置的属性映射：
    1. 可选。在 customappsso 属性 列中，找到 externalId 并将其删除。
    2. 编辑第一个属性，使其具有：
      • 源属性 为 objectId
      • 目标属性 为 externalId
      • 匹配优先级 为 1
    3. 更新现有的 customappsso 属性以匹配 已配置的属性映射。
    4. 删除不在下表中的任何其他属性。如果不删除它们不会造成问题，但 GitLab 不会使用这些属性。
  5. 在映射列表下方，选择 显示高级选项 复选框。
  6. 选择 编辑 customappsso 的属性列表 链接。
  7. 确保 id 是主要和必需字段，并且 externalId 也是必需的。
  8. 选择 保存，这将返回到属性映射配置页面。
  9. 通过点击右上角的 X 关闭 属性映射 配置页面。

配置设置

在 设置 部分：

  1. 可选。如果需要，选择 发生故障时发送电子邮件通知 复选框。
  2. 可选。如果需要，选择 防止意外删除 复选框。
  3. 如有必要，选择 保存 以确保所有更改都已保存。

配置好映射和设置后，返回应用概览页面并选择 开始预配 以启动 GitLab 中用户的自动 SCIM 预配。

同步后，更改映射到 id 和 externalId 的字段可能会导致错误。这些包括 预配错误、重复用户，并可能阻止现有用户访问 GitLab 组。

配置属性映射

在 Microsoft 从 Azure Active Directory 过渡到 Entra ID 命名方案时，您可能会注意到 用户界面中的不一致性。如果您遇到问题，可以查看此文档的旧版本或联系 GitLab 支持。

在 为 Entra ID 配置 SCIM 时，您配置 属性映射。示例配置请参见 示例配置。

下表提供了 GitLab 所需的属性映射。

源属性 目标属性 匹配优先级
objectId externalId 1
userPrincipalName 或 mail 1 emails[type eq "work"].value
mailNickname userName
displayName 或 Join(" ", [givenName], [surname]) 2 name.formatted
Switch([IsSoftDeleted], , "False", "True", "True", "False") 3 active
  1. 当 userPrincipalName 不是电子邮件地址或无法送达时，使用 mail 作为源属性。
  2. 如果您的 displayName 不符合 名字 姓氏 格式，请使用 Join 表达式。
  3. 这是表达式映射类型，而不是直接映射。在 映射类型 下拉列表中选择 表达式。

每个属性映射都有：

  • 一个 customappsso 属性，对应 目标属性。
  • 一个 Microsoft Entra ID 属性，对应 源属性。
  • 一个匹配优先级。

对于每个属性：

  1. 编辑现有属性或添加新属性。
  2. 从下拉列表中选择所需的源和目标属性映射。
  3. 选择 确定。
  4. 选择 保存。

如果您的 SAML 配置与 推荐的 SAML 设置 不同，请选择映射 属性并相应地进行修改。映射到 externalId 目标属性的源属性必须与用于 SAML NameID 的属性匹配。

如果表中未列出映射，请使用 Microsoft Entra ID 默认值。有关所需属性列表，请参阅 内部组 SCIM API 文档。

配置 Okta

在为 Okta 设置 单点登录 期间创建的 SAML 应用程序必须设置为支持 SCIM。

先决条件：

要为 Okta 配置 SCIM：

  1. 登录 Okta。
  2. 在右上角，选择 管理。从 管理 区域看不到此按钮。
  3. 在 应用程序 选项卡中，选择 浏览应用目录。
  4. 搜索 GitLab，找到并选择 GitLab 应用程序。
  5. 在 GitLab 应用程序概览页面上，选择 添加。
  6. 在 应用程序可见性 下，选择两个复选框。目前 GitLab 应用程序不支持 SAML 身份验证，因此不应向用户显示该图标。
  7. 选择 完成 以完成添加应用程序。
  8. 在 预配 选项卡中，选择 配置 API 集成。
  9. 选择 启用 API 集成。
    • 对于 基本 URL，粘贴您从 GitLab SCIM 配置页面的 SCIM API 端点 URL 复制的 URL。
    • 对于 API 令牌，粘贴您从 GitLab SCIM 配置页面的 您的 SCIM 令牌 复制的令牌。
  10. 要验证配置，选择 测试 API 凭据。
  11. 选择 保存。
  12. 保存 API 集成详细信息后，左侧会出现新的设置选项卡。选择 到应用程序。
  13. 选择 编辑。
  14. 为 创建用户 和 停用用户 选择 启用 复选框。
  15. 选择 保存。
  16. 在 分配 选项卡中分配用户。分配的用户将在您的 GitLab 组中创建和管理。

用户访问

在同步过程中，所有新用户：

下图描述了当您将用户添加到 SCIM 应用程序时发生的情况：

%%{init: { "fontFamily": "GitLab Sans" }}%%
graph TD
accTitle: 将用户添加到您的 SCIM 应用程序
accDescr: GitLab 如何确定是否将 SCIM 身份与用户关联。

  A[将用户添加到 SCIM 应用程序] -->|IdP 向 GitLab 发送用户信息| B(GitLab: 电子邮件是否存在?)
  B -->|否| C[GitLab 创建带有 SCIM 身份的用户]
  B -->|是| D(GitLab: 用户是否属于该组?)
  D -->|否| E(GitLab: 是否启用了 SSO 强制执行?)
  E -->|否| G
  E -->|是| F[GitLab 发送回消息:
               成员的电子邮件地址未链接到 SAML 账户]
  D -->|是| G[将 SCIM 身份关联到用户]

在预配过程中：

  • 检查 GitLab 用户账户是否存在时，会同时考虑主要和次要电子邮件。
  • 通过在创建用户时添加后缀 1 来处理重复的用户名。例如，如果 test_user 已存在， 则使用 test_user1。如果 test_user1 已存在，GitLab 会递增后缀以查找未使用的用户名。 如果在 4 次尝试后未找到未使用的用户名，则会将随机字符串附加到用户名上。

在后续访问中，新用户和现有用户可以通过以下方式访问组：

  • 通过身份提供商的仪表板。
  • 通过直接访问链接。

有关角色信息，请参阅 组级 SAML 页面。

通过 SCIM 为 GitLab 组创建的用户密码

GitLab 要求所有用户账户都有密码。对于使用 SCIM 预配创建的用户，GitLab 会自动 生成随机密码，用户在首次登录时无需设置密码。有关 GitLab 如何为通过 SCIM 为 GitLab 组创建的用户 生成密码的更多信息，请参阅 为通过集成身份验证方法创建的用户生成密码。

链接 SCIM 和 SAML 身份

如果配置了 组级 SAML 并且您拥有现有的 GitLab.com 账户，用户可以链接他们的 SCIM 和 SAML 身份。用户应该在启用同步之前执行此操作，因为在同步处于活动状态时，现有用户可能会出现预配错误。

要链接您的 SCIM 和 SAML 身份：

  1. 更新您 GitLab.com 用户账户中的 主要电子邮件 地址， 以匹配您身份提供商中的用户配置文件电子邮件地址。
  2. 链接您的 SAML 身份。

移除访问权限

在身份提供商上移除或停用用户，以移除他们对以下内容的访问权限：

  • 顶级组。
  • 所有子组和项目。

在身份提供商根据其配置的计划执行同步后， 用户的成员资格将被撤销，他们将失去访问权限。

当您启用 SCIM 时，这不会自动移除没有 SAML 身份的现有用户。

取消预配不会删除 GitLab 用户账户。

%%{init: { "fontFamily": "GitLab Sans" }}%%
graph TD
accTitle: 取消预配用户
accDescr: 如何从您的 SCIM 应用程序中移除用户并将其从 GitLab 组中移除。

  A[从 SCIM 应用程序中移除用户] -->|IdP 向 GitLab 发送请求| B(GitLab: 用户是否属于该组?)
  B -->|否| C[无需操作]
  B -->|是| D[GitLab 从 GitLab 组中移除用户]

重新激活访问权限

用户通过 SCIM 被移除或停用后，您可以通过 将他们添加到 SCIM 身份提供商来重新激活该用户。

在身份提供商根据其配置的计划执行同步后， 用户的 SCIM 身份将被重新激活，其组成员资格将得到恢复。