帶有OAuth的Google帳戶鏈接

帳戶使用行業標準的OAuth 2.0隱式授權代碼流進行鏈接。您的服務必須支持符合OAuth 2.0的授權令牌交換端點。

隱式流程中,Google在用戶的瀏覽器中打開您的授權端點。成功登錄後,您可以將長期訪問令牌返回給Google。現在,此訪問令牌包含在Google發送的每個請求中。

授權代碼流中,您需要兩個端點:

  • 授權端點,向尚未登錄的用戶顯示登錄UI。授權端點還創建了一個短暫的授權代碼,以記錄用戶對所請求訪問的同意。

  • 令牌交換端點,它負責兩種類型的交換:

    1. 將授權代碼交換為長壽命的刷新令牌和短壽命的訪問令牌。當用戶完成帳戶鏈接流程時,就會發生這種交換。
    2. 將長壽命的刷新令牌交換為短壽命的訪問令牌。當Google需要一個新的訪問令牌(因為該令牌已過期)時,就會發生這種交換。

選擇一個OAuth 2.0流程

儘管隱式流更易於實現,但Google建議隱式流發出的訪問令牌永不過期。這是因為在令牌與隱式流一起過期之後,用戶被迫再次鏈接其帳戶。如果出於安全原因需要令牌到期,我們強烈建議您改用授權代碼流。

設計準則

本部分描述了託管OAuth鏈接流的用戶屏幕的設計要求和建議。在由Google應用程序調用後,您的平台會顯示登錄Google頁面和用戶的帳戶鏈接同意屏幕。在同意鏈接帳戶後,該用戶將被定向回到Google的應用程序。

此圖顯示了用戶將其Google帳戶鏈接到您的身份驗證系統的步驟。第一個屏幕截圖顯示了用戶從您的平台啟動的鏈接。第二張圖片顯示用戶登錄Google,第三張圖片顯示用戶同意並確認將其Google帳戶與您的應用程序關聯。最終的屏幕截圖顯示了Google應用程序中已成功鏈接的用戶帳戶。
圖1.帳戶鏈接用戶登錄到Google和同意屏幕。

要求

  1. 您必須告知用戶帳戶將鏈接到Google,而不是特定的Google產品(例如Google Home或Google Assistant)。

推薦建議

我們建議您執行以下操作:

  1. 顯示Google的隱私權政策。在同意屏幕上包括指向Google隱私權政策的鏈接。

  2. 要共享的數據。使用簡潔明了的語言告訴用戶Google需要提供哪些數據以及原因。

  3. 清除號召性用語。在您的同意屏幕上註明明確的號召性用語,例如“同意並鏈接”。這是因為用戶需要了解與Google共享帳戶鏈接所需的數據。

  4. 取消的能力。如果用戶選擇不鏈接,則為用戶提供返回或取消的方式。

  5. 清除登錄過程。確保用戶使用清晰的方法登錄自己的Google帳戶,例如用戶名和密碼或使用Google登錄字段。

  6. 取消鏈接的能力。為用戶提供取消鏈接的機制,例如指向其平台上的帳戶設置的URL。或者,您可以包含指向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帳戶鏈接過程包括一個同意屏幕,該屏幕告知用戶請求訪問其數據的應用程序,他們要求的數據類型以及適用的條款。在生成Google API客戶端ID之前,您需要先配置OAuth同意屏幕。

  1. 打開Google API控制台的OAuth同意屏幕頁面。
  2. 如果出現提示,請選擇剛剛創建的項目。
  3. 在“ OAuth同意屏幕”頁面上,填寫表格,然後單擊“保存”按鈕。

    申請名稱:要求同意的申請名稱。該名稱應準確反映您的應用程序,並與用戶在其他地方看到的應用程序名稱一致。應用程序名稱將顯示在“帳戶鏈接同意”屏幕上。

    應用程序徽標:同意屏幕上的圖像,可幫助用戶識別您的應用程序。徽標顯示在“帳戶鏈接同意”屏幕和帳戶設置上

    支持電子郵件:供用戶與您聯繫以獲取有關其同意的問題。

    Google API範圍範圍允許您的應用訪問用戶的私人Google數據。對於Google帳戶關聯用例,默認範圍(電子郵件,個人資料,openid)就足夠了,您無需添加任何敏感範圍。通常,最佳實踐是在需要訪問時而不是預先請求增量地作用域。 了解更多

    授權域:為了保護您和您的用戶,Google僅允許使用OAuth進行身份驗證的應用程序使用授權域。您的應用程序的鏈接必須託管在授權域中。 了解更多

    應用程序主頁鏈接:您的應用程序的主頁。必須託管在授權域中。

    應用程序隱私權政策鏈接:顯示在Google Acount Linking同意屏幕上。必須託管在授權域中。

    應用程序服務條款鏈接(可選):必須託管在授權域中。

    圖1 。虛擬應用程序Google Tuning的Google帳戶鏈接同意屏幕

  4. 選中“驗證狀態”,如果您的應用程序需要驗證,則單擊“提交驗證”按鈕以提交您的應用程序以進行驗證。有關詳細信息,請參閱OAuth驗證要求

實施您的OAuth服務器

為了支持OAuth 2.0隱式流程,您的服務將使HTTPS可以使用授權端點。該端點負責身份驗證並獲得用戶的同意以進行數據訪問。授權端點向尚未登錄的用戶顯示登錄UI,並記錄對請求訪問的同意。

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

由Google啟動的典型OAuth 2.0隱式流程會話具有以下流程:

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

處理授權請求

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

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

例如,如果您的授權端點位於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與您分配給Google的客戶ID匹配。
    • 確認由redirect_uri參數指定的URL具有以下格式:
      https://oauth-redirect.googleusercontent.com/r/YOUR_PROJECT_ID
      https://oauth-redirect-sandbox.googleusercontent.com/r/YOUR_PROJECT_ID
      
  2. 檢查用戶是否登錄到您的服務。如果用戶未登錄,請完成服務的登錄或註冊流程。

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

  4. 發送HTTP響應,該響應將用戶的瀏覽器redirect_uriredirect_uri參數指定的URL。在URL片段中包括以下所有參數:

    • access_token :您剛剛生成的訪問令牌
    • token_type :字符串bearer
    • state :原始請求中未修改的state值

    以下是所得URL的示例:

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

Google的OAuth 2.0重定向處理程序接收訪問令牌,並確認state值未更改。 Google獲取了您的服務的訪問令牌後,Google會將令牌附加到對您的服務API的後續調用中。

驗證您的實施

您可以使用OAuth 2.0 Playground工具來驗證您的實施。

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

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

您可以使用Google帳戶鏈接演示工具來驗證您的實施。

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

  1. 點擊“使用Google登錄”按鈕。
  2. 選擇您要鏈接的帳戶。
  3. 輸入服務ID。
  4. (可選)輸入一個或多個您將請求訪問的作用域。
  5. 單擊開始演示
  6. 出現提示時,請確認您同意並拒絕鏈接請求。
  7. 確認您已重定向到平台。