使用 OAuth 連結 Google 帳戶

帳戶連結使用業界標準 OAuth 2.0 隱含授權碼流程。您的服務必須支援符合 OAuth 2.0 規定的授權憑證交換端點。

在「暗示」流程中,Google 會在使用者的瀏覽器中開啟您的授權端點。成功登入後,會將長期存取憑證傳回 Google。目前從 Google 發出的每個要求都會包含這個存取憑證。

在「授權碼」流程中,您需要兩個端點:

  • Authorization 端點,可為尚未登入的使用者顯示登入 UI。授權端點也會建立短期的授權碼來記錄使用者。同意要求的存取權。

  • 憑證交換端點,該端點負責兩種交換類型:

    1. 將授權碼提供給長期使用憑證和短期存取憑證。當使用者完成帳戶連結流程時,系統就會執行這個交換作業。
    2. 針對短期存取權杖交換長期更新權杖。 如果 Google 需要這個存取憑證過期,因此需要進行這個交換作業。

選擇 OAuth 2.0 流程

雖然隱含流程比較簡單,但 Google 建議採用隱含流程所核發的存取憑證永遠不會過期。這是因為憑證在隱含流程到期後,必須強制重新連結帳戶。如果您需要基於安全考量而要求憑證過期,強烈建議您改用授權碼流程。

設計指南

本節說明您針對 OAuth 連結流程託管的使用者畫面設計要求和建議。在 Google 應用程式呼叫 API 後,您的平台會向使用者顯示登入 Google 頁面和帳戶連結同意畫面。使用者同意連結帳戶之後,系統就會將他們重新導向 Google 的應用程式。

下圖顯示使用者將 Google 帳戶連結到驗證系統的步驟。第一個螢幕截圖顯示了使用者從平台啟動的連結。第二張圖片則顯示使用者登入 Google 的第三張圖片,第三張圖片則顯示使用者同意授權及確認將自己的 Google 帳戶連結至您的應用程式。最終螢幕截圖顯示 Google app 中成功連結的使用者帳戶。
圖 1.連結 Google 帳戶和同意畫面的帳戶連結。

必要條件

  1. 您必須通知使用者的帳戶將連結至 Google,而不是特定的 Google 產品,例如 Google Home 或 Google 助理。

建議

建議您採取下列做法:

  1. 顯示 Google 的隱私權政策。在同意畫面中加入 Google 隱私權政策連結。

  2. 要分享的資料。使用簡明扼要的用詞告訴使用者 Google 需要哪些資料,以及收集這些資料的原因。

  3. 加入明確的行動號召。在同意畫面上註明明確的行動號召 (例如「同意和連結」)。這是因為使用者必須瞭解需要與 Google 分享哪些資料,才能連結自己的帳戶。

  4. 取消功能:如果使用者選擇不要進行連結,可以提供取消或取消訂閱的方式。

  5. 清除登入程序。確保使用者明確能登入 Google 帳戶,例如使用者名稱和密碼欄位或使用 Google 帳戶登入欄位。

  6. 取消連結。提供機制,讓使用者能取消連結,例如 您平台中帳戶設定的網址。您也可以加入 Google 帳戶連結,方便使用者管理已連結帳戶。

  7. 可變更使用者帳戶。建議使用者切換帳戶的方法。如果使用者經常擁有多個帳戶,這項功能就特別實用。

    • 如果使用者必須先關閉同意畫面才能切換帳戶,請將可復原的錯誤傳送給 Google,讓使用者可透過 OAuth 連結隱含流程登入所需帳戶。
  8. 加入您的標誌。在同意畫面中顯示公司標誌。 請善用樣式指南來放置標誌。如果您希望一併顯示 Google 的標誌,請參閱標誌和商標一文。

建立專案

如要建立專案以使用帳戶連結功能,請按照下列步驟操作:

  1. Go to the Google API Console.
  2. 單擊創建項目
  3. 輸入名稱或接受生成的建議。
  4. 確認或編輯所有剩餘字段。
  5. 點擊創建

要查看您的項目ID:

  1. Go to the Google API Console.
  2. 在登錄頁面的表格中找到您的項目。項目ID出現在ID列中。

