SCIM 故障排除

本节包含您可能遇到的问题的解决方案。

用户被移除后无法添加

当您移除用户时，用户会被从组中移除，但他们的账户不会被删除 （请参阅移除访问权限）。

当用户被重新添加到 SCIM 应用时，GitLab 不会创建新用户，因为该用户已存在。

从 2023 年 8 月 11 日起，skip_saml_identity_destroy_during_scim_deprovision 功能标志已启用。

对于从该日期起通过 SCIM 停用 provision 的用户，其 SAML 身份不会被移除。 当该用户被重新添加到 SCIM 应用时：

• 他们的 SCIM 身份 active 属性被设置为 true。
• 他们可以使用 SSO 登录。

对于在该日期之前通过 SCIM 停用 provision 的用户，其 SAML 身份会被销毁。 要解决此问题，用户必须将 SAML 链接到其现有的 GitLab.com 账户。

GitLab Self-Managed

对于 GitLab Self-Managed，该实例的管理员可以手动添加用户身份。如果管理员需要重新添加多个身份，这可能会节省时间。

用户无法登录

以下是用户无法登录问题的可能解决方案：

• 确保用户已添加到 SCIM 应用。
• 如果收到"用户未链接到 SAML 账户"错误，用户可能已在 GitLab 中存在。让用户按照链接 SCIM 和 SAML 身份的说明操作。 或者，Self-Managed 管理员可以添加用户身份。
• GitLab 存储的 Identity (extern_uid) 值会在 id 或 externalId 更改时由 SCIM 更新。除非登录方式的 GitLab 标识符 (extern_uid) 与提供商发送的 ID（例如 SAML 发送的 NameId）匹配，否则用户无法登录。此值也由 SCIM 用于匹配用户的 id，并在 id 或 externalId 值更改时由 SCIM 更新。
• 在 GitLab.com 上，SCIM id 和 SCIM externalId 必须配置为与 SAML NameId 相同的值。您可以使用调试工具追踪 SAML 响应，并将任何错误与SAML 故障排除信息进行核对。

不确定用户的 SAML NameId 是否与 SCIM externalId 匹配

要检查用户的 SAML NameId 是否与其 SCIM externalId 匹配：

• 管理员可以使用 Admin 区域列出用户的 SCIM 身份。
• 组所有者可以在组 SAML SSO 设置页面中查看用户列表和为每个用户存储的标识符。
• 您可以使用SCIM API手动检索 GitLab 为用户存储的 extern_uid，并将其与从SAML API获取的每个用户的值进行比较。
• 让用户使用SAML Tracer，并将 extern_uid 与作为 SAML NameId 返回的值进行比较。

SCIM extern_uid 与 SAML NameId 不匹配

无论值是否更改或您需要映射到不同字段，以下内容必须映射到同一字段：

• extern_Id
• NameId

如果 SCIM extern_uid 与 SAML NameId 不匹配，您必须更新 SCIM extern_uid 以使用户能够登录。

如果您修改 SCIM 身份提供商使用的字段（通常是 extern_Id），请谨慎操作。 您的身份提供商应配置为执行此更新。 在某些情况下，身份提供商无法执行更新，例如当用户查找失败时。

GitLab 使用这些 ID 查找用户。 如果身份提供商不知道这些字段的当前值， 该提供商可能会创建重复用户，或无法完成预期的操作。

要将标识符值更改为匹配，您可以执行以下操作之一：

• 让用户取消链接并重新链接自己，基于 SAML 身份验证失败：用户已被占用 部分。

• 通过在启用 provision 的同时从 SCIM 应用中移除所有用户，同时取消链接所有用户。

  这会将顶级组和子组中所有用户的角色重置为配置的默认成员角色。

• 使用SAML API或SCIM API手动更正为用户存储的 extern_uid 以匹配 SAML NameId 或 SCIM externalId。

您不得：

• 将这些值更新为不正确的值，因为这会导致用户无法登录。
• 为错误的用户分配值，因为这会导致用户登录到错误的账户。

此外，用户的主电子邮件必须与您的 SCIM 身份提供商中的电子邮件匹配。

更改 SCIM 应用

当 SCIM 应用更改时：

• 用户可以按照更改 SAML 应用部分的说明操作。
• 身份提供商的管理员可以：
  1. 从 SCIM 应用中移除用户，这将：
     • 在 GitLab.com 中，从组中移除所有已移除的用户。
     • 在 GitLab Self-Managed 中，阻止用户。
  2. 为新的 SCIM 应用开启同步，以链接现有用户。

SCIM 应用返回 "User has already been taken","status":409 错误

更改 SAML 或 SCIM 配置或提供商可能导致以下问题：

• SAML 和 SCIM 身份不匹配。要解决此问题：
  1. 验证用户的 SAML NameId 是否与 SCIM extern_uid 匹配。
  2. 更新或修复不匹配的 SCIM extern_uid 和 SAML NameId。
• GitLab 与身份提供商 SCIM 应用之间的 SCIM 身份不匹配。要解决此问题：
  1. 使用SCIM API，该 API 显示 GitLab 中存储的用户 extern_uid，并将其与 SCIM 应用中的用户 externalId 进行比较。
  2. 使用相同的 SCIM API 更新 GitLab.com 上用户的 SCIM extern_uid。

该成员的电子邮件地址不允许用于此组

SCIM provision 可能会失败，HTTP 状态为 412，并显示以下错误消息：

该成员的电子邮件地址不允许用于此组。请联系您的管理员。

当以下两个条件都满足时，会发生此错误：

