使用 OAuth 連結 Google 帳戶

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

隐式流程中,Google 会在用户的浏览器中打开您的授权端点。成功登录后,系统会将长期访问令牌返回到 Google。现在,从 Google 发送的每个请求中都包含此访问令牌。

授权代码流程中,您需要两个端点:

  • 授权端点 - 向尚未登录的用户显示登录界面。授权端点还会创建一个短期授权代码,用于记录用户针对所请求的访问权限的同意情况。

  • 令牌交换端点,负责两种交换类型:

    1. 将授权代码交换为长期刷新令牌和短期访问令牌。这种交换会在用户完成帐号关联流程时进行。
    2. 将长期有效的刷新令牌交换为短期访问令牌。当 Google 需要新的访问令牌时,由于此令牌已过期,因此出现这种交换。

选择 OAuth 2.0 流程

虽然隐式数据流的实现过程更简单,但 Google 建议隐式数据流签发的访问令牌永远不会过期。这是因为在令牌随隐式流程过期后,用户被迫再次关联自己的帐号。出于安全考虑,如果您需要令牌过期,我们强烈建议您改为使用授权代码流程。

设计准则

本部分将介绍针对 OAuth 关联流程托管的用户屏幕的设计要求和建议。在由 Google 的应用调用后,您的平台会向用户显示“登录 Google”页面和帐号关联屏幕。用户同意关联帐号后,会被重定向回 Google 的应用。

此图显示了用户将其 Google 帐号与身份验证系统关联的步骤。第一个屏幕截图显示了用户从您的平台发起的关联。第二张图片展示了用户登录 Google 的界面,第三张图片显示了用户同意将其 Google 帐号与应用关联的确认消息。最后的屏幕截图显示的是已成功在 Google 应用中关联的用户帐号。
图 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. 確認您被重定向到您的平台。