问题排查和常见问题解答

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

排查 Web 登录问题

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

检查网络流量

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 请求的响应。相反，IAP 会返回 401 Unauthorized 状态代码。

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

• Authorization: Bearer 标头中的 ID 令牌
• 有效的 Cookie（请参阅刷新 会话）

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

是，在停用 API 的情况下，可以访问使用 IAP 保护的资源，但您将无法修改 IAM 权限。

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

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

如果无法实现这一点，您可以使用 防火墙规则阻止使用 IAP 实现 TCP。

IAP 使用哪个网域实现 TCP？

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

• tunnel.cloudproxy.app
• mtls.tunnel.cloudproxy.app（启用基于证书的访问权限 时）

注意： 确保您的代理服务器和防火墙允许流量流向这些网域 并且不会阻止 WebSocket 连接。

为什么我会收到 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 大小限制是根本原因。

错误代码

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

错误代码	说明	问题排查
7	OAuth 客户端 ID 或密钥为空	访问凭据页面，验证您的客户端 ID 和密钥。如果它们看起来正确但不起作用，请使用 API 方法检查设置（GET for Compute Engine, GET for App Engine），然后使用 PATCH 重置它们。
9	OAuth 重定向失败	这是一个内部错误，系统已自动记录。您无需采取任何措施。
9（使用路径重写规则）	OAuth 重定向失败	负载均衡器的路径重写规则阻止了 OAuth 完成。确保负载均衡器后面的所有后端都使用相同的 OAuth 客户端 ID。您可以使用 gcloud compute backend-services update 命令更新此 ID。
9（使用路径路由规则）	OAuth 重定向失败	为每个路径的两个版本（带和不带尾部斜杠）创建路径规则变体，并将它们定向到同一后端。例如，同时包含 /path/ 和 /path 的规则。
11	OAuth 客户端 ID 配置不正确	在凭据页面中检查您的客户端 ID 和密钥。如果它们看起来正确但不起作用，请使用 API 方法检查设置（GET for Compute Engine, GET for App Engine），然后使用 PATCH 重置它们。
13	OIDC 令牌无效	前往凭据页面，确认您的客户端 ID 未被删除或修改不正确。
51	浏览器缺少连接池支持	要求最终用户将其浏览器更新到当前版本。如需详细了解连接要求，请参阅限制资源访问。
52	主机名/SSL 证书不匹配	您的系统管理员需要更新 SSL 证书以与主机名匹配。如需指导，请参阅限制资源访问。
52（使用主要证书映射条目）	主机名/SSL 证书不匹配	IAP 不支持主要证书映射条目。请使用单独的条目将每个证书映射到正确的主机名。如需指导，请参阅创建证书映射条目。
53	主机名不在允许的网域中	管理员必须将您的主机名添加到允许的网域列表中。如需相关说明，请参阅限制资源访问。
253、HTTP 429	超出请求配额	您已达到请求限制（每种请求类型每分钟 360,000 个）。请考虑将工作负载分布到多个项目中，实现客户端请求限制，或者在合法增长需要时与 支持团队 联系以增加配额。
551	在多个位置启用了 IAP	您无法同时在转发规则和后端服务中启用 IAP。请按照为 Compute Engine 启用中的指导，在一个位置停用 IAP。
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 联系，并提供错误说明以及通过 GET 调用 API 得到的响应。请务必从响应中移除客户端密钥。