• 已为该组配置按域限制组访问。
• 正在 provision 的用户账户具有不被允许的电子邮件域。

要解决此问题，您可以执行以下任一操作：

• 将用户账户的电子邮件域添加到允许的域列表中。
• 通过移除所有域来禁用按域限制组访问功能。

在 Rails 日志中搜索 SCIM 请求

GitLab.com 管理员可以在 Kibana 中使用 pubsub-rails-inf-gprd-* 索引在 api_json.log 中搜索 SCIM 请求。使用以下过滤器基于内部组 SCIM API：

• json.path: /scim/v2/groups/<group-path>
• json.params.value: <externalId>

在相关日志条目中，json.params.value 显示 GitLab 接收的 SCIM 参数值。使用这些值 验证身份提供商的 SCIM 应用中配置的 SCIM 参数是否按预期传达给 GitLab。

例如，使用这些值作为权威来源，说明为什么账户使用特定详细信息集进行 provision。此信息可以帮助解决账户使用与 SCIM 应用配置不匹配的详细信息进行 SCIM provision 的问题。

SCIM 日志中成员的电子邮件地址未链接错误

当您尝试在 GitLab.com 上 provision SCIM 用户时，GitLab 会检查 是否已存在具有该电子邮件地址的用户。当以下情况发生时，您可能会看到以下错误：

• 用户存在，但没有链接的 SAML 身份。
• 用户存在，具有 SAML 身份，并且具有设置为 active: false 的 SCIM 身份。
• 用户存在，但不是相关顶级组的成员，并且已启用 SAML SSO 强制执行。

该成员的电子邮件地址未链接到 SAML 账户或具有非活动的 SCIM 身份。

此错误消息与状态 412 一起返回。

这可能会影响受影响的最终用户正确访问其账户。

第一个解决方法是：

1. 让最终用户将 SAML 链接到其现有的 GitLab.com 账户。
2. 用户执行此操作后，从您的身份提供商启动 SCIM 同步。 如果 SCIM 同步完成且没有相同错误，GitLab 已 成功将 SCIM 身份链接到现有用户账户，用户 现在应该能够使用 SAML SSO 登录。

如果错误仍然存在，用户很可能已存在，同时具有 SAML 和 SCIM 身份，并且 SCIM 身份设置为 active: false。要解决 此问题：

1. 可选。如果您在首次配置 SCIM 时未保存 SCIM 令牌，生成新令牌。如果您生成新的 SCIM 令牌，您必须更新身份提供商 SCIM 配置中的令牌，否则 SCIM 将停止工作。

2. 找到您的 SCIM 令牌。

3. 使用 API获取单个 SCIM provision 的用户。

4. 检查返回的信息以确保：

   • 用户的标识符 (id) 和电子邮件与您的身份提供商发送的内容匹配。
   • active 设置为 false。

   如果任何信息不匹配，联系 GitLab 支持。

5. 使用 API将 SCIM provision 的用户的 active 值更新为 true。

6. 如果更新返回状态码 204，让用户尝试使用 SAML SSO 登录。

Azure Active Directory

以下故障排除信息专门针对通过 Azure Active Directory provision 的 SCIM。

验证我的 SCIM 配置是否正确

确保：

• externalId 的匹配优先级为 1。
• SCIM externalId 值与 SAML NameId 值匹配。

检查以下 SCIM 参数的合理值：

• userName
• displayName
• emails[type eq "work"].value

测试连接时出现 invalid credentials 错误

测试连接时，您可能会遇到错误：

您似乎输入了无效的凭据。请确认
您使用的是管理员账户的正确信息

如果 租户 URL 和 密钥令牌 正确，请检查您的组路径是否包含可能被视为无效 JSON 原始字符（如 .）的字符。在组路径中删除或对这些字符进行 URL 编码通常可以解决此错误。

(字段) can't be blank 同步错误

检查 provision 的审核事件时，您有时会看到 命名空间不能为空、名称不能为空，且用户不能为空。错误。

此错误可能发生，因为并非所有必需字段（如名字和姓氏）都存在于正在映射的所有用户中。

作为解决方法，请尝试备用映射：

1. 按照Azure 映射说明操作。
2. 删除 name.formatted 目标属性条目。
3. 将 displayName 源属性更改为具有 name.formatted 目标属性。

无法在源系统和目标系统中匹配条目 组 '组名' 错误

Azure 中的组 provision 可能会失败，并出现 无法在源系统和目标系统中匹配条目 组 '组名'错误。错误响应可能包含 GitLab URL https://gitlab.com/users/sign_in 的 HTML 结果。

此错误是无害的，因为组 provision 已开启，但 GitLab SCIM 集成不支持也不需要它。要删除该错误，请按照 Azure 配置指南中的说明禁用将 Azure Active Directory 组同步到应用名称的选项。

Okta

以下故障排除信息专门针对通过 Okta provision 的 SCIM。

测试 API SCIM 凭据时出现 Error authenticating: null 消息

在您的 Okta SCIM 应用中测试 API 凭据时，您可能会遇到错误：

身份验证错误：null

Okta 需要能够连接到您的 GitLab 实例来 provision 或停用 provision 用户。

在您的 Okta SCIM 应用中，检查 SCIM 基础 URL 是否正确并指向有效的 Gitlab SCIM API 端点 URL。查看以下文档以获取此 URL 的信息：

• GitLab.com 组。
• GitLab Self-Managed。

对于 GitLab Self-Managed，确保您的实例是公开可用的，以便 Okta 可以连接到它。如果需要， 您可以在防火墙上允许访问 Okta IP 地址。