Google Account Linking API

此参考页面记录了您的应用在基于 OAuth 的账号关联过程中使用的 Google 提供的端点和接口。

前提条件和标准

如需成功与这些 Google 端点互动，您的集成必须遵循以下标准：

  • OAuth 2.0：符合 RFC 6749。
  • JSON Web 令牌 (JWT)：符合 RFC 7519（适用于简化关联和 RISC）。
  • 安全事件令牌：符合 RFC 8417（适用于 RISC）。
  • HTTPS：所有请求都必须通过安全的 HTTPS 连接发出。

OAuth 重定向 URI

在成功完成身份验证和征得用户同意后，您的服务会将用户的浏览器重定向到的端点。YOUR_PROJECT_ID 路径形参是您在注册期间配置的 ID。

  • 网址： https://oauth-redirect.googleusercontent.com/r/YOUR_PROJECT_ID

  • 沙盒网址： https://oauth-redirect-sandbox.googleusercontent.com/r/YOUR_PROJECT_ID

  • 方法： GET（使用浏览器重定向）

请求参数

将用户重定向回 Google 时，必须将参数附加到网址。这些参数的格式可以是查询字符串（授权码流程），也可以是网址片段（隐式流程），具体取决于所用的 OAuth 流程。

参数 说明
code （授权代码流程必需）由您的服务生成的授权代码。
state （必需）最初从 Google 收到的未修改状态值。
access_token （隐式流程必需）由您的服务生成的长期有效的访问令牌。
token_type （隐式流程必需）必须为 bearer。

错误响应

如果对 OAuth 重定向 URI 的请求格式有误，您会收到 HTTP 400 Bad Request 错误。响应正文将包含一个具有以下结构的 JSON 对象：

字段 说明
sendPostBody 确定 JS 是否应使用 POST 重定向到 redirectUri。在此场景中，通常为 false。
errorMessage 无法完成重定向时要向客户端显示的错误消息。对于缺失的 fragment，此值为 "A URI fragment or query string must be set."

OAuth 2.0 错误响应

如果用户拒绝授予同意权限，或者您的服务遇到错误，您的服务必须使用标准 OAuth 2.0 错误参数（例如 error=access_denied）将用户重定向回 OAuth 重定向 URI。Google 会处理这些参数，并向用户显示相应的错误界面。

RISC API（可选）

当用户使用 RISC 协议在您的平台上取消关联其账号时，您的服务会使用此端点主动通知 Google，确保两个平台保持同步。

  • 网址： https://risc.googleapis.com/v1/events:publish
  • 方法：POST
  • 身份验证：需要具有相应权限的 Google 服务账号令牌。
  • Content-Type： application/json

安全性事件令牌声明

您用于向 Google 通知令牌撤消事件的安全事件令牌必须符合下表中的要求：

声明 说明
iss 颁发者声明：这是您托管的网址，在注册期间会与 Google 共享。
aud 受众群体声明：用于将 Google 标识为 JWT 接收者。必须将其设置为 google_account_linking。
jti JWT ID 声明：这是您为每个安全性事件令牌生成的唯一 ID。
iat 签发时间声明：这是一个 NumericDate 值，表示创建相应安全性事件令牌的时间。
toe 活动声明时间：这是一个可选的 NumericDate 值，表示令牌被撤消的时间。
exp 过期时间声明：请勿添加此字段，因为导致此通知的事件已发生。
events 安全性事件声明：这是一个 JSON 对象，必须仅包含一个令牌撤消事件，其中包含以下字段：

  • subject_type：必须设为 oauth_token。
  • token_type：要撤消的令牌的类型，即 access_token 或 refresh_token。
  • token_identifier_alg：这是用于对令牌进行编码的算法，必须为 hash_SHA512_double。
  • token：这是已撤消令牌的 ID。

如需详细了解字段类型和格式，请参阅 JSON Web 令牌 (JWT)

App Flip“翻回”界面

对于App Flip，您的移动应用必须将授权代码或访问令牌返回给 Google 应用。

Android（Intent 结果）

您的应用是通过 intent 打开的。获得同意后，该服务会完成操作并将结果返回给 Google。如需了解详情，请参阅 Android 实现指南。

  • 操作： com.google.android.gms.auth.CODE_AVAILABLE
  • 其他： code、state、access_token、token_type。

您的应用使用自定义网址协议或 HTTPS 通用链接打开 Google。如需了解详情，请参阅 iOS 实现指南。

  • 格式： <return_url>?code=AUTHORIZATION_CODE&state=STATE_STRING