排查员工身份联合问题

本页面介绍如何解决员工身份联合常见问题。

检查 IdP 响应

本部分介绍如何检查身份提供方 (IdP) 的响应，以排查本文档中列出的问题。

基于浏览器的登录

如需检查 IdP 返回的响应，请使用您选择的工具生成 HAR 文件。例如，您可以使用 Google 管理员工具箱 HAR 分析器，该工具提供生成 HAR 文件的说明以及上传和分析该文件的工具。

重要提示：如果您向您的用户请求 HAR 文件，请要求他们在发送之前从 HAR 文件中清除任何个人身份信息 (PII) 和 cookie。

SAML

要检查 SAML IdP 响应，请执行以下步骤：

1. 在针对路径为 /signin-callback 的网址记录的 HAR 文件中找到 SAMLResponse 请求参数的值。
2. 使用您选择的工具（例如，您可以使用 Google 管理员工具箱编码/解码）对其进行解码。

OIDC

如需检查 OIDC IdP 响应，请执行以下步骤：

1. 在针对路径为 /signin-callback 的网址记录的 HAR 文件中查找 id_token 请求参数。
2. 使用您选择的 JWT 调试工具对其进行解码。

gcloud CLI

要在使用 gcloud CLI 时检查 IdP 的响应，请复制运行 gcloud iam workforce-pools create-cred-config 命令时 --credential-source-file 标志中传递的文件内容，然后执行以下步骤：

SAML

使用您自己选择的工具（例如 Google 管理员工具箱编码/解码）对 SAML IdP 响应进行解码。

OIDC

使用您选择的 JWT 调试工具对 OIDC IdP 响应进行解码。

查看日志

如需确定 Google Cloud 是否与 IdP 通信并查看事务信息，您可以检查 Cloud Audit Logs 日志。 要查看日志示例，请参阅审核日志示例。

员工池和提供方管理错误

本部分提供了修复管理池和提供方时可能遇到的常见错误的建议。

权限遭拒

当尝试配置员工身份联合的用户没有 IAM Workforce Pool Admin 角色 (roles/iam.workforcePoolAdmin) 时，就会发生此错误。

INVALID_ARGUMENT：缺少 OIDC 网络单点登录配置

创建 OIDC 员工身份池提供方时，如果未设置 web-sso-response-type 和 web-sso-assertion-claims-behavior 字段，则会出现以下错误：

ERROR: (gcloud.iam.workforce-pools.providers.create-oidc) INVALID_ARGUMENT: Missing OIDC web single sign-on config.

如需解决此错误，请在创建 OIDC 员工身份池提供方时，按照创建提供方部分中的步骤适当地设置字段。

已超出速率限制，请稍后重试。

达到员工池资源的配额限制时，会发生此错误。请联系您的 Google Cloud 客户代表来申请增加配额。

登录错误

本部分提供了修复员工身份联合用户登录时可能遇到的常见错误的建议。

常见的登录错误

特性条件拒绝给定凭据

如果针对员工身份池提供方设置的特性条件不满足，则会发生此错误。

例如，请考虑以下特性条件：

SAML

'gcp-users' in assertion.attributes.groups

OIDC

'gcp-users' in assertion.groups

在这种情况下，如果身份提供方 (IdP) 在 groups 特性中发送的群组列表不包含 gcp-users，则会看到此错误。

要解决此错误，请执行以下步骤：

1. 描述用于登录的提供方，并检查 attributeCondition 是否正确。如需了解条件支持的操作，请参阅语言定义。

2. 按照检查 IdP 响应中的步骤操作，查看 IdP 返回的特性，并确认特性条件格式是否正确。

3. 登录 IdP 的管理控制台，并检查特性条件中引用的 IdP 特性是否设置正确。如有必要，请参阅 IdP 的文档。

映射的特性必须是字符串类型

当错误消息中指定的特性应为单值字符串，但它映射到特性映射中的列表时，SAML 员工身份池提供方会发生此错误。

例如，假设某个 SAML 员工身份池提供方具有特性映射 attribute.role=assertion.attributes.userRole。在 SAML 断言中，Attribute 可以有多个 AttributeValue 标记，如以下示例所示。于是，所有 SAML 特性都被视为列表，因此 assertion.attributes.userRole 是一个列表。

