使用外部身分管理工作階段

本文說明如何在使用外部身分進行驗證時，透過 Identity-Aware Proxy (IAP) 管理工作階段。

正在重新整理工作階段

Identity Platform 工作階段的有效時限為一小時。工作階段過期時，應用程式必須重新導向至驗證頁面。驗證頁面包含 Identity Platform 重新整理權杖。只要使用者憑證仍有效，您就能用來重新驗證，不必顯示任何 UI。

如果使用者最近變更了電子郵件或密碼，或是發生其他導致權杖遭撤銷的動作，就必須再次完成驗證流程。

處理非 AJAX 要求

如果驗證頁面設定正確，系統會使用應用程式重新導向功能，自動處理非 AJAX 要求。

處理 AJAX 要求

Chrome 和其他瀏覽器正在逐步淘汰第三方 Cookie。如果停用第三方 Cookie，這個頁面中關於發出 AJAX 要求建議將無法運作。不過，如果 AJAX 要求的來源和目標都來自相同網站，系統仍會提供建議。

如需在 Chrome 中管理第三方 Cookie 的操作說明，請參閱「在 Chrome 中刪除、允許使用與管理 Cookie」。

如果傳送的 AJAX 要求包含過期的權杖，要求會傳回 401: Unauthorized 狀態碼。請實作下列其中一種解決方案來處理這個問題：

• 修改應用程式程式碼，處理 HTTP 401 狀態碼。
• 在應用程式中新增 iframe，指向工作階段重新整理器。
• 指示使用者在單獨分頁中手動載入工作階段重新整理器。

如果 AJAX 要求的回應是 302 狀態碼而非 401，請新增 X-Requested-With 標頭，並將值設為 XMLHttpRequest。這會告知 IAP 要求來自 JavaScript。

以程式輔助方式處理 HTTP 401

建議以程式輔助方式處理 HTTP 401 狀態碼，藉此重新整理 AJAX 工作階段。現在說明一下操作方式：

1. 更新應用程式程式碼，處理錯誤。

   if (response.status === 401) {
     statusElm.innerHTML = 'Login stale. <input type="button" value="Refresh" onclick="sessionRefreshClicked();"/>';
   }

2. 新增處理常式，開啟視窗重新驗證使用者，然後在程序完成時關閉視窗。

   var iapSessionRefreshWindow = null;
   
   function sessionRefreshClicked() {
     if (iapSessionRefreshWindow == null) {
       iapSessionRefreshWindow = window.open("/?gcp-iap-mode=DO_SESSION_REFRESH");
       window.setTimeout(checkSessionRefresh, 500);
     }
     return false;
   }
   
   function checkSessionRefresh() {
     if (iapSessionRefreshWindow != null && !iapSessionRefreshWindow.closed) {
       // Attempting to start a new session.
       // XMLHttpRequests is used by the server to identify AJAX requests
       fetch('/favicon.ico', {
             method: "GET",
             credentials: 'include',
             headers: {
                 'X-Requested-With': 'XMLHttpRequest'
             }
       .then((response) => {
         // Checking if browser has a session for the requested app
         if (response.status === 401) {
           // No new session detected. Try to get a session again
           window.setTimeout(checkSessionRefresh, 500);
         } else {
           // Session retrieved.
           iapSessionRefreshWindow.close();
           iapSessionRefreshWindow = null;
         }
       })
       });
     } else {
       iapSessionRefreshWindow = null;
     }
   }

使用 iframe

如果您無法以程式化方式處理 HTTP 401，則下一個最佳解決方案是在應用程式中新增 iframe，以指向工作階段重新整理器。

使用 iframe 時，您必須在與 IAP 保護的網頁應用程式相同的網域中，設定自訂登入頁面。否則，使用者會遇到跨來源錯誤。如要進一步瞭解如何設定登入頁面，請參閱建立自訂登入頁面。

iframe 的使用範例：

<iframe src="https://example.com/some/path?gcp-iap-mode=SESSION_REFRESHER" style="width:0;height:0;border:0; border:none;"></iframe>

載入工作階段重新整理器

萬不得已時，您可以指示使用者手動載入工作階段重新整理器。在應用程式或說明文件中加入指引，引導使用者在另一個分頁中開啟下列網址：

https://example.com/some/path?gcp-iap-mode=SESSION_REFRESHER

將使用者登出

如要讓使用者登出 IAP 資源，請使用查詢參數 ?gcp-iap-mode=GCIP_SIGNOUT。舉例來說，在 App Engine 應用程式中，網址如下所示：

https://example.com/some/path?gcp-iap-mode=GCIP_SIGNOUT

使用者登出後，系統會將他們重新導向至登入頁面。

如要將使用者登出所有資源和工作階段，請將他們重新導向至驗證網址，並附加 API 金鑰和 mode=signout 做為參數。例如：

https://auth.example.com/?apiKey=API-KEY&mode=signout

登出完成後，使用者會停留在該頁面。建議在 AuthenticationHandler 物件上實作 completeSignOut() 回呼，向使用者提供已成功登出的回饋。

切換租戶

在某些情況下，使用者可能會想針對同一個 IAP 資源，向多個租戶進行驗證。舉例來說，使用者可能屬於多個授予不同存取層級的租戶，並想改用權限較少或較多的租戶。

如要強制重新啟動租戶選取程序，請使用 ?gcp-iap-mode=CLEAR_LOGIN_COOKIE。舉例來說，在 App Engine 應用程式中，網址可能如下所示：

https://PROJECT-ID.appspot.com/some/path?gcp-iap-mode=CLEAR_LOGIN_COOKIE

後續步驟

• 使用 FirebaseUI 建立驗證 UI
• 建立自訂驗證 UI