OAuth 2.0 Token Revocation


OAuth 2.0 Token Revocation is a Revocation model defined in RFC 7009

The OAuth 2.0 core specification RFC 6749 defines several ways for a OAuth Client to obtain Refresh Token and Access Token.

OAuth 2.0 Token Revocation specification supplements the core specification with a mechanism to revoke both types of tokens. A token is a string representing an authorization grant issued by the resource Owner to the OAuth Client. A revocation request will invalidate the actual token and, if applicable, other tokens based on the same Authorization Grant and the Authorization Grant itself.

From an End-User's perspective, OAuth 2.0 is often used to log into a certain site or application. This revocation mechanism allows a OAuth Client to invalidate its tokens if the End-User (Resource Owner) logs out, changes Digital Identity, or uninstalls the respective application. Notifying the Authorization Server that the token is no longer needed allows the Authorization Server to clean up data associated with that token (e.g., session data) and the underlying Authorization Grant.

This behavior prevents a situation in which there is still a valid Authorization Grant for a particular OAuth Client of which the end-user is not aware. This way, token revocation prevents abuse of abandoned tokens and facilitates a better end-user experience since invalidated Authorization Grants will no longer turn up in a list of Authorization Grants the authorization server might present to the end-user.

RFC 7009 2.1. Revocation Request#

The OAuth Client constructs the Revocation Request by including the following parameters using the "application/x-www-form-urlencoded" format in the HTTP Request entity-body:
  • token - REQUIRED - The token that the client wants to get revoked.
  • token_type_hint - OPTIONAL A hint about the type of the token submitted for revocation. Clients MAY pass this parameter in order to help the Authorization Server to optimize the token lookup. If the server is unable to locate the token using the given hint, it MUST extend its search across all of its supported token types. An Authorization Server MAY ignore this parameter, particularly if it is able to detect the token type automatically. This specification defines two such values:
    • access_token: An access token as defined in RFC 6749, Section 1.4
    • refresh_token: A refresh token as defined in RFC 6749, Section 1.5
    • Specific implementations, profiles, and extensions of this specification MAY define other values for this parameter using the registry defined in Section 4.1.2.
  • credentials - The client also includes its authentication credentials as described in Section 2.3. of RFC 6749.

RFC 7009 2.2. Revocation Response#

The Authorization Server responds with HTTP Status Code 200 if the token has been revoked successfully or if the client submitted an invalid token.

Note: invalid tokens do not cause an error response since the client cannot handle such an error in a reasonable way. Moreover, the purpose of the revocation request, invalidating the particular token, is already achieved.

The content of the response body is ignored by the client as all necessary information is conveyed in the response code.

An invalid token type hint value is ignored by the authorization server and does not influence the revocation response.

RFC 7009 2.2.1. OAuth 2.0 Token Revocation OAuth Error Response#

The error presentation conforms to the definition in Section 5.2 of RFC 6749. The following additional error code is defined for the Revocation_endpoint:
  • unsupported_token_type: The authorization server does not support the revocation of the presented token type. That is, the client tried to revoke an access token on a server not supporting this feature.
  • HTTP 503 - If the server responds with HTTP status code 503, the client must assume the token still exists and may retry after a reasonable delay. The server may include a "Retry-After" header in the response to indicate how long the service is expected to be unavailable to the requesting client.

More Information#

There might be more information for this subject on one of the following: