從 Google 登入遷移

本指南可協助您瞭解成功遷移 JavaScript 程式庫所需的變更和步驟，將舊版 Google 登入平台資料庫遷移至新版 Google Identity 服務資料庫，以便進行驗證。

如果您的用戶端使用的是適用於 JavaScript 的 Google API 用戶端程式庫或其他舊版程式庫來進行授權，請參閱「遷移至 Google 身分識別服務」一文，瞭解詳情。

驗證及授權

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

與先前的 Google 登入平台資料庫一樣，新的 Google Identity 服務資料庫也同時支援驗證和授權程序。

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

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

如果您的用途包含授權，請參閱使用者授權的運作方式和遷移至 Google Identity 服務一文，確認應用程式使用的是改良後的新版 API。

異動情形

對於使用者而言，新的 Google Identity 服務程式庫提供許多可用性改善功能。主要包含：

  • 新的低摩擦 One Tap 和自動登入流程，可減少個別步驟
  • 更新的登入按鈕，提供使用者個人化體驗
  • 在網路上提供一致的品牌形象和登入行為，有助於提升使用者對 Google 的理解和信任。
  • 快速取得內容；使用者可在網站上的任何位置直接註冊及登入，無須先前往登入或帳戶頁面。

對開發人員來說，我們的重點是降低複雜性、提升安全性，並盡可能加快整合速度。其中一些改進項目包括：

  • 選擇只透過 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 控制台 確認並視需要更新下列用戶端設定：

  • 測試版和正式版應用程式使用不同的專案，且各自有專屬的用戶端 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>

最終顯示的內容

使用 visual-attributes 自訂「使用 Google 帳戶登入」按鈕的大小、形狀和顏色。顯示 One Tap 彈出式視窗和個人化按鈕，提高登入率。

「使用 Google 帳戶登入」按鈕 One Tap 彈出式視窗

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

在這個僅限驗證的範例中，新的 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 權杖分享登入狀態和使用者個人資料。為了進一步簡化，您不再需要使用「getter」樣式的存取方法來處理使用者設定檔資料。

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

  • 傳送至使用者在彈出式模式中，以瀏覽器為基礎的 JavaScript 回呼處理常式，或
  • 當「使用 Google 帳戶登入」按鈕 ux_mode 設為 redirect 時，系統會透過 Google 重新導向至您的後端伺服器。

無論是哪種情況，請更新現有的回呼處理常式，方法是移除：

  • 撥打至 googleUser.getBasicProfile() 的電話
  • BasicProfile 參照項目，以及對 getId()、getName()、getGivenName()、getFamilyName()、getImageUrl()、getEmail() 方法的相關呼叫，以及
  • AuthResponse 物件的用法。

請改為直接參照新 JWT CredentialResponse 物件中的 credential 子欄位，以便處理使用者個人資料。

此外，也請務必防止跨網站要求偽造 (CSRF) 和驗證後端伺服器上的 Google ID 權杖 (僅適用於重新導向模式)。

如要進一步瞭解使用者與網站的互動情形，您可以使用 CredentialResponse 中的 select_by 欄位，判斷使用者同意結果和使用的特定登入流程。

使用者初次登入您的網站時，Google 會提示使用者同意將帳戶個人資料提供給您的應用程式。只有在使用者提供同意聲明後，系統才會透過 ID 權杖憑證酬載，將使用者個人資料提供給您的應用程式。撤銷此設定檔的存取權，等同於撤銷先前登入程式庫中的存取權杖。

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

當使用者在您的平台上刪除帳戶時，最佳做法是使用 revoke 將應用程式與使用者的 Google 帳戶解除連結。

先前，您可以使用 auth2.signOut() 管理使用者從應用程式登出的情況。您應移除所有 auth2.signOut() 的用途，並直接管理個別使用者的會話狀態和登入狀態。

工作階段狀態和 Listener

新程式庫不會為您的網頁應用程式維持登入狀態或工作階段狀態。

Google 帳戶的登入狀態、應用程式的會話狀態和登入狀態是不同的概念。

使用者登入 Google 帳戶和應用程式的狀態彼此獨立，但在登入過程中，您知道使用者已成功驗證並登入 Google 帳戶時，這兩者就會相互關聯。

當您在網站上加入「使用 Google 帳戶登入」、「One Tap 登入」或「自動登入」功能時，使用者必須先登入 Google 帳戶，才能：

  • 在使用者首次註冊或登入網站時 提供同意聲明
  • 後續可用於使用者下次造訪網站時登入。

使用者可以在網站上保持登入狀態、登出或切換至其他 Google 帳戶，同時維持有效的登入工作階段。

您現在必須直接管理網頁應用程式使用者的登入狀態。先前，Google 登入功能可協助監控使用者的工作階段狀態。

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

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

移除對 listen()、auth2.currentUser 和 auth2.isSignedIn 的所有參照。

Cookie

「使用 Google 帳戶登入」功能會有限度使用 Cookie，但對於這類 Cookie 的說明內容如下。如要進一步瞭解 Google 使用的其他類型 Cookie，請參閱「Google 如何使用 Cookie」。

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

新的 Google Identity Services 程式庫可視情況根據您的設定選項，設定下列跨網域 Cookie：

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

  • g_csrf_token 是用於防範 CSRF 攻擊的雙重提交 Cookie，會在登入端點呼叫時設定。您可以明確設定登入 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() 針對 JS 和 HTML 的 data-callback 使用 IdConfiguration.callback 以新內容取代舊內容。
GoogleAuth.currentUser.get() CredentialResponse 改用 CredentialResponse，不再需要使用。
GoogleAuth.currentUser.listen() ，即可逐一移除離線觀看清單內的影片；無法取得使用者在 Google 上的目前登入狀態。 使用者必須登入 Google 帳戶，才能同意使用服務和登入服務。 CredentialResponse 中的 select_by 欄位可用於判斷使用者同意聲明的結果，以及所使用的登入方式。
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 元素，或對 google.accounts.id.renderButton 發出 JS 呼叫，即可觸發使用者登入 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 元素，或對 google.accounts.id.renderButton 發出 JS 呼叫，即可觸發使用者登入 Google 帳戶。