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

SAML 故障排除

Tier: Free, Premium, Ultimate
Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated

本页面包含使用以下功能时可能遇到的问题的解决方案：

GitLab.com 组的 SAML SSO。
GitLab 自托管实例级别的 SAML OmniAuth Provider。
使用 Switchboard 配置 GitLab Dedicated 实例的 SAML。

SAML 调试工具

SAML 响应使用 base64 编码。要即时解码它们，您可以使用 SAML-tracer 浏览器扩展（Firefox，Chrome）。

如果您无法安装浏览器插件，可以改为手动生成和捕获 SAML 响应。

请特别关注：

NameID，我们用它来标识正在登录的用户。如果用户之前登录过，这个值必须与我们存储的值匹配。
X509Certificate 的存在，我们需要它来验证响应签名。
SubjectConfirmation 和 Conditions，如果配置错误可能导致错误。

生成 SAML 响应

使用 SAML 响应在尝试使用身份提供者登录时，预览断言列表中发送的属性名称和值。

要生成 SAML 响应：

安装其中一个浏览器调试工具。
打开一个新的浏览器标签页。
打开 SAML 追踪器控制台：
- Chrome：在页面的上下文菜单中，选择检查，然后在开发者控制台中选择SAML 选项卡。
- Firefox：选择位于浏览器工具栏上的 SAML-tracer 图标。
对于 GitLab.com 组：
- 转到该组的 GitLab 单点登录 URL。
- 选择授权或尝试登录
对于 GitLab 自托管实例：
- 转到实例首页
- 点击 SAML Login 按钮登录
在追踪器控制台中会显示一个 SAML 响应，类似于这个示例 SAML 响应。
在 SAML 追踪器中，选择导出图标以 JSON 格式保存响应。

手动生成 SAML 响应

有关概述，请观看 GitLab Support 上传的此视频（关于不使用浏览器插件手动生成 SAML 响应，使用 Google Chrome）。

无论您使用什么浏览器，过程都类似于以下步骤：

在新浏览器上右键单击，点击检查以打开开发者工具窗口。
选择网络选项卡。确保选中保留日志。
切换到浏览器页面并使用 SAML SSO 登录 GitLab。
切换回开发者工具窗口，筛选 callback 事件。
为 callback 事件选择负载选项卡，右键单击复制值。
将此值粘贴到以下命令中：echo "<value>" | base64 --decode > saml_response.xml。
在代码编辑器中打开 saml_response.xml。

如果您的代码编辑器中安装了 XML “美化"工具，您应该能够自动格式化响应以便于阅读。

在 Rails 日志中搜索 SAML 登录

Tier: Free, Premium, Ultimate
Offering: GitLab Self-Managed

您可以在 audit_json.log 文件中找到有关 SAML 登录的详细信息。

例如，通过搜索 system_access，您可以找到显示用户何时使用 SAML 登录 GitLab 的条目：

{
  "severity": "INFO",
  "time": "2024-08-13T06:05:35.721Z",
  "correlation_id": "01J555EZK136DQ8S7P32G9GEND",
  "meta.caller_id": "OmniauthCallbacksController#saml",
  "meta.remote_ip": "45.87.213.198",
  "meta.feature_category": "system_access",
  "meta.user": "bbtest",
  "meta.user_id": 16,
  "meta.client_id": "user/16",
  "author_id": 16,
  "author_name": "[email protected]",
  "entity_id": 16,
  "entity_type": "User",
  "created_at": "2024-08-13T06:05:35.708+00:00",
  "ip_address": "45.87.213.198",
  "with": "saml",
  "target_id": 16,
  "target_type": "User",
  "target_details": "[email protected]",
  "entity_path": "bbtest"
}

如果您已配置 SAML 组链接，日志还会显示删除成员资格的条目：

