疑難排解與常見問題

本文提供 Identity-Aware Proxy (IAP) 的疑難排解指南和常見問題解答。

排解網頁登入問題

如果在登入或存取應用程式時發生錯誤，檢查瀏覽器的網路流量有助於診斷問題。

檢查網路流量

  1. 在瀏覽器中開啟新的無痕 (Chrome) 或私密視窗。
  2. 開啟瀏覽器的開發人員工具，然後前往「Network」分頁。
  3. 選取「Preserve log」選項，擷取重新導向期間的所有要求。
  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 要求時，請加入下列任一項目：

    如果停用 API，還能使用 IAP 嗎？

    可以。停用 API 後，受 IAP 保護的資源仍可存取，但您無法修改 IAM 權限。

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

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

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

    IAP for TCP 使用什麼網域？

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

    • tunnel.cloudproxy.app

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

    為什麼我會收到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 無法連線至後端，您就無法存取應用程式。

    如要與特定 VM 建立 IAP TCP 連線，也請確認 VM 接受來自 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 表示在 IAP 中，外部身分的 Identity Platform 驗證網址設定不正確。

    如要找出網址，請按照下列步驟操作：

    1. 前往 IAP 頁面。

      前往「IAP」頁面

    2. 按一下「應用程式」分頁標籤。

    3. 在「Resource」(資源) 欄中找出應用程式，然後勾選對應的核取方塊。

    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 發生登入問題或異常行為

    搭配使用 Identity Platform 和第三方識別資訊提供者 (IdP) 時，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 憑證。

    這項錯誤通常會在下列情況發生：

    • 專案不屬於任何組織：預設的 Google 代管 OAuth 用戶端僅適用於屬於Google Cloud 組織的專案。如果專案不屬於任何組織，您必須為 App Engine 或相應平台設定自訂 OAuth 憑證。
    • OAuth 憑證已刪除或未設定：如果您先前設定了自訂 OAuth 憑證，但 OAuth 用戶端已刪除，請在「Credentials」(憑證) 頁面重新建立憑證，並按照「搭配使用自訂 OAuth 用戶端與 IAP」一文所述更新 IAP 設定。

    錯誤代碼

    下表列出設定及使用 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 連線或防火牆問題 確認 VM 程序正在執行，並監聽預期的通訊埠。此外，請確認防火牆規則允許該通訊埠的連線。
    4010 連線已由目的地關閉 重設 VM。如果問題持續發生，請檢查 auth.log (通常位於 /var/log/)，或使用序列控制台進行更詳細的診斷。
    4033 權限、存在或 VM 狀態問題 請透過 IAP 頁面確認您已獲派資源的通道使用者角色，並確認 VM 存在且正在運作。
    4047 執行個體不存在或已停止 確認 VM 已開啟電源，並已完成啟動程序。

    如果無法解決問題，或是在本頁找不到錯誤，請與 Cloud Customer Care 聯絡，並說明錯誤和您從 GET 呼叫 API 取得的回應。請務必從回應中移除用戶端密鑰。