從 Google 登入遷移

本指南將協助您瞭解必要的變更和步驟 成功從先前的 Google 登入 遷移至新版 Google Identity 服務程式庫， authentication。

如果您的用戶端使用 JavaScript 或其他 Google API 用戶端程式庫 如需授權的舊版程式庫，請參閱遷移至 Google Identity 服務。

驗證及授權

「驗證」是指確認使用者身分，通常稱為 使用者註冊或登入授權是授予或 拒絕存取資料或資源的情形。舉例來說，您的應用程式會要求您的 使用者同意存取使用者的 Google 雲端硬碟。

如同舊版的 Google 登入平台程式庫，新版 Google Identity 服務程式庫旨在支援驗證和授權 作業。

不過，新版程式庫將兩個程序分開，以降低複雜度 ，方便開發人員整合 Google 帳戶與您的應用程式。

如果您的用途僅涉及驗證，請繼續閱讀本頁。

如果您的用途包含授權，請參閱使用者授權的運作方式一文 並遷移至 Google Identity 服務，確保應用程式 以便快速處理問題

異動情形

新版 Google Identity 服務程式庫為使用者提供許多功能 使用便利性提升。主要包含：

  • 全新流暢的 One Tap 與自動登入流程，減少使用者人數 步數
  • 新版登入按鈕提供使用者的個人化功能
  • 在網路上持續宣傳一致的品牌宣傳元素和統一登入行為，可提升 更加瞭解與信任
  • 快速找到內容；使用者可從任何位置直接註冊和登入 都不需要先前往登入或帳戶頁面

對開發人員來說，我們的重點是降低複雜性、改善安全性並 加快整合程序。其中一些改進項目包括：

  • 選擇在網站的靜態內容中新增使用者 HTML、
  • 將登入驗證與授權的機制區隔開來 使用者資料，因此不再需要進行複雜的 OAuth 2.0 整合 使用者登入網站
  • Google 的 OAuth 會持續支援彈出式視窗和重新導向模式 2.0 基礎架構現在會重新導向至後端伺服器的登入端點
  • 整合舊版 Google Identity 的功能 和 Google API JavaScript 程式庫整合到一個新的程式庫
  • 如此一來，您就可以決定是否要使用 Promise 與 getter 樣式函式的間接性 為方便起見

登入遷移範例

如果要從現有的 Google 登入按鈕進行遷移， 不同的是，最簡單的改變是 更新為新的個人化按鈕。可以透過替換 JavaScript 程式庫並更新程式碼集，以使用新的登入物件。

程式庫與設定

舊版的 Google 登入平台程式庫：apis.google.com/js/platform.js， 和 JavaScript 適用的 Google API 用戶端程式庫：gapi.client 不是 因此使用者驗證和授權作業的所需時間會降低。這些案例 由一個新的 Google Identity 服務 JavaScript 程式庫取代： accounts.google.com/gsi/client。

前三個 JavaScript 模組：api、client 和 platform 用於 登入程序已從「apis.google.com」載入。協助辨識地點 其中可能包含舊版程式庫，通常是：

  • 預設的登入按鈕會載入 apis.google.com/js/platform.js，
  • 自訂按鈕圖片載入 apis.google.com/js/api:client.js，以及
  • 直接使用 gapi.client 載入 apis.google.com/js/api.js。

在大部分的情況下，您可以繼續使用現有的網頁應用程式用戶端 ID 憑證建議您在遷移過程中，詳閱 OAuth 2.0 政策並使用 Google API 控制台 ，確認變更，並視需要更新下列用戶端設定：

  • 測試版和正式版應用程式會使用不同的專案，且有專屬的專案 Client-ID
  • OAuth 2.0 用戶端 ID 類型為「網頁應用程式」。
  • 針對已授權的 JavaScript 來源和重新導向 URI，系統會採用 HTTPS。

找出受影響的程式碼並進行測試

偵錯 Cookie 可協助找出受影響的程式碼，並在淘汰後測試 行為

在大型或複雜的應用程式中，可能很難找到所有受 淘汰 gapi.auth2 模組。如要記錄近期的使用情況 請前往控制台，將已淘汰的功能設為 G_AUTH2_MIGRATION Cookie 轉換為 informational。您也可以選擇在 並記錄到工作階段儲存空間。登入及收到 憑證進行審查，或將收集到的記錄傳送至後端，以供日後分析。適用對象 例如，informational:showauth2use 會將來源和網址儲存到工作階段儲存空間 名為 showauth2use 的金鑰。