<saml:Attribute Name="userRole">
    <saml:AttributeValue>
      security-admin
    </saml:AttributeValue>
    <saml:AttributeValue>
      user
    </saml:AttributeValue>
</saml:Attribute>

在此示例中，您可能会看到以下错误：

The mapped attribute 'attribute.role' must be of type STRING

要解决此问题，请执行以下步骤：

1. 描述用于登录的提供方，并标识在 attributeMapping 中设置的 IdP 特性。根据错误消息中显示的特性检查特性。在上一个示例中，名为 userRole 的 IdP 特性会映射到 role 特性，并且 role 特性会显示在上述错误示例中。

2. 请按照以下指导来更新特性映射：

   注意：只有 google.groups 接受列表。

   • 如果导致错误的特性是列表值，请确定一个替代的稳定字符串值特性。然后，通过引用第一项，更新特性映射以使用该映射。对于上一个示例，如果将 myRole 标识为替代的单值 IdP 特性，则特性映射将如下所示：

     attribute.role=assertion.attributes.myRole[0]
     

   • 或者，如果已知特性是单值，请更新特性映射以使用列表中的第一项。 对于上一个示例，如果 userRole 仅包含一个角色，您可以使用以下映射：

     attribute.role=assertion.attributes.userRole[0]
     

   • 要从列表中派生稳定的单值标识符，请参阅语言定义并相应地更新特性映射。

请参阅检查 IdP 响应部分，了解 IdP 返回的响应。

无法从给定凭据获取 google.subject 的值

如果无法使用您在员工身份池提供方配置中设置的特性映射来映射必需的声明 google.subject，则会出现此错误。

要解决此错误，请执行以下步骤：

1. 描述提供方，并检查 attributeMapping。确定为 google.subject 配置的映射。如果映射不正确，请更新员工身份池提供方。

2. 如需查看 IdP 返回的响应，请参阅检查 IdP 响应部分。检查在特性映射中映射到 google.subject 的 IdP 响应中特性的值。

   如果值为空或不正确，请登录 IdP 的管理控制台并检查已配置的特性。对于特性，请检查受影响的用户是否具有 IdP 中的相应数据。更新您的 IdP 配置，以相应地更正特性或用户信息。

3. 重新尝试登录。

400。出现了错误。

如果请求未按预期接收或格式不正确，就会发生此错误。

要解决此错误，请执行以下步骤：

1. 按照告知用户如何登录部分中的步骤操作，验证您是否执行了正确的登录步骤。

2. 将您的员工身份池提供方配置与您的 IdP 配置进行比较。

OIDC 登录错误

本部分提供了有关如何解决员工身份联合用户在登录时可能遇到的 OIDC 特定错误的建议。

连接到给定凭据的颁发者时出错

当 OIDC 员工身份池提供方无法访问 OIDC 发现文档或 JWKS URI 时，会发生此错误。

要解决此错误，请执行以下步骤：

1. 描述提供方，并检查配置的 issuerUri。将 /.well-known/openid-configuration 附加到颁发者 URI，以构建发现文档网址。例如，如果您的 issuerUri 为 https://example.com，则发现文档网址将为 https://example.com/.well-known/openid-configuration。

2. 在无痕模式浏览窗口中打开发现文档网址。

   1. 如果网址未打开或浏览器显示 404 错误，请参阅 IdP 的文档以确定正确的颁发者 URI。如有必要，请更新员工身份联合池提供方中的 issuerUri。

      如果您的 IdP 在本地运行，请参阅 IdP 的文档以预配它，以便通过互联网访问。

   2. 如果网址打开，请检查以下情况：

      1. 在传送发现文档之前，请检查网址是否没有多次重定向。如果网址多次重定向，请咨询 IdP 的管理员以解决此问题。
      2. 检查 IdP 响应时间。请咨询您的 IdP 管理员以缩短响应延迟时间。
      3. 打开的发现文档应采用 JSON 格式。

      4. 在 JSON 中查找 jwks_uri 字段。

         1. 验证关联的网址是否也打开了。
         2. 验证网址是否满足本指南前面所述的条件。

   3. 重新尝试登录。

