帳戶連結會使用業界標準的 OAuth 2.0 隱含和授權碼流程。您的服務必須支援符合 OAuth 2.0 標準的授權和權杖交換端點。
在隱含流程中,Google 會在使用者的瀏覽器中開啟授權端點。成功登入後,會將長期存取權杖傳回 Google。這個存取權杖現在已納入 Google 發出的每項要求。
在授權碼流程中,您需要兩個端點:
授權端點,會為尚未登入的使用者顯示登入 UI。授權端點也會建立短效授權碼,記錄使用者對所要求存取權的同意聲明。
權杖交換端點,負責兩種交換:
- 交換授權碼用於長期更新權杖和短期存取權杖。使用者進行帳戶連結流程時,就會發生這個交換。
- 這個外掛程式能使用長期更新權杖做為短期存取權杖。 如果 Google 需要新的存取權存證,因為舊的存證已過期,就會發生此交換。
選擇 OAuth 2.0 流程
雖然隱含流程的實作方式較簡單,但 Google 建議隱含流程發出的存取權杖永遠不會過期。這是因為權杖過期後,系統必須要求使用者再次連結帳戶。如果您基於安全性考量而需要代碼到期,強烈建議您改用授權程式碼流程。
設計指南
本節說明針對 OAuth 連結流程所託管使用者畫面的設計需求和建議。Google 的應用程式呼叫後,您的平台會向使用者顯示登入 Google 頁面和帳戶連結同意畫面。使用者同意連結帳戶後,系統會將他們導向 Google 的應用程式。
需求條件
- 您必須說明使用者的帳戶將連結至 Google,而不是 Google Home 或 Google 助理等特定 Google 產品。
建議
建議您採取以下做法:
顯示《Google 隱私權政策》。在同意畫面加入 Google 隱私權政策連結。
要共用的資料。使用簡潔明瞭的表達方式,向使用者說明 Google 需要他們的哪些資料,以及原因。
明確的行動號召。在同意聲明畫面上明確列出行動號召,例如「同意並連結」。這是因為使用者需要瞭解自己必須與 Google 分享哪些資料,才能連結帳戶。
可取消訂閱。如果使用者選擇不連結,請提供返回或取消的選項。
清除登入程序。請確認使用者有明確的方法登入 Google 帳戶,例如使用者名稱和密碼欄位,或使用 Google 帳戶登入。
可取消連結。提供使用者解除連結的機制,例如平台上帳戶設定的網址。或者,您也可以加入 Google 帳戶的連結,讓使用者能管理已連結帳戶。
變更使用者帳戶的功能。建議使用者切換帳戶的方法。如果使用者傾向擁有多個帳戶,這項功能就特別實用。
- 如果使用者必須關閉同意畫面才能切換帳戶,請將可復原的錯誤傳送給 Google,方便使用者透過 OAuth 連結和隱含流程登入所需帳戶。
加入標誌。在同意畫面上顯示公司標誌。 請依照您的樣式規範放置標誌。如果您也想顯示 Google 的標誌,請參閱標誌和商標。
创建项目
如需创建项目以使用账号关联功能,请执行以下操作:
配置 OAuth 同意屏幕
Google 账号关联流程包含一个权限请求页面,用于告知用户请求访问其数据的应用、应用请求访问的数据类型以及适用的条款。您需要先配置 OAuth 权限请求页面,然后才能生成 Google API 客户端 ID。
- 打开 Google API 控制台的 OAuth 同意屏幕页面。
- 如果出现提示,请选择您刚刚创建的项目。
在“OAuth 同意屏幕”页面上,填写表单,然后点击“保存”按钮。
应用名称:征求用户同意的应用的名称。该名称应准确反映您的应用,并与用户在其他地方看到的应用名称一致。应用名称将显示在账号关联意见征求界面上。
应用徽标:权限请求页面上显示的一张图片,用以让用户认出您的应用。该徽标会显示在账号关联意见征求页面和账号设置中
支持电子邮件:供用户就其是否同意的问题与您联系。
Google API 的范围:借助范围,您的应用可以访问用户的私密 Google 数据。对于 Google 账号关联用例,默认范围(电子邮件地址、个人资料、openid)已足够,您无需添加任何敏感范围。通常,最佳做法是在需要访问权限时逐步请求相应权限范围,而不是提前请求。了解详情。
已获授权的网域:为了保护您和您的用户,Google 只允许使用 OAuth 进行身份验证的应用使用已获授权的网域。您应用的链接必须托管在已获授权的网域上。了解详情。
应用首页链接:应用的首页。必须托管在已获授权的网域上。
应用隐私权政策链接:显示在 Google 账号关联意见征求界面上。必须托管在已获授权的网域上。
应用服务条款链接(可选):必须托管在已获授权的网域上。
图 1. 虚构应用 Tunery 的 Google 账号关联意见征求界面
查看“验证状态”,如果您的应用需要验证,请点击“提交以供验证”按钮,以提交您的应用以供验证。如需了解详情,请参阅 OAuth 验证要求。
實作 OAuth 伺服器
为了支持 OAuth 2.0 隐式流,您的服务会进行授权 端点。此端点负责进行身份验证, 就数据访问征得用户同意。授权端点 向尚未登录的用户显示登录界面,并记录 同意所请求的访问。
当 Google 应用需要调用您的某项服务获得授权的 API 时, Google 使用此端点从您的用户处获取调用这些 API 的权限 。
由 Google 发起的典型 OAuth 2.0 隐式流会话具有以下特征: 以下流程:
- Google 会在用户的浏览器中打开您的授权端点。通过 如果用户尚未登录,则直接登录,然后授予 Google 以下权限: 访问您的 API 访问其数据(如果尚未授权)。
- 您的服务会创建一个访问令牌并将其返回给 Google。为此,请将用户的浏览器重定向回 Google,并提供相应的访问权限 令牌。
- Google 调用您的服务的 API,并附加带有 。您的服务会验证访问令牌是否向 Google 授予 访问 API 的授权,然后完成 API 调用。
处理授权请求
当 Google 应用需要通过 OAuth 2.0 执行账号关联时 隐式流程,Google 会通过 请求,其中包含以下参数:
授权端点参数 | |
---|---|
client_id |
您分配给 Google 的客户 ID。 |
redirect_uri |
此请求的响应发送到的网址。 |
state |
将一个在 重定向 URI。 |
response_type |
要在响应中返回的值的类型。对于 OAuth 2.0 隐式
则响应类型始终为 token 。 |
user_locale |
“Google 账号语言设置” 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 匹配 分配给 Google。 - 确认
redirect_uri
指定的网址 参数的格式如下:https://oauth-redirect.googleusercontent.com/r/YOUR_PROJECT_ID https://oauth-redirect-sandbox.googleusercontent.com/r/YOUR_PROJECT_ID
- 确认
检查用户是否已登录您的服务。如果用户未登录 中,完成服务的登录或注册流程。
生成访问令牌,以供 Google 用于访问您的 API。通过 访问令牌可以是任何字符串值,但必须唯一地表示 令牌对应的用户和客户端,且不得被猜到。
发送 HTTP 响应,将用户浏览器重定向到相应网址 由
redirect_uri
参数指定。添加所有 以下参数:access_token
:您刚刚生成的访问令牌token_type
:字符串bearer
state
:原始状态的未修改状态值 请求
以下是生成的网址示例:
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
处理 userinfo 请求
userinfo 端点是受 OAuth 2.0 保护的资源,会返回关联用户的声明。实现和托管 userinfo 端点是可选的,但以下用例除外:
从您的令牌端点成功检索到访问令牌后,Google 会向您的 userinfo 端点发送请求,以检索关联用户的基本个人资料信息。
userinfo 端点请求标头 | |
---|---|
Authorization header |
Bearer 类型的访问令牌。 |
例如,如果您的 userinfo 端点可通过
https://myservice.example.com/userinfo
时,请求可能如下所示:
GET /userinfo HTTP/1.1 Host: myservice.example.com Authorization: Bearer ACCESS_TOKEN
为了让 userinfo 端点能够处理请求,请执行以下步骤:
- 从 Authorization 标头中提取访问令牌,并返回与访问令牌相关联的用户的信息。
- 如果访问令牌无效,则使用
WWW-Authenticate
响应标头返回 HTTP 401 Unauthorized 错误。下面是一个 userinfo 错误响应示例:HTTP/1.1 401 Unauthorized WWW-Authenticate: error="invalid_token", error_description="The Access Token expired"
如果在关联过程中返回 401 未经授权错误或任何其他失败的错误响应,该错误将无法恢复,检索到的令牌将被舍弃,并且用户必须重新开始关联流程。 如果访问令牌有效,则返回 HTTPS 正文中包含以下 JSON 对象的 HTTP 200 响应 回复:
{ "sub": "USER_UUID", "email": "EMAIL_ADDRESS", "given_name": "FIRST_NAME", "family_name": "LAST_NAME", "name": "FULL_NAME", "picture": "PROFILE_PICTURE", }
如果您的 userinfo 端点返回 HTTP 200 成功响应,则系统会针对用户的 Google 账号注册检索到的令牌和声明。userinfo 端点响应 sub
系统中用于识别用户的唯一 ID。 email
用户的电子邮件地址。 given_name
可选:用户的名字。 family_name
可选:用户的姓氏。 name
可选:用户的全名。 picture
可选:用户的个人资料照片。
驗證實作
您可以使用 OAuth 2.0 Playground 工具驗證實作結果。
請在工具中按照下列步驟操作:
- 點選「Configuration」圖示 ,開啟 OAuth 2.0 設定視窗。
- 在「OAuth 流程」欄位中,選取「用戶端」。
- 在「OAuth 端點」欄位中,選取「自訂」。
- 在對應的欄位中指定 OAuth 2.0 端點,以及您指派給 Google 的用戶端 ID。
- 在「步驟 1」部分中,請勿選取任何 Google 範圍。請改為將這個欄位留空,或輸入有效的伺服器範圍 (如果您不使用 OAuth 範圍,則輸入任意字串)。完成後,按一下「授權 API」。
- 在「步驟 2」和「步驟 3」部分,請完成 OAuth 2.0 流程,並確認每個步驟都能正常運作。
您可以使用 Google 帳戶連結示範工具驗證實作成果。
在工具中執行下列步驟:
- 按一下「使用 Google 帳戶登入」按鈕。
- 選擇要連結的帳戶。
- 輸入服務 ID。
- 您可以選擇輸入一或多個要申請存取權的範圍。
- 按一下「開始試用」。
- 系統顯示提示時,請確認您可以同意或拒絕連結要求。
- 確認系統是否會將你重新導向至平台。