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

为 GitLab Self-Managed 配置 SCIM

  • 版本：Premium, Ultimate
  • 产品：GitLab Self-Managed

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

  • 创建用户。
  • 屏蔽用户。
  • 重新添加用户（重新激活 SCIM 身份）。

GitLab 内部 SCIM API 实现了 RFC7644 协议 的一部分。

如果您是 GitLab.com 用户，请参阅为 GitLab.com 群组配置 SCIM。

配置 GitLab

先决条件：

要配置 GitLab SCIM：

  1. 在左侧边栏的底部，选择 管理员。
  2. 选择 设置 > 通用。
  3. 展开 SCIM 令牌 部分并选择 生成 SCIM 令牌。
  4. 为了配置您的身份提供商，请保存：
    • 您的 SCIM 令牌 字段中的令牌。
    • SCIM API 端点 URL 字段中的 URL。

配置身份提供商

您可以将以下内容配置为身份提供商：

其他身份提供商可能可以与 GitLab 配合使用，但未经测试且不受支持。您应联系该提供商以获取支持。GitLab 支持团队可以通过查看相关日志条目来提供帮助。

配置 Okta

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

先决条件：

要为 SCIM 配置 Okta：

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

配置 Microsoft Entra ID (以前称为 Azure Active Directory)

先决条件：

在为 Azure Active Directory 设置单点登录 期间创建的 SAML 应用程序必须为 SCIM 进行设置。有关示例，请参阅示例配置。

您必须完全按照以下说明中的详细步骤配置 SCIM 预配。如果配置错误，您将遇到用户预配和登录问题，解决这些问题需要大量工作。如果您在任何步骤中遇到任何问题或疑问，请联系 GitLab 支持。

要配置 Microsoft Entra ID，您需要配置：

  • 用于 SCIM 的 Microsoft Entra ID。
  • 设置。
  • 映射，包括属性映射。

为 SCIM 配置 Microsoft Entra ID

  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 关闭 属性映射 配置页面。
配置属性映射

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

在为 SCIM 配置 Entra ID 时，您需要配置属性映射。有关示例，请参阅示例配置。

下表提供了 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 与 Firstname Lastname 格式不匹配，请使用 Join 表达式。
  3. 这是表达式映射类型，而不是直接映射。在 映射类型 下拉列表中选择 表达式。

每个属性映射都有：

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

对于每个属性：

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

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

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

配置设置

在 设置 部分下：

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

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

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

移除访问权限

在身份提供商上移除或停用用户会阻止该用户访问 GitLab 实例，同时 SCIM 身份仍与 GitLab 用户保持关联。

要更新用户的 SCIM 身份，请使用 GitLab 内部 SCIM API。

重新激活访问权限

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

身份提供商根据其配置的计划执行同步后，用户的 SCIM 身份将被重新激活，并且他们对 GitLab 实例的访问权限也将恢复。

使用 SCIM 进行群组同步

此功能的可用性由功能标志控制。 更多信息，请参阅历史记录。

除了用户预配之外，您还可以使用 SCIM 在您的身份提供商和 GitLab 之间同步群组成员资格。 使用此方法，您可以根据用户在身份提供商中的群组成员资格，自动从 GitLab 群组中添加和移除用户。

先决条件：

  • 必须首先配置 SAML 群组链接。
  • 您身份提供商中的 SAML 群组名称必须与 GitLab 中配置的 SAML 群组名称相匹配。

在您的身份提供商中配置群组同步

有关在身份提供商中配置群组同步的详细说明，请参阅提供商的文档。示例如下：

当多个 SAML 群组链接映射到同一个 GitLab 群组时，用户将被分配所有映射群组链接中的最高角色。如果用户属于链接到该 GitLab 群组的另一个 SAML 群组，则从 IdP 群组中移除的用户仍会保留在该 GitLab 群组中。

故障排除

请参阅我们的 SCIM 故障排除指南。