帐号使用行业标准的 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=1&hl=ca)
要求
- 您必须告知用户该用户帐号将与 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=1&hl=ca)
创建项目
如需创建项目以使用帐号关联,请按以下步骤操作:
- 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 同意屏幕”页面上,填写表单,然后点击“保存”按钮。
应用名称:请求用户同意的应用的名称。该名称应准确反映您的应用,并与用户在别处看到的应用名称保持一致。应用名称将显示在帐号关联同意屏幕上。
应用徽标:同意屏幕上的图片,有助于用户识别您的应用。徽标会显示在帐号关联同意屏幕和帐号设置中
支持电子邮件地址:供用户就其同意情况与您联系。
Google API 的范围:范围允许您的应用访问用户的私有 Google 数据。对于 Google 帐号关联用例,默认范围(电子邮件、个人资料、OpenID)就足够了,您无需添加任何敏感范围。最佳做法一般是在需要访问时逐步请求作用域,而不是预先请求。了解详情。
已获授权的网域:为保护您和您的用户,Google 仅允许使用 OAuth 进行身份验证的应用使用已获授权的网域。您应用的链接必须托管在已获授权的网域上。了解详情。
应用首页链接:您的应用的首页。必须托管在已获授权的网域上。
应用隐私权政策链接:在 Google 帐号关联同意屏幕上显示。必须托管在已获授权的网域上。
应用服务条款链接(可选):必须托管在已获授权的网域上。
图 1. 一款虚构应用 Tunery 的 Google 帐号关联同意屏幕
查看“验证状态”。如果您的申请需要验证,请点击“提交验证”按钮,提交您的申请。如需了解详情,请参阅 OAuth 验证要求。
实现 OAuth 服务器
授权代码流程的 OAuth 2.0 服务器实现包括 两个端点,您的服务会通过 HTTPS 提供这两个端点。第一个端点 是授权端点,负责查找或获取 就数据访问征求用户意见。授权端点会提供一个 尚未登录的用户的登录界面,并记录同意情况 请求的访问权限。第二个端点是令牌交换端点, 用于获取加密字符串(称为令牌),以授权用户 访问您的服务。
当 Google 应用需要调用您的某个服务的 API 时,Google 会使用 将这些端点组合在一起,以获取用户调用这些 API 的权限 。
由 Google 发起的 OAuth 2.0 授权代码流程会话包含 以下流程:
- Google 会在用户的浏览器中打开您的授权端点。如果流 在用户通过纯语音设备上针对某个 Action 启动,Google 会将 将代码执行到手机上
- 用户登录(如果尚未登录),并授予 Google 以下权限: 访问您的 API 访问其数据(如果尚未授权)。
- 您的服务会创建授权代码并将其返回给 Google。待办事项 因此,请使用授权代码将用户的浏览器重定向回 Google。 附件。
- Google 会将授权代码发送到您的令牌交换端点, 验证代码的真实性并返回访问令牌和 刷新令牌。访问令牌是一个短期有效的令牌 作为访问 API 的凭据。刷新令牌长期有效 Google 可以存储该令牌,以便在用户首次访问该令牌时, 过期。
- 在用户完成账号关联流程后, 从 Google 发送的请求中包含访问令牌。
处理授权请求
需要使用 OAuth 2.0 授权代码执行账号关联的情况 流程中,Google 会通过请求将用户发送到您的授权端点 包含以下参数:
授权端点参数 | |
---|---|
client_id |
您分配给 Google 的客户 ID。 |
redirect_uri |
此请求的响应发送到的网址。 |
state |
将一个在 重定向 URI。 |
scope |
可选:一组以空格分隔的范围字符串,用于指定 Google 请求授权的数据 |
response_type |
要在响应中返回的值的类型。对于 OAuth 2.0
授权代码流程中,响应类型始终为 code 。
|
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&scope=REQUESTED_SCOPES&response_type=code&user_locale=LOCALE
为了让授权端点能够处理登录请求,请执行以下操作 步骤:
- 验证
client_id
是否与您分配给 Google 的 Client ID 匹配,以及redirect_uri
与 Google 为您的服务提供的重定向网址是否匹配。这些检查对于防止 访问意外或配置错误的客户端应用。如果你支持多种 OAuth 2.0 流程,还应确认response_type
是否为code
。 - 检查用户是否已登录您的服务。如果用户没有登录, 完成服务的登录或注册流程。
- 生成授权代码,以供 Google 用于访问您的 API。 授权代码可以是任何字符串值,但它必须是唯一的 代表用户、令牌对应的客户端以及代码的有效期 而且不可猜测出来。您通常需要进行授权 会在大约 10 分钟后过期。
- 确认
redirect_uri
参数指定的网址包含 以下表单:https://oauth-redirect.googleusercontent.com/r/YOUR_PROJECT_ID https://oauth-redirect-sandbox.googleusercontent.com/r/YOUR_PROJECT_ID
- 将用户的浏览器重定向到
redirect_uri
参数。添加您在 以及您在重定向时返回未经修改的原始状态值 方法是附加code
和state
参数。以下是 生成的网址示例: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_code 或 refresh_token 。 |
code |
如果值为 grant_type=authorization_code ,则此参数为
Google 通过您的登录或令牌交换收到的代码
端点。 |
redirect_uri |
如果值为 grant_type=authorization_code ,则此参数为
初始授权请求中使用的网址。 |
refresh_token |
如果值为 grant_type=refresh_token ,则此参数为
刷新令牌 Google 从您的令牌交换端点收到的令牌。 |
交换访问令牌和刷新令牌的授权代码
用户登录且您的授权端点返回一个短期有效的 授权代码发送给 Google,Google 会向您的令牌交换发送请求 端点使用授权代码交换访问令牌和刷新 令牌。
对于这些请求,grant_type
的值为 authorization_code
,
的 code
值是您先前授予的授权代码的值
。以下是发送
访问令牌和刷新令牌的授权代码:
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
请求:
步骤:
- 验证
client_id
是否将请求来源标识为已获授权的请求来源 来源,并且client_secret
与预期值匹配。 - 请确认授权代码有效且未过期, 请求中指定的客户端 ID 与 授权代码。
- 确认
redirect_uri
参数指定的网址完全相同 初始授权请求中使用的值。 - 如果您无法验证上述所有条件,则返回 HTTP
正文为
{"error": "invalid_grant"}
的 400 Bad Request 错误。 - 否则,使用授权代码中的用户 ID 来生成刷新 令牌和访问令牌。这些标记可以是任何字符串值, 必须唯一地代表用户和令牌对应的客户端, 不得被猜到对于访问令牌,请记录 令牌,通常是在您发出令牌一个小时后。 刷新令牌不会过期。
- 在 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
请求:
- 验证
client_id
是否将请求来源标识为 Google,并client_secret
与预期值一致。 - 请确认刷新令牌有效,以及在 请求与刷新令牌所关联的客户端 ID 相匹配。
- 如果您无法验证上述所有条件,则返回 HTTP 400
正文为
{"error": "invalid_grant"}
的 Bad Request 错误。 - 否则,请使用刷新令牌中的用户 ID 来生成访问权限 令牌。这些标记可以是任何字符串值,但它们必须是唯一的 代表用户和客户端,而不得 猜测。对于访问令牌,请记录令牌的到期时间, 通常在您发出令牌一小时后发送
- 在 HTTPS 的正文中返回以下 JSON 对象
回答:
{ "token_type": "不记名", "access_token": "ACCESS_TOKEN", “expires_in”:SECONDS_TO_EXPIRATION }
处理 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游乐场工具。
在工具中,执行以下步骤:
- 单击配置 打开的OAuth 2.0配置窗口。
- 在OAuth流场中,选择客户端。
- 在OAuth端点字段中,选择自定义。
- 在相应字段中指定您的 OAuth 2.0 端点和您分配给 Google 的客户端 ID。
- 在步骤1部分,不要选择任何谷歌范围。相反,将此字段留空或键入对您的服务器有效的范围(如果不使用 OAuth 范围,则输入任意字符串)。当您完成后,单击授权的API。
- 在步骤2和步骤3段,完成OAuth 2.0流程和验证每个步骤按预期工作。
您可以通过验证您的实现谷歌帐户链接演示工具。
在工具中,执行以下步骤:
- 点击登录在与谷歌按钮。
- 选择您要关联的帐户。
- 输入服务标识。
- (可选)输入您将请求访问的一个或多个范围。
- 单击开始演示。
- 出现提示时,确认您可以同意并拒绝链接请求。
- 确认您被重定向到您的平台。