Unlinking accounts

Unlinking may be initiated from your platform or Google, and the display of a consistent link state on both provides the best user experience. Support for a token revocation endpoint or Cross-Account Protection is optional for Google Account Linking.

Accounts can become unlinked by any of the following:

  • User request from
  • Failure to renew an expired refresh token
  • Other events initiated by you or Google. For example, account suspension by abuse and threat detection services.

User requested unlinking from Google

Account unlinking initiated through a user's Google Account or app deletes any previously issued access and refresh tokens, removes user consent, and optionally calls your token revocation endpoint if you chose to implement one.

User requested unlinking from your platform

You should provide a mechanism for users to unlink, such as a URL to their account. If you don't offer a way for users to unlink, include a link to the Google Account so that the users can manage their linked account.

You can choose to implement Risk & Incident Sharing and Collaboration (RISC) and notify Google of changes to the users account linking status. This allows for an improved user experience where both your platform and Google show a current and consistent linking status without the need to rely on a refresh or access token request to update linking state.

Token expiration

To provide a smooth user experience and avoid service disruption, Google attempts to renew refresh tokens near the end of their lifetime. In some scenarios, user consent might be required to re-link accounts when a valid refresh token is unavailable.

Designing your platform to support multiple unexpired access and refresh tokens can minimize race conditions present in client-server exchanges between clustered environments, avoid user disruption, and minimize complex timing and error handling scenarios. While eventually consistent, both previous and newly issued unexpired tokens might be in use for a short period of time during the client-server token renewal exchange and prior to cluster synchronization. For example, a Google request to your service that uses the previous unexpired access token occurs just after you issue a new access token, but before receipt and cluster synchronization takes place at Google. Alternative security measures to Refresh Token Rotation are recommended.

Other events

Accounts can be unlinked due to various other reasons, such as inactivity, suspension, malicious behavior, and so forth. In such scenarios, your platform and Google can best manage user accounts and relink by notifying one another of changes to account and link state.

Implement a token revocation endpoint for Google to call, and notify Google of your token revocation events using RISC to ensure your platform and Google maintain consistent user account link state.

Token revocation endpoint

If you support an OAuth 2.0 token revocation endpoint, your platform can receive notifications from Google. This lets you inform users of link state changes, invalidate a token, and cleanup security credentials and authorization grants.

The request has the following form:

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

client_id=GOOGLE_CLIENT_ID&client_secret=GOOGLE_CLIENT_SECRET&token=TOKEN&token_type_hint=refresh_token

Your token revocation endpoint must be able to handle the following parameters:

Revocation endpoint parameters
client_id A string that identifies the request origin as Google. This string must be registered within your system as Google's unique identifier.
client_secret A secret string that you registered with Google for your service.
token The token to be revoked.
token_type_hint (Optional) The type of token being revoked, either an access_token or refresh_token. If unspecified, defaults to access_token.

Return a response when the token is deleted or invalid. See the following for an example:

HTTP/1.1 200 Success
Content-Type: application/json;charset=UTF-8

If the token can't be deleted for any reason, return a 503 response code, as shown in the following example:

HTTP/1.1 503 Service Unavailable
Content-Type: application/json;charset=UTF-8
Retry-After: HTTP-date / delay-seconds

Google retries the request later or as requested by Retry-After.

Cross-Account Protection (RISC)

如果您支持跨账号保护功能，您的平台可以在以下情况下通知 Google： 访问或刷新令牌会被撤消。这样，Google 就可以告知用户 更改关联状态、使令牌失效、清理安全凭据 授权。

跨账号保护以 RISC 标准是 OpenID Foundation。

安全事件令牌 用于通知 Google 令牌撤消。

解码后，令牌撤消事件如以下示例所示：

{
  "iss":"http://risc.example.com",
  "iat":1521068887,
  "aud":"google_account_linking",
  "jti":"101942095",
  "toe": "1508184602",
  "events": {
    "https://schemas.openid.net/secevent/oauth/event-type/token-revoked":{
      "subject_type": "oauth_token",
      "token_type": "refresh_token",
      "token_identifier_alg": "hash_SHA512_double",
      "token": "double SHA-512 hash value of token"
    }
  }
}

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

令牌撤消事件
iss Issuer Claim：这是由您托管的网址，并且会分享给 在注册过程中与 Google 联系。
aud 受众群体声明：这可将 Google 标识为 JWT 收件人。它 必须设置为 google_account_linking。
jti JWT ID 声明：这是您为每次 JWT 生成的唯一 ID 安全事件令牌
iat Issued At Claim：这是一个 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 网络令牌 (JWT)。