如要在 gapi.auth2 模組不再載入時驗證應用程式行為，請設定 G_AUTH2_MIGRATION Cookie 的值設為 enforced。如此一來 在違規處置日期前，採取淘汰後的行為。

可能的 G_AUTH2_MIGRATION 個 Cookie 值：

  • enforced 不要載入 gapi.auth2 模組。
  • informational將已淘汰功能的使用情況記錄到 JS 控制台。一併記錄 如果設定選用的金鑰名稱，就會： informational:key-name。

為盡量減少使用者受到的影響，建議先在本機設定這個 Cookie 仍在開發和測試階段，然後再用於正式環境。

HTML 和 JavaScript

在這種僅限驗證的登入情境中，範例程式碼與轉譯 畫面上就會顯示現有的 Google 登入按鈕。從彈出式視窗或重新導向中選取 模式，觀察驗證回應的方式差異， JavaScript 回呼，或透過安全重新導向至後端伺服器登入的方式。 端點

先前

顯示 Google 登入按鈕，並使用回呼處理登入作業 直接透過使用者的瀏覽器

<html>
  <body>
    <script src="https://apis.google.com/js/platform.js" async defer></script>
    <meta name="google-signin-client_id" content="YOUR_CLIENT_ID">
    <div class="g-signin2" data-onsuccess="handleCredentialResponse"></div>
  </body>
</html>

重新導向模式

顯示 Google 登入按鈕，並在結尾為使用者的 AJAX 呼叫結束 將瀏覽器傳送至後端伺服器登入端點

<html>
  <body>
    <script src="https://apis.google.com/js/platform.js" async defer></script>
    <meta name="google-signin-client_id" content="YOUR_CLIENT_ID">
    <div class="g-signin2" data-onsuccess="handleCredentialResponse"></div>
    <script>
      function handleCredentialResponse(googleUser) {
        ...
        var xhr = new XMLHttpRequest();
        xhr.open('POST', 'https://yourbackend.example.com/tokensignin');
        xhr.setRequestHeader('Content-Type', 'application/x-www-form-urlencoded');
        xhr.onload = function() {
          console.log('Signed in as: ' + xhr.responseText);
        };
        xhr.send('idtoken=' + id_token);
      }
    </script>
  </body>
</html>

最終顯示的內容

新的視覺屬性簡化了先前建立自訂 按鈕，消除撥打 gapi.signin2.render() 的通話， 不費吹灰之力就能在網站上代管及維護圖片和影像素材資源

Google 登入

登入 Google

使用者登入狀態更新按鈕文字。

新做法

如何在僅限驗證的登入情境中使用新程式庫，請選取 請從彈出式視窗或重新導向模式中，使用這段程式碼 導入這些機制

使用回呼直接處理使用者瀏覽器中的登入。

<html>
  <body>
    <script src="https://accounts.google.com/gsi/client" async defer></script>
    <div id="g_id_onload"
         data-client_id="YOUR_CLIENT_ID"
         data-callback="handleCredentialResponse">
    </div>
    <div class="g_id_signin" data-type="standard"></div>
  </body>
</html>

重新導向模式

Google 會叫用您的登入端點 (由 data-login_url 指定) 屬性。先前您必須負責執行 POST 作業 參數名稱新的程式庫會將 ID 權杖發布至 credential 參數。最後，在您的後端驗證 ID 權杖。 伺服器

<html>
  <body>
    <script src="https://accounts.google.com/gsi/client" async defer></script>
    <div id="g_id_onload"
         data-client_id="YOUR_CLIENT_ID"
         data-ux_mode="redirect"
         data-login_uri="https://www.example.com/your_login_endpoint">
    </div>
    <div class="g_id_signin" data-type="standard"></div>
  </body>
</html>

最終顯示的內容

使用視覺屬性自訂「使用 Google 帳戶登入」按鈕 大小、形狀、顏色顯示 One Tap 彈出式視窗和個人化設定 可以提高登入率的按鈕。

