问题排查和常见问题解答

本文档提供了有关 Identity-Aware Proxy (IAP) 的问题排查指南和常见问题解答。

排查网页登录问题

如果您在登录或访问应用时遇到错误，检查浏览器的网络流量有助于诊断问题。

检查网络流量

  1. 在浏览器中打开新的无痕 (Chrome) 或隐私窗口。
  2. 打开浏览器的开发者工具，然后前往网络标签页。
  3. 选择保留日志选项，以捕获重定向期间的所有请求。
  4. 通过前往您遇到问题的网址来重现问题。
  5. 检查日志中的网络请求，找出错误发生的位置。

分析网络流量

当您访问受 IAP 保护的应用时，系统会将您重定向到登录页面。在通过身份提供方成功进行身份验证后，系统会向 https://iap.googleapis.com 网域发出请求以完成身份验证，然后系统会发出 IAP Cookie 并将您重定向到应用。

您可以根据发生错误的网域排查错误：

  • iap.googleapis.com 上的错误：如果 iap.googleapis.com 网域上发生错误，页面上会显示详细的出错提示。如果错误与 IAP 设置有关（例如 OAuth 客户端问题），请调整设置。如果您遇到不知道如何解决的客户端错误，或者看到服务器错误，请提交 Google Cloud 支持服务工单。
  • 应用网域错误：如果您在重定向到受 IAP 保护的应用网域后发生错误，系统会显示错误代码。如需详细了解常见错误，请参阅错误代码部分。如果您无法解决问题，请提交 Google Cloud 支持服务工单。

我可以使用 IAP 保护哪些应用？

