使用 FedCM API 進行 Google 登入

本指南討論 Google 登入平台程式庫採用 FedCM API 的方式。相關主題包括時間軸和後續步驟，確保程式庫回溯相容；如何執行影響評估及驗證使用者登入作業能繼續正常運作，並視需要更新網頁應用程式。此外，也會介紹管理轉換期的選項，以及取得說明的方式。

程式庫狀態

任何新網頁應用程式都無法使用已淘汰的 Google 登入平台程式庫，但使用該程式庫的應用程式可以繼續使用，直到另行通知為止。尚未設定圖書館的最終停用日期 (關閉)。詳情請參閱停止支援和停用。

回溯相容性更新會將 FedCM API 新增至 Google 登入程式庫。雖然大部分的變更都會無縫接軌，但這次更新會對使用者提示、iframe permissions-policy 和內容安全政策 (CSP) 造成影響。這些變更可能會影響您的網頁應用程式，且需要變更應用程式的程式碼和網站設定。

在轉換期間，設定選項會控制是否在使用者登入時使用 FedCM API。

過渡期結束後，所有使用 Google 登入程式庫的網路應用程式都必須使用 FedCM API。

時間軸

上次更新時間：2024 年 9 月

以下是影響使用者登入行為的日期和變更：

  • 2023 年 3 月 淘汰 Google 登入平台資料庫的支援。
  • 2024 年 7 月過渡期開始，Google 登入平台程式庫新增 FedCM API 支援功能。根據預設，Google 會控制在這個期間使用 FedCM 的使用者登入要求百分比。網頁應用程式可能會使用 use_fedcm 參數明確覆寫這個行為。
  • 必須透過 Google 登入平台程式庫強制採用 FedCM API (2025 年 3 月)，之後系統就會忽略 use_fedcm 參數，並要求所有使用者登入要求使用 FedCM。

後續步驟

您可以選擇以下三種做法：

  1. 執行影響評估，並視需要更新網頁應用程式。這種做法會評估是否使用需要變更網頁應用程式的功能。本指南的下一節會提供操作說明。
  2. 移至 Google Identity 服務 (GIS) 程式庫。強烈建議您改用最新且支援的登入程式庫。請按照這些操作說明執行。
  3. 不採取任何行動。當 Google 登入程式庫遷移至 FedCM API 以便使用者登入時，您的網頁應用程式會自動更新。這是最省事的做法，但使用者可能無法登入您的網路應用程式。

進行影響評估

請按照下列操作說明，判斷您的網頁應用程式是否可透過回溯相容性更新無縫更新，或是需要進行變更，以免在 Google 登入平台程式庫完全採用 FedCM API 時，使用者無法登入。

設定

如要在使用者登入期間使用 FedCM，必須使用瀏覽器 API 和最新版的 Google 登入平台程式庫。

繼續之前，請注意以下事項：

  • 請更新至最新版的 Chrome。Chrome for Android 需要 M128 以上版本，因此無法使用舊版測試。

  • 開啟 chrome://flags 並將下列特徵設為這些值：

    • #fedcm-authz 已啟用
    • 已啟用 #tracking-protection-3pcd
    • #third-party-cookie-deprecation-trial 已停用
    • #tpcd-metadata-grants 已停用
    • #tpcd-heuristics-grants 已停用

    並重新啟動 Chrome。

  • 在網頁應用程式中初始化 Google 登入平台程式庫時，請將 use_fedcm 設為 true。一般來說，初始化作業如下所示：

    • gapi.client.init({use_fedcm: true})，或
    • gapi.auth2.init({use_fedcm: true})，或
    • gapi.auth2.authorize({use_fedcm: true})。

  • 撤銷 Google 登入平台資料庫的快取版本。 一般而言，不需要執行這個步驟，因為只要在 <script src> 標記中加入 api.js、client.js 或 platform.js，即可直接將最新版本的程式庫下載至瀏覽器 (要求可能會使用程式庫的任何這類套件名稱)。

  • 確認 OAuth 用戶端 ID 的 OAuth 設定：

    1. 開啟 Google API Console的「憑證」頁面

    2. 確認網站的 URI 已納入「已授權的 JavaScript 來源」。URI 僅包含配置和完整主機名稱。例如 https://www.example.com。

    3. 您可以選擇透過重新導向至您代管的端點，而不是透過 JavaScript 回呼，來傳回憑證。如果是這種情況，請確認重新導向 URI 是否已納入「已授權的重新導向 URI」。重新導向 URI 包含配置、完整主機名稱和路徑，且必須符合重新導向 URI 驗證規則。例如：https://www.example.com/auth-receiver

測試

按照「設定」中的操作說明操作後：

找出 Google 登入程式庫要求