SAML 登录错误

本部分提供了有关如何解决员工身份联合用户在登录时可能遇到的 SAML 特定错误的建议。

未能验证 SAMLResponse 中的签名

如果无法使用您在员工身份池提供方中配置的 IdP 元数据 XML 提供的任何 X.509 证书验证 IdP 响应上的签名，则 SAML 员工身份池提供方会出现此错误。此错误的常见原因是 IdP 上的验证证书已轮替，但未使用最新的 IdP 元数据 XML 文件更新员工身份池提供方配置。

要解决此错误，请执行以下步骤：

1. 可选：按照检查 IdP 响应中的步骤，查看 IdP 返回的响应，并在其中找到 X509Certificate 字段。描述您用于登录的提供方，并检查在员工身份池提供方中设置的 idpMetadataXml 值的 X509Certificate 字段。将证书与 IdP 返回的响应中显示的证书进行比较。证书必须匹配。

2. 登录 IdP 的管理控制台，然后下载最新的元数据 XML。

3. 使用下载的 IdP 元数据 XML 更新员工身份池提供方。

4. 重新尝试登录。

SAML 断言中的收件人未设置为正确的 ACS 网址

当 IdP 响应包含 SubjectConfirmationData 标记的 Recipient 字段的值不正确时，SAML 员工身份池提供方会发生此错误。

要解决此错误，请更新 Recipient URL/Redirect URL 或 IdP 配置中的等效字段，以使用在 IdP 中设置重定向网址所述的重定向网址，然后重试登录。

按照检查 IdP 响应中的步骤操作，查看 IdP 返回的响应，并确认 Recipient 字段正确无误。

例如，对于员工身份池提供方 locations/global/workforcePools/example-pool/providers/example-provider，包含重定向网址的 Recipient 会显示在 IdP 的 SAML 响应中，如下所示：

<SubjectConfirmationData Recipient="https://auth.cloud.google/signin-callback/locations/global/workforcePools/example-pool/providers/example-provider"

SAMLResponse 目标与 RP 回调网址不匹配

当 IdP 响应包含 Response 标记的 Destination 字段的值不正确时，SAML 员工身份池提供方会发生此错误。

要解决此错误，请更新 Destination URL/Redirect URL 或 IdP 配置中的等效字段，以使用在 IdP 中设置重定向网址所述的重定向网址。

按照检查 IdP 响应中的步骤操作，查看 IdP 返回的响应，并确认 Destination 字段正确无误。

例如，对于员工身份池提供方 locations/global/workforcePools/example-pool/providers/example-provider，包含重定向网址的 Destination 将显示在 IdP 的 SAML 响应中，如下所示：

<Response Destination="https://auth.cloud.google/signin-callback/locations/global/workforcePools/example-pool/providers/example-provider"

断言无效：NameID 缺失或空白

当从 IdP 收到的 SAML 响应不包含 NameId 字段或包含空值时，就会发生此错误。

要解决此错误，请参阅 IdP 文档将其配置为发送 NameID，这是 SAML 断言的主题，通常是正在进行身份验证的用户。

注意：即使您决定在特性映射中将其他特性映射到 google.subject，也需要使用 NameID。

按照检查 IdP 响应中的步骤操作，查看 IdP 返回的响应及其设置的 NameID。

所有 <AudienceRestriction> 都应包含 SAML RP 实体 ID

如果来自您的 IdP 的 SAML 响应中的 AudienceRestriction 标记未使用代表员工身份池提供方的实体 ID 的值设置 Audience 标记，则会发生此错误。

要解决此错误，请执行以下步骤：

1. 请参阅 IdP 文档，了解如何在 SAML 响应发送的 AudienceRestriction 标记中配置受众群体。通常，通过在 IdP 配置中设置 Entity ID 或 Audience 字段来配置受众群体。请参阅创建员工身份池提供方 SAML 部分，了解应设置的值 SP Entity ID。

2. 更新 IdP 配置后，重试登录。

按照检查 IdP 响应中的步骤操作，查看 IdP 返回的响应及其设置的 AudienceRestriction。