使用 Google 帳戶登入 按鈕 輕觸一下 彈出式視窗

使用者登入狀態未更新「登入」的按鈕文字到 「已登入」。提供同意聲明或回訪後，個人化 這個按鈕包含使用者名稱、電子郵件地址和個人資料相片。

在這個僅限驗證範例中，新的 accounts.google.com/gsi/client 程式庫、g_id_signin 類別和 g_id_onload 物件 apis.google.com/js/platform.js 程式庫和 g-signin2 物件。

除了轉譯新的個人化按鈕外，範例程式碼也 會顯示新的 One Tap 彈出式視窗。無論您在哪裡顯示個人化按鈕 極力建議你一併顯示 One Tap 彈出式視窗，盡可能減少使用者操作 讓使用者的註冊流程更為流暢。

儘管我們不建議這麼做，因為 個人化按鈕可以單獨顯示，不用同時顯示 One Tap 對話方塊。方法是將 data-auto_prompt 屬性設為 false。

HTML 和 JavaScript API

上一個範例說明如何使用新的 HTML API 將登入程序新增至 你的網站或者，您可以使用功能對等的對等項目 JavaScript API，或在整個網站上混用 HTML 和 JavaScript API 網站。

以互動方式檢視按鈕自訂選項，例如回呼類型和 屬性，例如顏色、大小、形狀、文字和主題，請參閱程式碼 產生器。可用來快速比較不同選項 在網站上使用的 HTML 程式碼片段。

使用 One Tap 登入任何頁面

One Tap 是全新的簡便方式，讓使用者能夠輕鬆註冊或登入您的網站。 這項功能可讓使用者 直接從網站的任何網頁登入 使用者就不必造訪專屬的登入頁面。換句話說 讓使用者能彈性選擇 註冊及登入。

如要啟用任何網頁的登入功能，建議您在以下元素中加入 g_id_onload 在整個網站上共用相同的標頭、頁尾或其他物件。

建議您一併新增 g_id_signin，這將顯示個人化登入資訊 按鈕。為使用者提供選擇 將按鈕和其他聯盟網站列在一起 識別資訊提供者按鈕，以及使用者名稱和密碼輸入欄位。

權杖回應

不必再瞭解或運用 OAuth 2.0 使用者登入了 授權碼、存取權杖或重新整理權杖而是使用 JSON Web Token (JWT) ID 權杖可用來分享登入狀態和使用者個人資料。身為 我們導入這個 SDK 之後，不再需要使用「getter」樣式 存取子方法來處理使用者設定檔資料。

系統會傳回安全的 Google 簽署 JWT ID 權杖憑證，例如：

  • 透過彈出式視窗向使用者顯示瀏覽器型 JavaScript 回呼處理常式，或
  • 且 Google 會重新導向至您的登入端點 「使用 Google 帳戶登入」按鈕 ux_mode 已設為 redirect。

在這兩種情況下，請移除以下項目，以更新現有的回呼處理常式：

  • 對 googleUser.getBasicProfile() 的呼叫、
  • 對 BasicProfile 的參照，以及對 getId() 的相關呼叫 getName()、getGivenName()、getFamilyName()、getImageUrl()、 getEmail() 方法和
  • 使用 AuthResponse 物件。

請改為直接參照新 JWT 中的 credential 子欄位 CredentialResponse 物件，用於處理使用者設定檔資料。

此外，如果是只有重新導向模式，請務必避免跨網站要求 偽造 (CSRF) 和驗證後端伺服器上的 Google ID 權杖。

若想進一步瞭解使用者與網站的互動方式， CredentialResponse 中的 select_by 欄位可用來判斷使用者 同意聲明結果以及使用的登入流程

使用者首次登入您的網站時，Google 會提示使用者同意 可與您的應用程式分享帳戶個人資料。只有在提供同意聲明後，才能 透過 ID 權杖憑證酬載提供給應用程式的使用者設定檔。 撤銷這個設定檔的存取權，等同於撤銷 以及舊版登入資料庫

使用者可以撤銷權限，以及將應用程式與 Google 帳戶取消連結 請前往 https://myaccount.google.com/permissions。 或者，使用者也可能觸發 API，直接中斷與應用程式的連線 與您實作的呼叫先前的 disconnect 方法 已由新版 revoke 方法取代。