檢查 Google 登入平台程式庫的要求，確認是否需要變更 permissions-policy 和 Content Security Policy。如要這麼做，請使用程式庫的名稱和來源找出要求：

  • 在 Chrome 中，開啟開發人員工具的「Network」面板，然後重新載入網頁。
  • 使用「Domain」和「Name」欄中的值，找出資料庫要求：
    • 網域為 apis.google.com，且
    • 名稱為 api.js、client.js 或 platform.js。Name 的具體值取決於文件要求的程式庫套件。

例如，將「網域」欄中的 apis.google.com 和「名稱」欄中的 platform.js 設為篩選條件。

檢查 iframe 權限政策

您的網站可能會在跨來源 iframe 中使用 Google 登入平台程式庫。如果是的話，請務必更新。

按照「找出 Google 登入程式庫要求」操作說明後，在開發人員工具的「Network」面板中選取 Google 登入程式庫要求，然後在「Headers」分頁的「Request Headers」部分找出 Sec-Fetch-Site 標頭。如果標頭的值為：

  • same-site 或 same-origin，則跨來源政策不適用，因此不需要進行任何變更。
  • 如果使用 iframe，可能需要變更 cross-origin。

如要確認是否有 iframe，請按照下列步驟操作：

  • 在 Chrome 開發人員工具中選取「元素」面板，然後
  • 使用 Ctrl + F 鍵找出文件中的 iframe。

如果找到 iframe，請檢查文件，檢查是否有 gapi.auth2 函式或 script src 指令在 iframe 中載入 Google 登入程式庫的呼叫。出現這種情況時：

對文件中的每個 iframe 重複執行這個程序。iframe 可嵌套，因此請務必在所有周圍的父項 iframe 中加入 allow 指示詞。

檢查內容安全政策

如果您的網站使用內容安全政策，您可能需要更新 CSP，以便使用 Google 登入程式庫。

按照「找出 Google 登入程式庫要求」的操作說明操作後，請在「開發人員工具」面板中選取 Google 登入程式庫要求，然後在「標頭」分頁的「回應標頭」部分找出 Content-Security-Policy 標頭。

如果找不到標頭，則不需要進行任何變更。否則，請檢查 CSP 標頭中是否定義了任何 CSP 指令，並按照下列步驟更新：

  • 將 https://apis.google.com/js/、https://accounts.google.com/gsi/ 和 https://acounts.google.com/o/fedcm/ 新增至任何 connect-src、default-src 或 frame-src 指令。

  • 將 https://apis.google.com/js/bundle-name.js 新增至 script-src 指令。根據文件要求的程式庫套件，將 bundle-name.js 替換為 api.js、client.js 或 platform.js。

檢查使用者提示變更

使用者提示行為有些許差異，FedCM 會新增瀏覽器顯示的模式對話方塊，並更新使用者啟用需求。

FedCM 互動式對話方塊圖片

檢查網站版面配置，確認底層內容可安全重疊，並暫時遮蓋瀏覽器的模式對話方塊。如果不是這樣，您可能需要調整網站某些元素的版面配置或位置。

使用者啟用

FedCM 包含更新的使用者啟用規定。按下按鈕或點按連結，就是允許第三方來源發出網路要求或儲存資料的使用者手勢。使用 FedCM 時，瀏覽器會在下列情況下提示使用者同意：

  • 使用者先透過新的瀏覽器執行個體登入網頁應用程式，或
  • 系統會呼叫 GoogleAuth.signIn。

目前，如果使用者曾登入您的網站，您可以在使用 gapi.auth2.init 初始化 Google 登入程式庫時取得使用者的登入資訊，而無須再進行使用者互動。除非使用者先前至少曾經歷 FedCM 登入流程一次，否則無法再執行這項操作。

只要選擇加入 FedCM 並呼叫 GoogleAuth.signIn，下次同一位使用者造訪您的網站時，gapi.auth2.init 就能在初始化期間取得使用者的登入資訊，無須使用者互動。

常見用途

