Overview#OAuth 2.0 Token Revocation is a Revocation model defined in RFC 7009
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.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:
- credentials - The client also includes its authentication credentials as described in Section 2.3. of RFC 6749.
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.