IAP 可与以下各项搭配使用：

  • App Engine 标准环境和 App Engine 柔性环境应用

  • 具有 HTTP(S) 负载均衡后端服务的 Compute Engine 实例

  • Google Kubernetes Engine 容器

  • 具有 HTTP(S) 负载均衡后端服务的 Cloud Run 应用

  • 一键式 Cloud Run，无负载均衡后端服务

    IAP 不能与 Cloud CDN 搭配使用。

    登录我的应用后，为什么网址末尾会有 #？

    在某些浏览器中以及在特定条件下，身份验证后，网址后面可能会附加 #。这是正常现象，不会引起登录问题。

    为什么我的请求失败并返回 405 Method Not Allowed？

    如果请求中未附加 Cookie，通常会出现这种情况。默认情况下，JavaScript 方法不会附加 Cookie。

    不同的请求方法需要不同的方法：

    • 对于 XMLHttpRequest，将 withCredentials 设置为 true。

    • 对于 Fetch API，请将 credentials 设置为 include 或 same-origin。

    如需处理与会话相关的错误，请参阅管理 IAP 会话。

    为什么我收到的是HTTP 401 Unauthorized，而不是302 Redirect？

    仅当您的客户端配置为处理重定向时，IAP 才会发送 302 Redirect。

    在请求标头中添加 HTTP Accept="text/html,*/*"，以指明支持重定向。

    为什么 POST 请求不会触发重定向？

    浏览器不会重定向以响应 POST 请求。而是返回 401 Unauthorized 状态代码。

    对于向受 IAP 保护的资源发出的 POST 请求，请添加以下任一项：

    • Authorization: Bearer 标头中的 ID 令牌

    • 有效 Cookie（请参阅刷新会话）

    如果我已停用 API，是否可以使用 IAP？

    是的，停用 API 后，受 IAP 保护的资源仍可访问，但您将无法修改 IAM 权限。

    如何阻止具有 Owner 角色的用户使用 IAP for TCP？

    理想情况下，应限制使用 Owner (roles/owner) 角色，而改用更精细的权限。如需相关指导，请参阅 IAM 最佳实践。

    如果无法做到这一点，您可以使用防火墙规则屏蔽 IAP for TCP。

    IAP 使用哪个网域实现 TCP？

    IAP 使用以下 Google 拥有的网域：

    为什么我会收到Server Error？

    如果您看到：

    The server encountered a temporary error and could not complete your request. Please try again in 30 seconds.

    您的防火墙可能屏蔽了负载均衡器 IP。

    确保防火墙允许来自 130.211.0.0/22 和 35.191.0.0/16 的流量。如果这些 IP 地址无法访问您的后端，则您的应用将无法访问。

    对于与特定虚拟机的 IAP TCP 连接，还需确保虚拟机接受来自 35.235.240.0/20 范围的连接。

    为什么我会间歇性地收到内部服务器错误？

    An internal server error occurred while authorizing your request. Error code X 等消息表示后端故障。

    错误代码 1、30、62、63、64 或 703 通常反映的是暂时性问题。为重试实现指数退避算法。

    如何更正 Identity Platform 错误（错误代码 38）

    错误代码 38 表示外部身份的 Identity Platform 身份验证网址未在 IAP 中正确配置。

    如需查找网址，请执行以下操作：

    1. 前往 IAP 页面。

      转到 IAP

    2. 点击应用标签页。

    3. 在资源列中，找到您的应用并选中其复选框。

    4. 在身份验证网址或登录网址中，确保网址正确无误。

    如需了解如何将外部身份与 IAP 搭配使用，请参阅使用外部身份对用户进行身份验证。

    如何解决“超出配额”错误（错误代码 429）？

    当应用超出 IAP 的请求限制时，会发生错误代码 429。该服务会强制执行单独的配额：

    • 基于浏览器的请求：每个项目每分钟 360,000 个

    • 程序化请求：每个项目每分钟 360,000 个

    程序化请求是指包含 AUTHORIZATION 或 PROXY-AUTHORIZATION 标头且不包含 IAP Cookie 的请求。所有其他请求（包括没有凭据的请求）都被视为浏览器请求。

    这些限制共同适用于项目中所有受 IAP 保护的资源。

    如果您遇到与配额相关的错误，请考虑以下解决方案：

    • 避免在生产环境中进行负载测试。请改用绕过 IAP 的备用网络路径。

    • 对于服务到服务的流量，请实现指数退避算法，以妥善处理 429 错误。

    • 将高流量应用分布在多个项目中。

    • 对基于 API 的应用使用 Apigee 或类似的 API 网关解决方案。

    • 如果自然增长导致了此问题，请与Google Cloud 支持团队联系以增加配额。

    使用 Identity Platform 的 IAP 出现登录问题或异常行为

    将第三方身份提供方 (IdP) 与 Identity Platform 搭配使用时，ID 令牌中的大型声明数据可能会导致 IAP 会话 Cookie 超出浏览器大小限制（通常约为 4 KB）。IAP 会将这些会话信息（包括这些声明）存储在浏览器 Cookie 中。

    超出会话 Cookie 大小限制可能会导致登录失败或无限登录循环。为避免这些问题，请考虑采取以下措施：

    • 减少声明：将第三方 IdP 配置为仅向 Identity Platform 发送基本声明。尽量减少令牌中包含的声明的大小和数量。

    • 检查 Cookie 大小：使用浏览器开发者工具检查在应用网域中设置的 Cookie 的大小。查找与 Cookie 大小相关的警告，尤其是与 IAP 相关的 Cookie。

    • 测试最少声明：暂时将 IdP 配置为发送尽可能少的声明。如果这样可以解决问题，则可以确认 Cookie 大小限制是根本原因。

    为什么我会收到 HTTP 502 错误，并显示“Google 账号 OAuth 客户端 ID/密钥为空”？

    如果您访问受 IAP 保护的应用并收到 HTTP 502 Bad Gateway 错误（消息为 Empty Google Account OAuth client ID(s)/secret(s).），则表示 IAP 找不到应用的 OAuth 凭据。

    此错误通常发生在以下场景中：

    错误代码

    下表列出了在配置和使用 IAP 时返回的常见错误代码和消息。

    错误代码 说明 问题排查
    7、HTTP 502 OAuth 客户端 ID 或密钥为空 (Empty Google Account OAuth client ID(s)/secret(s).) 如果您的项目不属于任何组织，请配置自定义 OAuth 凭证。否则，请访问“凭证”页面验证您的客户端 ID 和密钥，或使用 API 方法（Compute Engine 使用 GET，App Engine 使用 GET）检查设置，并使用 PATCH 重置。如需了解详情，请参阅 HTTP 502 错误。
    9 OAuth 重定向失败 这是一个已自动记录的内部错误。您无需采取任何行动。
    9（使用路径重写规则） OAuth 重定向失败 负载均衡器的路径重写规则阻止了 OAuth 完成。确保负载均衡器后面的所有后端都使用相同的 OAuth 客户端 ID。您可以使用 gcloud compute backend-services update 命令更新此设置。
    9（具有路径路由规则） OAuth 重定向失败 为每个路径的两个版本（末尾有斜线和没有斜线）创建路径规则变体，并将其定向到同一后端。例如，同时包含 /path/ 和 /path 的规则。
    11 OAuth 客户端 ID 配置不正确 在“凭证”页面中检查您的客户端 ID 和密钥。如果这些设置看起来正确但无法正常运行，请使用 API 方法检查设置（Compute Engine 使用 GET，App Engine 使用 GET），并使用 PATCH 重置这些设置。
    13 OIDC 令牌无效 前往“凭据”页面，确认您的客户端 ID 未被删除或错误修改。
    51 浏览器缺少连接池支持 请让最终用户将浏览器更新到最新版本。如需详细了解连接要求，请参阅限制资源访问权限。
    52 主机名/SSL 证书不匹配 您的系统管理员需要更新 SSL 证书，使其与主机名一致。如需相关指导，请参阅限制资源访问权限。
    52（具有主证书映射条目） 主机名/SSL 证书不匹配 IAP 不支持主要证书映射条目。请使用单独的条目将每个证书映射到正确的主机名。如需相关指导，请参阅创建证书映射条目。
    53 主机名不在允许的网域中 管理员必须将您的主机名添加到允许的网域列表中。如需了解相关说明，请参阅限制资源访问权限。
    253、HTTP 429 已超出请求配额 您已达到请求上限（每种请求类型 360,000 次/分钟）。考虑将工作负载分布到多个项目中、实施客户端请求限制，或在需要合法增长时联系支持团队以增加配额。
    551 在多个位置启用了 IAP 您无法同时在转发规则和后端服务上启用 IAP。按照为 Compute Engine 启用中的指导，在一个位置停用该功能。
    700、701 员工池提供方问题 为员工池配置一个提供方。如需了解详细要求，请参阅员工池限制。
    705 缺少员工身份的 OAuth 客户端 ID 请按照完整的设置流程操作：首先创建 OAuth 客户端 ID，然后更新 IAP 设置。
    708 员工池名称无效 验证您的员工池是否存在，并且使用了正确的格式：locations/global/workforcePools/WORKFORCE_POOL_ID。
    4003 连接或防火墙问题 检查虚拟机进程是否正在运行并监听预期端口。此外，还要验证您的防火墙规则是否允许通过该端口进行连接。
    4010 连接已被目标关闭 重置虚拟机。如果问题仍然存在，请检查 auth.log（通常位于 /var/log/ 中）或使用串行控制台进行更详细的诊断。
    4033 权限、存在性或虚拟机状态问题 通过 IAP 页面确认您已获分配该资源的 Tunnel User 角色，并验证虚拟机是否存在且正在运行。
    4047 实例不存在或已停止 确保虚拟机已开机并已完全完成启动序列。

    如果您无法解决问题，或者在此页面上没有看到您遇到的错误，请与 Cloud Customer Care 联系，并提供错误说明以及您从对 API 的 GET 调用中获得的响应。请务必从响应中移除客户端密钥。