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

本文將說明如何使用身分識別 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

後續步驟