疑難排解與常見問題

本文提供 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 權限。

如何防止擁有者角色的使用者透過 TCP 使用 IAP？

建議您盡量不要使用「擁有者」角色 (roles/owner)，改用更精細的權限。如需相關指引，請參閱 IAM 最佳做法。

如果無法這麼做，可以使用防火牆規則封鎖 TCP 的 IAP。

IAP for TCP 使用哪個網域？

IAP 使用下列 Google 擁有的網域：

• tunnel.cloudproxy.app
• mtls.tunnel.cloudproxy.app (啟用憑證型存取權時)

注意： 請確保 Proxy 伺服器和防火牆允許連線至這些網域，且未封鎖 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 連線至特定 VM，請一併確認 VM 接受來自 35.235.240.0/20 範圍的連線。

為什麼我會間歇性收到內部伺服器錯誤訊息？

An internal server error occurred while authorizing your request. Error code X 等訊息表示後端發生錯誤。

錯誤代碼 1、30、62、63、64 或 703 通常反映暫時性問題。針對重試作業實作指數輪詢。

如何解決超出配額的錯誤 (錯誤代碼 429)？

如果應用程式超出 IAP 的要求限制，就會發生錯誤代碼 429。這項服務會強制執行個別配額：

• 透過瀏覽器提出的要求：每項專案每分鐘 360,000 項
• 程式輔助要求：每項專案每分鐘 360,000 項

程式輔助要求是指包含 AUTHORIZATION 或 PROXY-AUTHORIZATION 標頭，但不含 IAP Cookie 的要求。所有其他要求 (包括沒有憑證的要求) 都視為瀏覽器要求。

這些限制適用於專案中所有受 IAP 保護的資源。

如果遇到配額相關錯誤，請嘗試下列解決方案：

• 請勿在正式環境中進行負載測試。請改用可繞過 IAP 的替代網路路徑。
• 如果是服務對服務流量，請實作指數輪詢，妥善處理 429 錯誤。
• 將高流量應用程式分散在多個專案中。
• 對於以 API 為基礎的應用程式，請使用 Apigee 或類似的 API 閘道解決方案。
• 如果自然成長導致問題，請與Google Cloud 支援團隊聯絡，要求提高配額。

錯誤代碼

下表列出設定及使用 IAP 時，常見的錯誤代碼和訊息。

錯誤代碼	說明	疑難排解
7	OAuth 用戶端 ID 或密鑰為空白	前往「憑證」頁面，驗證用戶端 ID 和密鑰。如果顯示的設定正確，但無法運作，請使用 API 方法檢查設定 (Compute Engine 為 GET，App Engine 為 GET)，然後使用 PATCH 重設設定。
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	連線或防火牆問題	確認 VM 程序正在執行，並在預期通訊埠上監聽。此外，請確認防火牆規則允許該通訊埠的連線。
4010	連線已由目的地關閉	重設 VM。如果問題持續發生，請檢查 auth.log (通常位於 /var/log/)，或使用序列控制台進行更詳細的診斷。
4033	權限、存在與否或 VM 狀態問題	透過 IAP 頁面確認您已為資源指派通道使用者角色，並驗證 VM 是否存在且正在執行。
4047	執行個體不存在或已停止	確認 VM 已開機，且啟動程序已完全完成。

如果無法解決問題，或本頁面未列出您遇到的錯誤，請與 Cloud Customer Care 聯絡，並提供錯誤說明，以及對 API 進行 GET 呼叫時收到的回應。請務必從回應中移除用戶端密鑰。