OAuth 2.0 Token Revocation
Extracted elements (23)
Access tokens may be self-contained (resource server needs no authorization server interaction) or handle-based (resource server must query authorization server). Immediate revocation of self-contained tokens requires non-standardized backend interaction, making short-lived access tokens a practical alternative.
Clients relying on JSONP should be aware that a malicious revocation endpoint may attempt to inject malicious code into the client, since JSONP executes a JavaScript callback from the server response.
Invalid tokens do not cause an error response because the client cannot handle such an error in a reasonable way, and the purpose of the revocation request — invalidating the token — is already achieved by the time an invalid token is presented.
A client compliant with RFC 6749 must be prepared to handle unexpected token invalidation at any time, independent of this revocation mechanism. Different server policies on cascading token revocation do not pose interoperability problems.
After the authorization server returns HTTP 200, the token is immediately invalidated and clients must not try to use it again. Implementations should minimize any propagation delay window.
If the revoked token is a refresh token and the authorization server supports access token revocation, it SHOULD also invalidate all access tokens based on the same authorization grant. If an access token is revoked, the server MAY revoke the respective refresh token as well.
If the server responds with HTTP 503, the client must assume the token still exists and may retry after a reasonable delay. The server may include a 'Retry-After' header to indicate unavailability duration.
If the token revocation endpoint host is also reachable over HTTP, the server SHOULD offer a revocation service at the corresponding HTTP URI but MUST NOT publish it as a token revocation endpoint, ensuring accidentally HTTP-sent tokens are revoked.
Implementations MUST support the revocation of refresh tokens and SHOULD support the revocation of access tokens.
The token revocation endpoint URL MUST conform to the rules given in RFC 6749 Section 3.1, and clients MUST verify that the URL is an HTTPS URL.
URLs for token revocation endpoints MUST be HTTPS URLs, and the authorization server MUST use TLS in a version compliant with RFC 6749 Section 1.6, because requests transmit plaintext credentials.
A new error code 'unsupported_token_type' is defined for the revocation endpoint, returned when the authorization server does not support revocation of the presented token type (e.g., access token revocation not supported).
The authorization server responds with HTTP status code 200 for both successful revocation and for invalid (unknown or already-expired) tokens. The response body content is ignored by the client.
The revocation endpoint accepts HTTP POST requests with an 'application/x-www-form-urlencoded' body containing a REQUIRED 'token' parameter and an OPTIONAL 'token_type_hint' parameter. Client authentication credentials are also included as described in RFC 6749 Section 2.3.
The revocation endpoint MAY support CORS for use with user-agent-based applications, and MAY also offer JSONP for legacy user-agents via GET requests with an optional 'callback' parameter naming a JavaScript function.
The 'token_type_hint' parameter is an optional hint to help the authorization server optimize token lookup. If the server cannot locate the token using the given hint, it MUST extend its search across all supported token types; it MAY ignore this parameter entirely.
This specification establishes the 'OAuth Token Type Hints' registry with Specification Required policy, with initial values 'access_token' and 'refresh_token'. New values are reviewed on [email protected] for two weeks before registration.
This specification registers the 'unsupported_token_type' error value in the IANA 'OAuth Extensions Error Registry' defined in RFC 6749, for use at the revocation endpoint error response.
A malicious client attempting to guess valid tokens via revocation requests is constrained because the request must include valid client credentials and the token must belong to the requesting client. Successful guessing would allow worse abuse than revocation, limiting the incremental risk.
Cleaning up tokens via revocation contributes to overall security and privacy by reducing the likelihood of abuse of abandoned tokens, and prevents valid authorization grants from persisting without the end-user's awareness.
Clients MUST obtain the revocation endpoint location from a trustworthy source only, and MUST authenticate the endpoint (certificate validation, etc.) to prevent attackers from capturing valid tokens via a counterfeit revocation endpoint.
If the authorization server does not support access token revocation, access tokens will not be immediately invalidated when the corresponding refresh token is revoked. Deployments must account for this gap in their security risk analysis.
Malicious clients could attempt denial-of-service attacks against the revocation endpoint; countermeasures MUST be applied, equivalent to those for the token endpoint. Invalid token_type_hint values can cause additional database lookups, so care MUST be taken to prevent exploitation for DoS.