當使用者從你的平台上刪除帳戶時，最佳做法是使用 revoke已取消您的應用程式與 Google 帳戶的連結。

過去，auth2.signOut() 可協助管理使用者登出功能 即可。應用程式應移除所有使用「auth2.signOut()」的情況 應直接管理每個使用者工作階段的狀態和登入狀態。

工作階段狀態和監聽器

新程式庫不會保留網站的登入狀態或工作階段狀態 應用程式。

Google 帳戶的登入狀態，以及應用程式的工作階段狀態 登入狀態是不同獨立的概念。

使用者登入 Google 帳戶的狀態，您的應用程式各自獨立 除非你知道使用者 驗證成功並登入 Google 帳戶。

「使用 Google 帳戶登入」功能內建了 One Tap 或自動登入功能， 網站使用者必須先登入 Google 帳戶，才能執行以下操作：

  • 在使用者首次註冊或提供同意聲明時，提供同意聲明 登入網站
  • 並在回訪時登入網站。

使用者仍可保持登入、登出或切換到其他 Google 帳戶 同時在網站上進行登入工作階段。

現在，您已負責管理 即可快速導入 APIGoogle 登入先前可協助您監控使用者的 工作階段狀態

移除對 auth2.attachClickHandler() 及其已註冊的所有參照 回呼處理常式。

先前，Listener 用於共用登入狀態的變更 使用者的 Google 帳戶。不再支援事件監聽器。

移除對 listen()、auth2.currentUser 和 auth2.isSignedIn。

Cookie

「使用 Google 帳戶登入」功能會限制 Cookie 的使用方式 後面。請參閱 Google 如何運用 Cookie 。

舊版 Google 登入平台程式庫設定的 G_ENABLED_IDPS Cookie 不再使用

新版 Google Identity 服務程式庫可選擇性設定這些跨網域 根據您的設定選項建立 Cookie：

  • g_state 會儲存使用者的登出狀態，並在使用 One Tap 時設定 彈出式視窗或自動登入

  • g_csrf_token 是一種雙重提交 Cookie，用於防止 CSRF 攻擊 會在呼叫登入端點時設定。您的登入 URI 值 可以明確設定或採用目前網頁的 URI。您的 使用下列程式碼時，可呼叫登入端點：

    • 含有 data-ux_mode=redirect 或 data-login_uri 為 HTML API 設定或

    • 含有 ux_mode=redirect 的 JavaScript API google.accounts.id.prompt() 未用於顯示 One Tap 或 自動登入。

如果您有管理 Cookie 的服務，請務必新增兩個新的 Cookie 並在遷移作業完成後移除先前的 Cookie。

如果您管理多個網域或子網域，請參閱「在各處顯示 One Tap 功能 子網域，進一步瞭解使用 g_state Cookie 的進一步操作說明。

使用者登入作業的物件遷移參考資料

