帳戶連結使用業界標準 OAuth 2.0 隱含與授權碼流程。您的服務必須支援符合 OAuth 2.0 規定的授權和憑證交換端點。
在隐式流程中,Google 会在用户的浏览器中打开您的授权端点。成功登录后,系统会将长期访问令牌返回到 Google。现在,从 Google 发送的每个请求中都包含此访问令牌。
在授权代码流程中,您需要两个端点:
授权端点 - 向尚未登录的用户显示登录界面。授权端点还会创建一个短期授权代码,用于记录用户针对所请求的访问权限的同意情况。
令牌交换端点,负责两种交换类型:
- 将授权代码交换为长期刷新令牌和短期访问令牌。这种交换会在用户完成帐号关联流程时进行。
- 将长期有效的刷新令牌交换为短期访问令牌。当 Google 需要新的访问令牌时,由于此令牌已过期,因此出现这种交换。
选择 OAuth 2.0 流程
虽然隐式数据流的实现过程更简单,但 Google 建议隐式数据流签发的访问令牌永远不会过期。这是因为在令牌随隐式流程过期后,用户被迫再次关联自己的帐号。出于安全考虑,如果您需要令牌过期,我们强烈建议您改为使用授权代码流程。
设计准则
本部分将介绍针对 OAuth 关联流程托管的用户屏幕的设计要求和建议。在由 Google 的应用调用后,您的平台会向用户显示“登录 Google”页面和帐号关联屏幕。用户同意关联帐号后,会被重定向回 Google 的应用。
![此图显示了用户将其 Google 帐号与身份验证系统关联的步骤。第一个屏幕截图显示了用户从您的平台发起的关联。第二张图片展示了用户登录 Google 的界面,第三张图片显示了用户同意将其 Google 帐号与应用关联的确认消息。最后的屏幕截图显示的是已成功在 Google 应用中关联的用户帐号。](https://developers.google.cn/static/identity/images/oauth-linking-flow.png?authuser=3&hl=zh-tw)
要求
- 您必须告知用户该用户帐号将与 Google 关联,而不是与特定 Google 产品(例如 Google Home 或 Google 助理)关联。
建议
建议您执行以下操作:
显示 Google 的隐私权政策。在同意屏幕上添加指向 Google 隐私权政策的链接。
要共享的数据。使用简洁明了的语言向用户说明他们的 Google 需要哪些数据以及为何收集这些数据。
明确的号召性用语。在同意屏幕上提供明确的号召性用语,例如“同意并关联”。这是因为用户需要了解他们需要与 Google 共享哪些数据,才能关联帐号。
能够取消。如果用户不关联,则可以提供返回或取消的方式。
清除登录流程。确保用户有明确的登录 Google 帐号的方法,例如用户名和密码字段或使用 Google 帐号登录字段。
能够解除关联。为用户提供解除关联的机制,例如他们在平台上的帐号设置网址。或者,您也可以添加指向 Google 帐号的链接,以便用户可以管理关联的帐号。
能够更改用户帐号。推荐一种供用户切换帐号的方法。如果用户往往拥有多个帐号,这一点尤其有用。
- 如果用户必须关闭同意屏幕才能切换帐号,请向 Google 发送一个可恢复错误,以便用户通过 OAuth 关联和隐式流程登录所需帐号。
添加徽标。在同意屏幕上显示公司徽标。 根据样式指南放置徽标。如果您还希望显示 Google 的徽标,请参阅徽标和商标。
![下图显示了示例用户登录和同意屏幕,其中列出了设计用户登录和同意屏幕时需要遵循的各项要求和建议。](https://developers.google.cn/static/identity/images/oauth-linking-consent.png?authuser=3&hl=zh-tw)
建立專案
如要建立專案以使用帳戶連結功能,請按照下列步驟操作:
- Go to the Google API Console.
- 單擊創建項目 。
- 輸入名稱或接受生成的建議。
- 確認或編輯所有剩餘字段。
- 點擊創建 。
要查看您的項目ID:
- Go to the Google API Console.
- 在登錄頁面的表格中找到您的項目。項目ID出現在ID列中。
設定 OAuth 同意畫面
Google 帳戶連結程序包含同意畫面,可告知使用者應用程式要求存取資料、要求的資料類型和適用的條款。您必須先設定 OAuth 同意畫面,才能產生 Google API 用戶端 ID。
- 開啟 Google API 控制台的「OAuth 同意畫面」頁面。
- 如果出現提示,請選取您剛建立的專案。
在「OAuth 同意畫面」頁面上,填寫表單,然後按一下「Save」按鈕。
Application name (應用程式名稱):要求同意的應用程式名稱。名稱必須如實反映您的應用程式,並與使用者在其他地方看到的應用程式名稱一致。應用程式名稱會顯示在「帳戶連結同意」畫面中。
應用程式標誌:可協助使用者識別您應用程式的圖片。這個標誌會顯示在帳戶連結同意畫面和帳戶設定中
支援電子郵件:方便使用者與您聯絡,詢問同意聲明問題。
Google API 的範圍:「範圍」可讓應用程式存取使用者的私人 Google 資料。就 Google 帳戶連結的情況而言,預設範圍 (電子郵件、設定檔、openid) 就已足夠,您不需要新增任何敏感範圍。一般而言,最佳做法是逐步要求範圍,且在需要時而非預先存取權。瞭解詳情。
授權網域:為了保護您和您的使用者,Google 僅允許透過 OAuth 進行驗證的應用程式使用授權網域。您的應用程式連結必須託管於授權網域。瞭解詳情。
應用程式首頁連結:應用程式的首頁。必須由授權網域代管。
應用程式隱私權政策連結:會顯示在 Google 帳戶連結同意畫面中。必須由授權網域代管。
應用程式服務條款連結 (選用):必須由授權網域代管。
圖 1. 虛構應用程式的 Google 帳戶連結同意畫面:Tunery
查看「驗證狀態」。若您的申請需要驗證,請按一下「提交驗證申請」按鈕,提交驗證申請。詳情請參閱「OAuth 驗證規定」一文。
實作 OAuth 伺服器
為了支持OAuth 2.0已隱含流,你的服務使可通過HTTPS授權端點。此端點負責身份驗證並獲得用戶對數據訪問的同意。授權端點向尚未登錄的用戶顯示登錄 UI,並記錄對請求訪問的同意。
當 Google 應用程序需要調用您的服務的授權 API 之一時,Google 會使用此端點來獲得您的用戶的許可,以代表他們調用這些 API。
一個典型的由 Google 發起的 OAuth 2.0 隱式流會話具有以下流程:
- Google 在用戶的瀏覽器中打開您的授權端點。用戶登錄(如果尚未登錄)並授予 Google 使用您的 API 訪問其數據的權限(如果他們尚未授予權限)。
- 您的服務創建的訪問令牌並將其返回給谷歌。為此,請使用附加到請求的訪問令牌將用戶的瀏覽器重定向回 Google。
- 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
對於處理登錄請求的授權端點,請執行以下步驟:
驗證
client_id
和redirect_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
- 確認該
檢查用戶是否已登錄您的服務。如果用戶未登錄,請完成服務的登錄或註冊流程。
生成供 Google 用來訪問您的 API 的訪問令牌。訪問令牌可以是任何字符串值,但它必須唯一地代表該令牌所針對的用戶和客戶端,並且不能被猜測。
發送用戶的瀏覽器重定向到被指定的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 端點處理請求,請執行以下步驟:
- 從 Authorization 標頭中提取訪問令牌並返回與訪問令牌關聯的用戶的信息。
- 如果訪問令牌無效,返回HTTP 401錯誤未經授權使用的
WWW-Authenticate
響應頭。下面是一個userinfo的錯誤響應的一個示例:HTTP/1.1 401 Unauthorized WWW-Authenticate: error="invalid_token", error_description="The Access Token expired"
如果一個401未經授權,或任何其它不成功錯誤響應在關聯過程返回時,誤差將是不可恢復的,所檢索的令牌將被丟棄,並且用戶將必須再次啟動鏈接過程。 如果訪問令牌是有效的,回國與以下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遊樂場工具。
在工具中,執行以下步驟:
- 單擊配置 打開的OAuth 2.0配置窗口。
- 在OAuth流場中,選擇客戶端。
- 在OAuth端點字段中,選擇自定義。
- 在相應字段中指定您的 OAuth 2.0 端點和您分配給 Google 的客戶端 ID。
- 在步驟1部分,不要選擇任何谷歌範圍。相反,將此字段留空或鍵入對您的服務器有效的範圍(如果不使用 OAuth 範圍,則輸入任意字符串)。當您完成後,單擊授權的API。
- 在步驟2和步驟3段,完成OAuth 2.0流程和驗證每個步驟按預期工作。
您可以通過驗證您的實現谷歌帳戶鏈接演示工具。
在工具中,執行以下步驟:
- 點擊登錄在與谷歌按鈕。
- 選擇您要關聯的帳戶。
- 輸入服務標識。
- (可選)輸入您將請求訪問的一個或多個範圍。
- 單擊開始演示。
- 出現提示時,確認您可以同意並拒絕鏈接請求。
- 確認您被重定向到您的平台。