Google 登入程式庫的開發人員說明文件包含常見用途的指南和程式碼範例。本節將說明 FedCM 對這些行為的影響。

  • 將 Google 登入整合至網頁應用程式

    在這個示範中，<div> 元素和類別會轉譯按鈕，而對於已登入的使用者，網頁 onload 事件會傳回使用者憑證。必須與使用者互動才能登入及建立新工作階段。

    程式庫初始化作業是由 g-signin2 類別完成，該類別會呼叫 gapi.load 和 gapi.auth2.init。

    使用者手勢 (<div> 元素 onclick 事件) 會在登入期間呼叫 auth2.signIn，或在登出時呼叫 auth2.signOut。

  • 建立自訂 Google 登入按鈕

    在第一個示範中，我們使用自訂屬性控制登入按鈕的外觀，而對於已登入的使用者，頁面 onload 事件會傳回使用者憑證。您必須與使用者互動，才能登入並建立新的工作階段。

    程式庫初始化作業會透過 platform.js 程式庫的 onload 事件完成，而按鈕則會由 gapi.signin2.render 顯示。

    使用者手勢 (按下登入按鈕) 會呼叫 auth2.signIn。

    在第二個示範中，我們使用 <div> 元素、CSS 樣式和自訂圖形來控制登入按鈕的外觀。您必須與使用者互動，才能登入並建立新的工作階段。

    在載入文件時，程式庫會使用呼叫 gapi.load、gapi.auth2.init 和 gapi.auth2.attachClickHandler 的 start 函式完成初始化。

    使用者手勢 (<div> 元素 onclick 事件)：在登入時使用 auth2.attachClickHandler 呼叫 auth2.signIn，或在登出時使用 auth2.signOut。

  • 監控使用者的工作階段狀態

    在這個示範中，按下按鈕可用於使用者登入和登出。需要使用者互動，才能登入及建立新的工作階段。

    使用 script src 載入 platform.js 後，直接呼叫 gapi.load、gapi.auth2.init 和 gapi.auth2.attachClickHandler() 即可完成程式庫初始化作業。

    使用者手勢 (<div> 元素 onclick 事件)：在登入時使用 auth2.attachClickHandler 呼叫 auth2.signIn，或在登出時使用 auth2.signOut。

  • 要求其他權限

    在這個示範中，按下按鈕可用於要求其他 OAuth 2.0 範圍，取得新的存取權憑證，如果是已登入的使用者，頁面 onload 事件會傳回使用者憑證。您必須與使用者互動，才能登入並建立新的工作階段。

    platform.js 程式庫的初始化作業是由 onload 事件透過呼叫 gapi.signin2.render 完成。

    使用者手勢 (點選 <button> 元素) 會在登出時，使用 googleUser.grant 或 auth2.signOut 觸發要求其他 OAuth 2.0 範圍。

  • 使用事件監聽器整合 Google 登入

    在這個示範中，對於已登入的使用者，onload 頁面事件會傳回使用者憑證。需要使用者互動，才能登入及建立新工作階段。

    在載入文件時，程式庫會使用呼叫 gapi.load、gapi.auth2.init 和 gapi.auth2.attachClickHandler 的 start 函式完成初始化。接著，我們會使用 auth2.isSignedIn.listen 和 auth2.currentUser.listen 設定會話狀態變更的通知。最後，系統會呼叫 auth2.SignIn，以便傳回已登入使用者的憑證。

    使用者手勢 (<div> 元素 onclick 事件) 會在登入時使用 auth2.attachClickHandler 呼叫 auth2.signIn，或在登出時呼叫 auth2.signOut。

  • 伺服器端應用程式適用的 Google 登入功能

    在這個示範中，使用者手勢會用來要求 OAuth 2.0 驗證碼，而 JS 回呼會發出 AJAX 呼叫，將回應傳送至後端伺服器進行驗證。

    程式庫初始化作業會使用 platform.js 程式庫的 onload 事件，該事件會使用啟動函式呼叫 gapi.load 和 gapi.auth2.init。

    使用者手勢，按一下 <button> 元素，會呼叫 auth2.grantOfflineAccess 觸發取得授權碼的要求。

  • 跨平台單一登入 (SSO)

    FedCM 需要每個瀏覽器執行個體的同意聲明，即使 Android 使用者已登入，也必須提供一次性同意聲明。

管理轉換期

在轉換期間，部分使用者登入作業可能會使用 FedCM，具體百分比可能會有所不同，且可能隨時間變動。根據預設，Google 會控制使用 FedCM 的登入要求數量，但您可以選擇在轉換期間啟用或停用 FedCM。過渡期結束後，FedCM 就會成為強制要求，並用於所有登入要求。

選擇採用後，系統會引導使用者完成 FedCM 登入流程，選擇不採用後，系統會引導使用者完成現有的登入流程。您可以使用 use_fedcm 參數來控制此行為。

啟用

控管是否使用 FedCM API 對網站所有或部分登入嘗試可能有幫助。方法是在初始化平台程式庫時，將 use_fedcm 設為 true。在這種情況下，使用者登入要求會使用 FedCM API。

選擇停用

在轉換期間，根據預設，使用者嘗試登入網站的次數中，會有部分會使用 FedCM API。如果您需要更多時間變更應用程式，可以暫時選擇不使用 FedCM API。如要執行這項操作，請在初始化平台程式庫時將 use_fedcm 設為 false。在這種情況下，使用者登入要求不會使用 FedCM API。

強制採用後，Google 登入平台程式庫會忽略任何 use_fedcm 設定。

取得說明

使用 google-signin 標記在 StackOverflow 上搜尋或提出問題。