舊優惠 新功能 附註
JavaScript 程式庫
apis.google.com/js/platform.js accounts.google.com/gsi/client 更換為新舊裝置。
apis.google.com/js/api.js accounts.google.com/gsi/client 更換為新舊裝置。
GoogleAuth 物件和相關方法：
GoogleAuth.attachClickHandler() IdConfiguration.callback 適用於 JS 和 HTML 資料回呼 更換為新舊裝置。
GoogleAuth.currentUser.get() CredentialResponse 不再需要使用 CredentialResponse。
GoogleAuth.currentUser.listen() ，即可逐一移除離線觀看清單內的影片；無法取得使用者目前在 Google 的登入狀態。 使用者必須登入 Google，才能表示同意並登入。 select_by CredentialResponse 中的欄位可用於判斷 以及使用者的登入方式
GoogleAuth.disconnect() google.accounts.id.revoke 更換為新舊裝置。撤銷狀態可能也會透過 https://myaccount.google.com/permissions 撤銷
GoogleAuth.grantOfflineAccess() ，即可逐一移除離線觀看清單內的影片；ID 權杖已取代 OAuth 2.0 存取權杖和範圍。
GoogleAuth.isSignedIn.get() ，即可逐一移除離線觀看清單內的影片；無法取得使用者目前在 Google 的登入狀態。 使用者必須登入 Google，才能表示同意並登入。
GoogleAuth.isSignedIn.listen() ，即可逐一移除離線觀看清單內的影片；無法取得使用者目前在 Google 的登入狀態。 使用者必須登入 Google，才能表示同意並登入。
GoogleAuth.signIn() ，即可逐一移除離線觀看清單內的影片；HTML DOM 載入 g_id_signin 元素或 JS 呼叫 google.accounts.id.renderButton 觸發 Google 帳戶登入程序。
GoogleAuth.signOut() ，即可逐一移除離線觀看清單內的影片；您的應用程式和 Google 帳戶的使用者登入狀態： 而且不會產生獨立的差異Google 不會管理應用程式的工作階段狀態。
GoogleAuth.then() ，即可逐一移除離線觀看清單內的影片；GoogleAuth 已淘汰，
GoogleUser 物件和相關方法：
GoogleUser.disconnect() google.accounts.id.revoke 更換為新舊裝置。撤銷狀態可能也會透過 https://myaccount.google.com/permissions 撤銷
GoogleUser.getAuthResponse()
GoogleUser.getBasicProfile() CredentialResponse 直接使用 credential 和子欄位，而不是 BasicProfile 方法。
GoogleUser.getGrantedScopes() ，即可逐一移除離線觀看清單內的影片；ID 權杖已取代 OAuth 2.0 存取權杖和範圍。
GoogleUser.getHostedDomain() CredentialResponse 請直接使用 credential.hd。
GoogleUser.getId() CredentialResponse 請直接使用 credential.sub。
GoogleUser.grantOfflineAccess() ，即可逐一移除離線觀看清單內的影片；ID 權杖已取代 OAuth 2.0 存取權杖和範圍。
GoogleUser.grant() ，即可逐一移除離線觀看清單內的影片；ID 權杖已取代 OAuth 2.0 存取權杖和範圍。
GoogleUser.hasGrantedScopes() ，即可逐一移除離線觀看清單內的影片；ID 權杖已取代 OAuth 2.0 存取權杖和範圍。
GoogleUser.isSignedIn() ，即可逐一移除離線觀看清單內的影片；無法取得使用者目前在 Google 的登入狀態。 使用者必須登入 Google，才能表示同意並登入。
GoogleUser.reloadAuthResponse() ，即可逐一移除離線觀看清單內的影片；ID 權杖已取代 OAuth 2.0 存取權杖和範圍。
gapi.auth2 物件和相關方法：
gapi.auth2.AuthorizeConfig 物件 ，即可逐一移除離線觀看清單內的影片；ID 權杖已取代 OAuth 2.0 存取權杖和範圍。
gapi.auth2.AuthorizeResponse 物件 ，即可逐一移除離線觀看清單內的影片；ID 權杖已取代 OAuth 2.0 存取權杖和範圍。
gapi.auth2.AuthResponse 物件 ，即可逐一移除離線觀看清單內的影片；ID 權杖已取代 OAuth 2.0 存取權杖和範圍。
gapi.auth2.authorize() ，即可逐一移除離線觀看清單內的影片；ID 權杖已取代 OAuth 2.0 存取權杖和範圍。
gapi.auth2.ClientConfig() ，即可逐一移除離線觀看清單內的影片；ID 權杖已取代 OAuth 2.0 存取權杖和範圍。
gapi.auth2.getAuthInstance() ，即可逐一移除離線觀看清單內的影片；ID 權杖已取代 OAuth 2.0 存取權杖和範圍。
gapi.auth2.init() ，即可逐一移除離線觀看清單內的影片；ID 權杖已取代 OAuth 2.0 存取權杖和範圍。
gapi.auth2.OfflineAccessOptions 物件 ，即可逐一移除離線觀看清單內的影片；ID 權杖已取代 OAuth 2.0 存取權杖和範圍。
gapi.auth2.SignInOptions 物件 ，即可逐一移除離線觀看清單內的影片；ID 權杖已取代 OAuth 2.0 存取權杖和範圍。
gapi.signin2 物件和相關方法，如下所示：
gapi.signin2.render() ，即可逐一移除離線觀看清單內的影片；HTML DOM 載入 g_id_signin 元素或 JS 呼叫 google.accounts.id.renderButton 觸發 Google 帳戶登入程序。