排查员工身份联合问题

本页介绍了如何解决 Workforce Identity Federation 的常见问题。

检查 IdP 响应

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

基于浏览器的登录

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

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

SAML

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

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

OIDC

如需检查 OIDC IdP 响应，请执行以下步骤。此方法不适用于代码流。

1. 在 HAR 文件中，查找针对路径为 /signin-callback 的网址记录的 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。