本頁面由 Cloud Translation API 翻譯而成。
Switch to English

帶有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會將執行轉移到手機上。
  2. 該用戶登錄(如果尚未登錄),如果尚未授予Google許可,則可以使用您的API來訪問其數據。
  3. 您的服務將創建一個授權碼,並將其返回給Google。為此,請將用戶的瀏覽器重定向到Google,並在請求中附加授權碼。
  4. Google將授權代碼發送到您的令牌交換端點,該端點會驗證代碼的真實性並返回訪問令牌刷新令牌。訪問令牌是您的服務接受作為訪問API的憑據的短暫令牌。刷新令牌是一個長期存在的令牌,Google可以存儲該令牌並使用該令牌在新的訪問令牌到期時獲取這些令牌。
  5. 用戶完成帳戶鏈接流程後,從Google發送的每個後續請求都包含一個訪問令牌。

處理授權請求

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

授權端點參數
client_id您在Google註冊的Google客戶ID。
redirect_uri您將對此請求的響應發送到的URL。
state重定向URI中的傳遞給Google的簿記值保持不變。
scope可選:一組用空格分隔的範圍字符串,用於指定Google正在請求其授權的數據。
response_type要在響應中返回的值的類型。對於OAuth 2.0授權代碼流,響應類型始終為code
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&scope=REQUESTED_SCOPES&response_type=code&user_locale=LOCALE

為了使您的授權端點能夠處理登錄請求,請執行以下步驟:

  1. 驗證client_id與您在Google中註冊的Google客戶ID匹配,並且redirect_uri與Google為您提供的服務的重定向URL匹配。這些檢查對於防止授予對意外或錯誤配置的客戶端應用程序訪問很重要。如果您支持多個OAuth 2.0流,還請確認response_typecode
  2. 檢查用戶是否登錄到您的服務。如果用戶未登錄,請完成服務的登錄或註冊流程。
  3. 生成供Google訪問您的API的授權碼。授權代碼可以是任何字符串值,但是它必須唯一地代表用戶,令牌所針對的客戶端以及代碼的到期時間,並且不能讓人猜測。通常,您發出的授權碼將在大約10分鐘後過期。
  4. 確認redirect_uri參數指定的URL具有以下格式:
      https://oauth-redirect.googleusercontent.com/r/YOUR_PROJECT_ID
      https://oauth-redirect-sandbox.googleusercontent.com/r/YOUR_PROJECT_ID
      
  5. 將用戶的瀏覽器重定向到redirect_uri參數指定的URL。通過附加codestate參數進行重定向時,請包括剛生成的授權代碼以及未經修改的原始狀態值。以下是所得URL的示例:
    https://oauth-redirect.googleusercontent.com/r/YOUR_PROJECT_ID?code=AUTHORIZATION_CODE&state=STATE_STRING

處理令牌交換請求

服務的令牌交換端點負責兩種令牌交換:

  • 交換訪問令牌和刷新令牌的授權代碼
  • 將刷新令牌交換為訪問令牌

令牌交換請求包括以下參數:

令牌交換端點參數
client_id一個字符串,用於將請求來源標識為Google。此字符串必須在您的系統中註冊為Google的唯一標識符。
client_secret您在Google註冊的用於服務的秘密字符串。
grant_type交換令牌的類型。它是authorization_coderefresh_token
codegrant_type=authorization_code ,此參數是Google從您的登錄或令牌交換端點接收到的代碼。
redirect_urigrant_type=authorization_code ,此參數是初始授權請求中使用的URL。
refresh_tokengrant_type=refresh_token ,此參數是Google從令牌交換端點收到的刷新令牌。
交換訪問令牌和刷新令牌的授權代碼

用戶登錄後,您的授權端點將短暫的授權碼返回給Google,Google會向您的令牌交換端點發送請求,以將授權碼交換為訪問令牌和刷新令牌。

對於這些請求, grant_type的值是authorization_code ,而code的值是您之前授予Google的授權碼的值。以下是請求交換訪問令牌和刷新令牌的授權碼的示例:

POST /token HTTP/1.1
Host: oauth2.example.com
Content-Type: application/x-www-form-urlencoded

client_id=GOOGLE_CLIENT_ID&client_secret=GOOGLE_CLIENT_SECRET&grant_type=authorization_code&code=AUTHORIZATION_CODE&redirect_uri=REDIRECT_URI

要交換訪問令牌和刷新令牌的授權代碼,令牌交換端點通過執行以下步驟來響應POST請求:

  1. 驗證client_id將請求來源標識為授權來源,並且client_secret與期望值匹配。
  2. 驗證授權碼是否有效且未過期,以及請求中指定的客戶端ID是否與與授權碼關聯的客戶端ID匹配。
  3. 確認redirect_uri參數指定的URL與初始授權請求中使用的值相同。
  4. 如果無法驗證以上所有條件,請返回HTTP 400錯誤請求錯誤,並以{"error": "invalid_grant"}作為正文。
  5. 否則,使用授權碼中的用戶ID生成刷新令牌和訪問令牌。這些標記可以是任何字符串值,但是它們必須唯一地代表該標記所針對的用戶和客戶端,並且它們不可猜測。對於訪問令牌,還記錄令牌的到期時間,通常是您發行令牌後的一個小時。刷新令牌不會過期。
  6. 在HTTPS響應的主體中返回以下JSON對象:
    {
    "token_type": "Bearer",
    "access_token": "ACCESS_TOKEN",
    "refresh_token": "REFRESH_TOKEN",
    "expires_in": SECONDS_TO_EXPIRATION
    }
    

Google為用戶存儲訪問令牌和刷新令牌,並記錄訪問令牌的到期時間。訪問令牌過期後,Google會使用刷新令牌從您的令牌交換端點獲取新的訪問令牌。

將刷新令牌交換為訪問令牌

訪問令牌過期後,Google會向您的令牌交換端點發送請求,以將刷新令牌交換為新的訪問令牌。

對於這些請求, grant_type的值是refresh_token ,而refresh_token的值是您之前授予Google的刷新令牌的值。以下是將刷新令牌交換為訪問令牌的請求的示例:

POST /token HTTP/1.1
Host: oauth2.example.com
Content-Type: application/x-www-form-urlencoded

client_id=GOOGLE_CLIENT_ID&client_secret=GOOGLE_CLIENT_SECRET&grant_type=refresh_token&refresh_token=REFRESH_TOKEN

要將刷新令牌交換為訪問令牌,令牌交換端點將通過執行以下步驟來響應POST請求:

  1. 驗證client_id將請求來源標識為Google,並且client_secret與期望值匹配。
  2. 驗證刷新令牌是否有效,以及請求中指定的客戶端ID是否與與刷新令牌關聯的客戶端ID匹配。
  3. 如果您無法驗證所有上述條件,請返回HTTP 400錯誤請求錯誤,並以{"error": "invalid_grant"}作為正文。
  4. 否則,請使用刷新令牌中的用戶ID生成訪問令牌。這些標記可以是任何字符串值,但是它們必須唯一地代表該標記所針對的用戶和客戶端,並且它們不可猜測。對於訪問令牌,還記錄令牌的到期時間,通常是在您發行令牌後的一個小時內。
  5. 在HTTPS響應的主體中返回以下JSON對象:
    {
    "token_type": "Bearer",
    "access_token": " ACCESS_TOKEN ",
    "expires_in": SECONDS_TO_EXPIRATION
    }

驗證您的實施

您可以使用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. 確認您已重定向到平台。