{
  "severity": "INFO",
  "time": "2024-08-13T05:24:07.769Z",
  "correlation_id": "01J55330SRTKTD5CHMS96DNZEN",
  "meta.caller_id": "Auth::SamlGroupSyncWorker",
  "meta.remote_ip": "45.87.213.206",
  "meta.feature_category": "system_access",
  "meta.client_id": "ip/45.87.213.206",
  "meta.root_caller_id": "OmniauthCallbacksController#saml",
  "id": 179,
  "author_id": 6,
  "entity_id": 2,
  "entity_type": "Group",
  "details": {
    "remove": "user_access",
    "member_id": 7,
    "author_name": "BB Test",
    "author_class": "User",
    "target_id": 6,
    "target_type": "User",
    "target_details": "BB Test",
    "custom_message": "Membership destroyed",
    "ip_address": "45.87.213.198",
    "entity_path": "group1"
  },

您还可以在 auth_json.log 中看到 GitLab 从 SAML 提供者收到的用户详细信息，例如：

{
  "severity": "INFO",
  "time": "2024-08-20T07:01:20.979Z",
  "correlation_id": "01J5Q9E59X4P40ZT3MCE35C2A9",
  "meta.caller_id": "OmniauthCallbacksController#saml",
  "meta.remote_ip": "xxx.xxx.xxx.xxx",
  "meta.feature_category": "system_access",
  "meta.client_id": "ip/xxx.xxx.xxx.xxx",
  "payload_type": "saml_response",
  "saml_response": {
    "issuer": [
      "https://sts.windows.net/03b8c6c5-104b-43e2-aed3-abb07df387cc/"
    ],
    "name_id": "ab260d59-0317-47f5-9afb-885c7a1257ab",
    "name_id_format": "urn:oasis:names:tc:SAML:2.0:nameid-format:persistent",
    "name_id_spnamequalifier": null,
    "name_id_namequalifier": null,
    "destination": "https://dh-gitlab.agounder.com/users/auth/saml/callback",
    "audiences": [
      "https://dh-gitlab.agounder.com/16.11.6"
    ],
    "attributes": {
      "http://schemas.microsoft.com/identity/claims/tenantid": [
        "03b8c6c5-104b-43e2-aed3-abb07df387cc"
      ],
      "http://schemas.microsoft.com/identity/claims/objectidentifier": [
        "ab260d59-0317-47f5-9afb-885c7a1257ab"
      ],
      "http://schemas.microsoft.com/identity/claims/identityprovider": [
        "https://sts.windows.net/03b8c6c5-104b-43e2-aed3-abb07df387cc/"
      ],
      "http://schemas.microsoft.com/claims/authnmethodsreferences": [
        "http://schemas.microsoft.com/ws/2008/06/identity/authenticationmethod/password"
      ],
      "email": [
        "[email protected]"
      ],
      "firstname": [
        "BB"
      ],
      "name": [
        "[email protected]"
      ],
      "lastname": [
        "Test"
      ]
    },
    "in_response_to": "_f8863f68-b5f1-43f0-9534-e73933e6ed39",
    "allowed_clock_drift": 2.220446049250313e-16,
    "success": true,
    "status_code": "urn:oasis:names:tc:SAML:2.0:status:Success",
    "status_message": null,
    "session_index": "_b4f253e2-aa61-46a4-902b-43592fe30800",
    "assertion_encrypted": false,
    "response_id": "_392cc747-7c8b-41de-8be0-23f5590d5ded",
    "assertion_id": "_b4f253e2-aa61-46a4-902b-43592fe30800"
  }
}

测试 GitLab SAML

您可以使用以下方法之一来排查 SAML 问题：

使用 Docker Compose 构建的包含 SAML 测试环境的完整 GitLab。
如果您只需要一个 SAML 提供者，可以使用快速入门指南启动 Docker 容器，该容器即插即用 SAML 2.0 身份提供者。
通过在 GitLab 自托管实例上为组启用 SAML创建本地环境。

验证配置

为方便起见，我们包含了一些示例资源，这些资源是我们的支持团队使用的。虽然它们可能帮助您验证 SAML 应用配置，但不能保证反映第三方产品的当前状态。

计算指纹

在配置 idp_cert_fingerprint 时，应尽可能使用 SHA256 指纹。SHA1 也受支持，但不推荐。您可以通过在证书文件上运行以下命令来计算指纹：

openssl x509 -in <certificate.crt> -noout -fingerprint -sha256

将 <certificate.crt> 替换为证书文件名。

SSO 证书更新

当用于身份提供者的证书更改时（例如更新或续订证书），您也必须更新证书指纹。您可以在身份提供者的 UI 中找到证书指纹。如果无法在身份提供者 UI 中获取证书，请按照计算指纹文档中的步骤操作。

配置错误

无效的受众

此错误意味着身份提供者不认为 GitLab 是 SAML 请求的有效发送方和接收方。请确保：

将 GitLab 回调 URL 添加到身份提供者服务器的批准受众列表中。
避免在 issuer 字符串中使用尾随空格。

密钥验证错误、摘要不匹配或指纹不匹配

这些错误都来自相似的地方，即 SAML 证书。SAML 请求必须使用指纹、证书或验证器进行验证。

对于此要求，请务必考虑以下几点：

如果您使用指纹，请确认您的 SHA256 指纹：
1. 重新下载证书文件。
2. 计算指纹。
3. 将指纹与 idp_cert_fingerprint 中提供的值进行比较。这些值应该相同。
如果设置中未提供证书，则需要提供指纹或指纹验证器，并且服务器的响应必须包含证书（<ds:KeyInfo><ds:X509Data><ds:X509Certificate>）。
如果设置中提供了证书，则请求中不再需要包含证书。在这种情况下，指纹或指纹验证器是可选的。

如果上述任何场景都不适用，请求将失败并显示其中一个提到的错误。

缺少声明，或 “Email can’t be blank” 错误

身份提供者服务器需要传递某些信息，以便 GitLab 创建账户或将登录信息与现有账户匹配。email 是需要传递的最少信息。如果身份提供者服务器不提供此信息，所有 SAML 请求都将失败。

请确保提供此信息。

导致此错误的另一个问题是，当身份提供者正在发送正确的信息，但属性与 OmniAuth info 哈希中的名称不匹配时。在这种情况下，您必须在 SAML 配置中设置 attribute_statements，以将 SAML 响应中的属性名称映射到相应的 OmniAuth info 哈希名称。

用户登录横幅错误消息

消息：“SAML authentication failed: SAML NameID is missing from your SAML response.”

您可能会收到错误消息，显示 SAML authentication failed: SAML NameID is missing from your SAML response. Please contact your administrator.

当您尝试使用组 SSO 登录 GitLab 时，如果您的 SAML 响应未包含 NameID，就会发生此问题。

要解决此问题：

联系您的管理员，确保您的 IdP 账户已分配 NameID。
使用 SAML 调试工具验证您的 SAML 响应有有效的 NameID。

消息：“SAML authentication failed: Extern uid has already been taken.”

您可能会收到错误消息，显示 SAML authentication failed: Extern uid has already been taken. Please contact your administrator to generate a unique external_uid (NameID).

当您尝试将现有的 GitLab 账户链接到使用组 SSO 的 SAML 身份时，但存在一个具有您当前 NameID 的现有 GitLab 账户，就会发生此问题。

要解决此问题，请告诉您的管理员为您的 IdP 账户重新生成唯一的 Extern UID（NameID）。确保这个新的 Extern UID 遵循 GitLab NameID 约束。

如果您不想使用该 GitLab 用户进行 SAML 登录，您可以将 GitLab 账户与 SAML 应用解除关联。

消息：“SAML authentication failed: User has already been taken”

您登录的用户已经链接到不同的身份，或者 NameID 值已更改。以下是可能的原因和解决方案：

原因	解决方案
您尝试为同一用户链接多个 SAML 身份，针对给定的身份提供者。	更改您登录的身份。为此，在尝试再次登录之前，将之前的 SAML 身份解除关联
每次用户请求 SSO 身份验证时，`NameID` 都会更改	检查 `NameID` 是否设置为 `Transient` 格式，或者 `NameID` 在后续请求中没有更改

消息：“SAML authentication failed: Email has already been taken”

原因	解决方案
如果存在具有相同电子邮件地址的 GitLab 用户账户，但该账户未与 SAML 身份关联。	在 GitLab.com 上，用户需要链接他们的账户。在 GitLab 自托管上，管理员可以配置实例在用户首次登录时自动将 SAML 身份与 GitLab 用户账户关联。

用户账户通过以下方式之一创建：

用户注册
通过 OAuth 登录
通过 SAML 登录
SCIM 供应

错误：user has already been taken

同时收到这两个错误表明，身份提供者提供的 NameID 大小写与该用户的先前值不完全匹配：

SAML authentication failed: Extern UID has already been taken
User has already been taken

可以通过配置 NameID 返回一致的值来防止这种情况。为单个用户修复此问题涉及更改用户的标识符。对于 GitLab.com，用户需要将他们的 SAML 从 GitLab 账户解除关联。

消息：“Request to link SAML account must be authorized”

确保尝试将他们的 GitLab 账户链接的用户已作为用户添加到身份提供者的 SAML 应用中。

或者，SAML 响应可能在 samlp:Response 标签中缺少 InResponseTo 属性，这是SAML gem 所期望的。身份提供者管理员应确保登录是由服务提供商发起的，而不仅仅是身份提供者。

消息：`There is already a GitLab account associated with this email address.`

Tier: Premium, Ultimate
Offering: GitLab.com

当用户尝试手动将 SAML 链接到他们现有的 GitLab.com 账户时，可能会看到此消息：

There is already a GitLab account associated with this email address.
Sign in with your existing credentials to connect your organization's account

要解决此问题，用户应检查他们是否使用正确的 GitLab 密码登录。如果以下两个条件都满足，用户首先需要重置密码：

账户是由 SCIM 供应的。
他们是第一次使用用户名和密码登录。

消息：“SAML Name ID and email address do not match your user account”

Tier: Premium, Ultimate
Offering: GitLab.com

用户可能会收到错误消息，显示 “SAML Name ID and email address do not match your user account. Contact an administrator.” 这意味着：

SAML 发送的 NameID 值与现有的 SAML 身份 extern_uid 值不匹配。NameID 和 extern_uid 都区分大小写。有关更多信息，请参阅管理用户 SAML 身份。
SAML 响应未包含电子邮件地址，或者电子邮件地址与用户的 GitLab 电子邮件地址不匹配。

解决方法是 GitLab 组所有者使用 SAML API 更新用户的 SAML extern_uid。 extern_uid 值必须与 SAML 身份提供者（IdP）发送的 Name ID 值匹配。根据 IdP 配置，这可能是一个生成的唯一 ID、电子邮件地址或其他值。

错误：响应中缺少证书元素（`ds:x509certificate`）

此错误表明 IdP 未配置在 SAML 响应中包含 X.509 证书：

Certificate element missing in response (ds:x509certificate) and not cert provided at settings

必须在响应中包含 X.509 证书。要解决此问题，请配置您的 IdP 在 SAML 响应中包含 X.509 证书。

有关更多信息，请参阅有关在您的 IdP 上为 SAML 应用进行额外配置的文档。

其他用户登录问题

验证 `NameID`

在故障排除中，任何已认证的用户都可以通过访问 https://gitlab.com/api/v4/user 并检查身份下的 extern_uid 来验证 GitLab 已链接到其用户的 NameID。

对于 GitLab 自托管，管理员可以使用用户 API 查看相同的信息。

当为组使用 SAML 时，具有适当权限的角色的组成员可以使用成员 API 查看组成员的组 SAML 身份信息。

然后，这可以通过使用 SAML 调试工具解码消息与身份提供者发送的 NameID 进行比较。我们要求这些匹配以识别用户。

陷入登录"循环”

确保GitLab 单点登录 URL（对于 GitLab.com）或实例 URL（对于 GitLab 自托管）已在身份提供者的 SAML 应用中配置为"登录 URL"（或类似名称的字段）。

对于 GitLab.com，或者，当用户需要将 SAML 链接到他们现有的 GitLab.com 账户时，提供GitLab 单点登录 URL并指示用户不要在首次登录时使用 SAML 应用。

用户收到 404

Tier: Premium, Ultimate
Offering: GitLab.com

如果用户在成功登录后收到 404，请检查您是否配置了 IP 限制。IP 限制设置配置在：

GitLab.com，在组级别。
GitLab 自托管，在实例级别。

由于组的 SAML SSO 是付费功能，您的订阅到期可能导致您在 GitLab.com 上使用 SAML SSO 登录时出现 404 错误。如果所有用户在使用 SAML SSO 尝试登录时都收到 404，请确认在此 SAML SSO 命名空间中使用的是有效订阅。

如果您在使用"验证配置"时在设置期间收到 404，请确保您使用了正确的SHA-1 生成的指纹。

如果用户是第一次尝试登录，并且 GitLab 单点登录 URL尚未配置，他们可能会看到 404。如用户访问部分所述，组所有者需要向用户提供 URL。

如果顶级组通过电子邮件域限制了成员资格，并且具有不允许的电子邮件域的用户尝试使用 SSO 登录，该用户可能会收到 404。用户可能有多个账户，他们的 SAML 身份可能链接到他们的个人账户，该账户具有不同于公司域的电子邮件地址。要检查这一点，请验证以下内容：

顶级组已通过电子邮件域限制成员资格。
在顶级组的审计事件中：
- 您可以看到该用户的使用 GROUP_SAML 身份验证登录操作。
- 通过选择作者名称，用户的用户名与您为 SAML SSO 配置的用户名相同。
  - 如果用户名与您为 SAML SSO 配置的用户名不同，请要求用户将他们的 SAML 身份从个人账户解除关联。

如果所有用户在登录到身份提供者（IdP）后都收到 404：

验证 assertion_consumer_service_url：
- 在 GitLab 配置中，将其与 GitLab 的 HTTPS 端点匹配。
- 在您的 IdP 上设置 SAML 应用时，作为 Assertion Consumer Service URL 或等效字段。
验证 404 是否与用户在 Azure IdP 中分配了过多组有关。
验证 IdP 服务器和 GitLab 上的时钟是否同步到同一时间。

如果一部分用户在登录到 IdP 后收到 404 错误，首先验证如果用户被添加到组然后立即删除会返回哪些审计事件。或者，如果用户可以成功登录，但他们不显示为顶级组的成员：

确保用户已添加到 SAML 身份提供者，如果已配置，则添加SCIM。
使用SCIM API 确保用户的 SCIM 身份的 active 属性为 true。如果 active 属性为 false，您可以执行以下操作之一来可能解决问题：
- 在 SCIM 身份提供者中为用户触发同步。例如，Azure 有"按需供应"选项。
- 在 SCIM 身份提供者中删除并重新添加用户。
- 如果可能，让用户解除他们的账户关联，然后关联他们的账户。
- 使用内部 SCIM API 使用您组的 SCIM 令牌更新用户的 SCIM 身份。如果您不知道您组的 SCIM 令牌，请重置令牌并使用新令牌更新 SCIM 身份提供者应用。示例请求：
```
curl --request PATCH "https://gitlab.example.com/api/scim/v2/groups/test_group/Users/f0b1d561c-21ff-4092-beab-8154b17f82f2" --header "Authorization: Bearer <SCIM_TOKEN>" --header "Content-Type: application/scim+json" --data '{ "Operations": [{"op":"Replace","path":"active","value":"true"}] }'
```

登录后出现 500 错误

Tier: Free, Premium, Ultimate
Offering: GitLab Self-Managed, GitLab Dedicated

如果您在从 SAML 登录页面重定向回 GitLab 时看到"500错误"，这可能表明：

GitLab 无法获取 SAML 用户的电子邮件地址。确保身份提供者使用声明名称 email 或 mail 包含用户电子邮件地址的声明。
您的 gitlab.rb 文件中为 identity provider_cert_fingerprint 或 identity provider_cert 设置的证书不正确。
您的 gitlab.rb 文件设置为启用 identity provider_cert_fingerprint，并且正在提供 identity provider_cert，或者相反。

登录后出现 422 错误

Tier: Free, Premium, Ultimate
Offering: GitLab Self-Managed, GitLab Dedicated

如果您在从 SAML 登录页面重定向回 GitLab 时看到"422错误"，您可能在身份提供者上配置了错误的断言消费者服务（ACS）URL。

确保 ACS URL 指向 https://gitlab.example.com/users/auth/saml/callback，其中 gitlab.example.com 是您的 GitLab 实例的 URL。

如果 ACS URL 正确，您仍然遇到错误，请查看其他故障排除部分。

带有非允许电子邮件的 422 错误

您可能会收到 422 错误，显示"Email is not allowed for sign-up. Please use your regular email address."（电子邮件不允许注册。请使用您的常规电子邮件地址。）

此消息表明您必须从您的域名允许列表或拒绝列表设置中添加或删除域。

要实现此解决方法：

在左侧边栏底部，选择Admin。
选择设置 > 常规。
展开注册限制。
根据需要向允许注册的域名和拒绝注册的域名添加或删除域。
选择保存更改。

用户通过 SAML 登录时被阻止

Tier: Free, Premium, Ultimate
Offering: GitLab Self-Managed, GitLab Dedicated

以下是用户通过 SAML 登录时被阻止的最可能原因：

在配置中，设置了 gitlab_rails['omniauth_block_auto_created_users'] = true，并且这是用户第一次登录。
配置了 required_groups，但用户不是其中一员。

Google Workspace 故障排除提示

Google Workspace 关于SAML 应用错误消息的文档对于调试您在登录时从 Google 收到的错误很有帮助。请特别注意以下 403 错误：

app_not_configured
app_not_configured_for_user

消息：“The member’s email address is not linked to a SAML account”

Tier: Premium, Ultimate
Offering: GitLab.com

当您尝试邀请用户到 GitLab.com 组（或组内的子组或项目）时，此错误会出现，该组已启用SAML SSO 强制。

如果您在尝试邀请用户到组后看到此消息：

确保用户已添加到 SAML 身份提供者。
如果用户有 GitLab.com 账户，请要求他们将 SAML 链接到他们现有的 GitLab.com 账户。否则，请要求用户通过从身份提供者的仪表板访问 GitLab.com创建 GitLab.com 账户，或通过手动注册并链接 SAML 到他们的新账户。
确保用户是顶级组的成员。

此外，请参阅用户在登录后收到 404 的故障排除。

消息：`The SAML response did not contain an email address.`

如果您看到此错误：

The SAML response did not contain an email address.
Either the SAML identity provider is not configured to send the attribute, or the
identity provider directory does not have an email address value for your user

当以下情况发生时会出现此错误：

SAML 响应在 email 或 mail 属性中不包含用户的电子邮件地址。
用户尝试链接 SAML 到他们的账户，但尚未完成身份验证过程。

确保 SAML 身份提供者配置为发送支持的邮件属性：

<Attribute Name="email">
  <AttributeValue>[email protected]‹/AttributeValue>
</Attribute>

从 GitLab 16.7 开始，默认支持以 http://schemas.xmlsoap.org/ws/2005/05/identity/claims 和 http://schemas.microsoft.com/ws/2008/06/identity/claims/ 开头的属性名称。

<Attribute Name="http://schemas.microsoft.com/ws/2008/06/identity/claims/emailaddress">
  <AttributeValue>[email protected]‹/AttributeValue>
</Attribute>