Google 帳戶連結程序包含同意畫面,可告知使用者應用程式要求存取資料、要求的資料類型和適用的條款。您必須先設定 OAuth 同意畫面,才能產生 Google API 用戶端 ID。

  1. 開啟 Google API 控制台的「OAuth 同意畫面」頁面。
  2. 如果出現提示,請選取您剛建立的專案。
  3. 在「OAuth 同意畫面」頁面上,填寫表單,然後按一下「Save」按鈕。

    Application name (應用程式名稱):要求同意的應用程式名稱。名稱必須如實反映您的應用程式,並與使用者在其他地方看到的應用程式名稱一致。應用程式名稱會顯示在「帳戶連結同意」畫面中。

    應用程式標誌:可協助使用者識別您應用程式的圖片。這個標誌會顯示在帳戶連結同意畫面和帳戶設定

    支援電子郵件:方便使用者與您聯絡,詢問同意聲明問題。

    Google API 的範圍:「範圍」可讓應用程式存取使用者的私人 Google 資料。就 Google 帳戶連結的情況而言,預設範圍 (電子郵件、設定檔、openid) 就已足夠,您不需要新增任何敏感範圍。一般而言,最佳做法是逐步要求範圍,且在需要時而非預先存取權。瞭解詳情

    授權網域:為了保護您和您的使用者,Google 僅允許透過 OAuth 進行驗證的應用程式使用授權網域。您的應用程式連結必須託管於授權網域。瞭解詳情

    應用程式首頁連結:應用程式的首頁。必須由授權網域代管。

    應用程式隱私權政策連結:會顯示在 Google 帳戶連結同意畫面中。必須由授權網域代管。

    應用程式服務條款連結 (選用):必須由授權網域代管。

    圖 1. 虛構應用程式的 Google 帳戶連結同意畫面:Tunery

  4. 查看「驗證狀態」。若您的申請需要驗證,請按一下「提交驗證申請」按鈕,提交驗證申請。詳情請參閱「OAuth 驗證規定」一文。

實作 OAuth 伺服器

為了支持OAuth 2.0已隱含流,你的服務使可通過HTTPS授權端點。此端點負責身份驗證並獲得用戶對數據訪問的同意。授權端點向尚未登錄的用戶顯示登錄 UI,並記錄對請求訪問的同意。

當 Google 應用程序需要調用您的服務的授權 API 之一時,Google 會使用此端點來獲得您的用戶的許可,以代表他們調用這些 API。

一個典型的由 Google 發起的 OAuth 2.0 隱式流會話具有以下流程:

  1. Google 在用戶的瀏覽器中打開您的授權端點。用戶登錄(如果尚未登錄)並授予 Google 使用您的 API 訪問其數據的權限(如果他們尚未授予權限)。
  2. 您的服務創建的訪問令牌並將其返回給谷歌。為此,請使用附加到請求的訪問令牌將用戶的瀏覽器重定向回 Google。
  3. Google 會調用您服務的 API 並在每個請求中附加訪問令牌。您的服務會驗證訪問令牌授予 Google 訪問 API 的授權,然後完成 API 調用。

處理授權請求

當 Google 應用程序需要通過 OAuth 2.0 隱式流程執行帳戶鏈接時,Google 會將用戶發送到您的授權端點,並包含以下參數的請求:

授權端點參數
client_id您分配給 Google 的客戶端 ID。
redirect_uri您向其發送對此請求的響應的 URL。
state傳遞回 Google 的簿記值在重定向 URI 中保持不變。
response_type要在響應中返回的值的類型。對於的OAuth 2.0隱式流程中,響應類型總是token
user_locale在谷歌帳戶語言設置RFC5646格式用於本地化用戶的首選語言內容。

例如,如果您的授權端點可在https://myservice.example.com/auth ,請求看起來像下面這樣:

GET https://myservice.example.com/auth?client_id=GOOGLE_CLIENT_ID&redirect_uri=REDIRECT_URI&state=STATE_STRING&response_type=token&user_locale=LOCALE

對於處理登錄請求的授權端點,請執行以下步驟:

  1. 驗證client_idredirect_uri值,以防止授權訪問意外或錯誤配置的客戶端應用程序:

    • 確認該client_id你分配給谷歌的客戶ID相匹配。
    • 確認URL指定由redirect_uri參數有以下形式:
      https://oauth-redirect.googleusercontent.com/r/YOUR_PROJECT_ID
      https://oauth-redirect-sandbox.googleusercontent.com/r/YOUR_PROJECT_ID
      
  2. 檢查用戶是否已登錄您的服務。如果用戶未登錄,請完成服務的登錄或註冊流程。

  3. 生成供 Google 用來訪問您的 API 的訪問令牌。訪問令牌可以是任何字符串值,但它必須唯一地代表該令牌所針對的用戶和客戶端,並且不能被猜測。

  4. 發送用戶的瀏覽器重定向到被指定的URL的HTTP響應redirect_uri參數。在 URL 片段中包含以下所有參數:

    • access_token :剛才生成的令牌,你的訪問
    • token_type :字符串bearer
    • state :從原始請求的未修改的狀態值

    以下是所得的URL的一個示例:

    https://oauth-redirect.googleusercontent.com/r/YOUR_PROJECT_ID#access_token=ACCESS_TOKEN&token_type=bearer&state=STATE_STRING

谷歌的OAuth 2.0重定向處理接收的令牌的訪問並確認state的值並沒有改變。在 Google 為您的服務獲取訪問令牌後,Google 會將令牌附加到對您的服務 API 的後續調用中。

處理用戶信息請求

用戶信息終端是一個OAuth 2.0保護的資源,對鏈接的用戶返回的權利要求。實現和託管 userinfo 端點是可選的,以下用例除外:

從您的令牌端點成功檢索訪問令牌後,Google 會向您的 userinfo 端點發送請求,以檢索有關鏈接用戶的基本個人資料信息。

userinfo 端點請求標頭
Authorization header Bearer 類型的訪問令牌。

例如,如果你的用戶信息終端可在https://myservice.example.com/userinfo ,請求看起來像下面這樣:

GET /userinfo HTTP/1.1
Host: myservice.example.com
Authorization: Bearer ACCESS_TOKEN

要讓您的 userinfo 端點處理請求,請執行以下步驟:

  1. 從 Authorization 標頭中提取訪問令牌並返回與訪問令牌關聯的用戶的信息。
  2. 如果訪問令牌無效,返回HTTP 401錯誤未經授權使用的WWW-Authenticate響應頭。下面是一個userinfo的錯誤響應的一個示例:
    HTTP/1.1 401 Unauthorized
    WWW-Authenticate: error="invalid_token",
    error_description="The Access Token expired"
    
    如果一個401未經授權,或任何其它不成功錯誤響應在關聯過程返回時,誤差將是不可恢復的,所檢索的令牌將被丟棄,並且用戶將必須再次啟動鏈接過程。
  3. 如果訪問令牌是有效的,回國與以下JSON對象在HTTPS響應的身體HTTP 200回應:

    {
    "sub": "USER_UUID",
    "email": "EMAIL_ADDRESS",
    "given_name": "FIRST_NAME",
    "family_name": "LAST_NAME",
    "name": "FULL_NAME",
    "picture": "PROFILE_PICTURE",
    }
    
    如果你的用戶信息端點返回一個HTTP 200成功響應,檢索到的令牌和索賠登記針對用戶的谷歌帳戶。

    用戶信息端點響應
    sub標識系統中用戶的唯一 ID。
    email用戶的電子郵件地址。
    given_name可選:用戶的名字。
    family_name可選:用戶的姓氏。
    name可選:用戶的全名。
    picture可選:用戶的檔案圖片。

驗證實作

您可以通過使用驗證實現的OAuth 2.0遊樂場工具。

在工具中,執行以下步驟:

  1. 單擊配置打開的OAuth 2.0配置窗口。
  2. OAuth流場中,選擇客戶端
  3. OAuth端點字段中,選擇自定義
  4. 在相應字段中指定您的 OAuth 2.0 端點和您分配給 Google 的客戶端 ID。
  5. 步驟1部分,不要選擇任何谷歌範圍。相反,將此字段留空或鍵入對您的服務器有效的範圍(如果不使用 OAuth 範圍,則輸入任意字符串)。當您完成後,單擊授權的API。
  6. 步驟2步驟3段,完成OAuth 2.0流程和驗證每個步驟按預期工作。

您可以通過驗證您的實現谷歌帳戶鏈接演示工具。

在工具中,執行以下步驟:

  1. 點擊登錄在與谷歌按鈕。
  2. 選擇您要關聯的帳戶。
  3. 輸入服務標識。
  4. (可選)輸入您將請求訪問的一個或多個範圍。
  5. 單擊開始演示
  6. 出現提示時,確認您可以同意並拒絕鏈接請求。
  7. 確認您被重定向到您的平台。