OAuth Revoke Flow
On this page
Access tokens and refresh tokens expire at some point in time. Access tokens tend to expire quickly, whereas refresh tokens last longer. Their validity period is set when created. The period for which they are valid depends on factors such as:
- How the user authenticated and when.
- The client application that was used.
- The scopes that the user delegated.
The authorization server may also consider other contextual information when setting the duration of validity time for tokens. When a token should expire before this time, it should be revoked.
How Token Revocation Works
RFC 7009 defines an API for revoking tokens at the authorization server. It introduces a dedicated endpoint, the token revocation endpoint, as well as the request and response for the protocol. The following diagram illustrates the flow.
Revoke Endpoint
- The client sends the token that it wishes to revoke in a POST request along with its credentials to the token revocation endpoint at the authorization server.
- The server validates the request, revokes the token, and responds with an empty body using the HTTP status code 200.
The client can provide a "hint" about the kind of token in the request using the request parameter token_type_hint. The defined values for the hint are access_token or refresh_token.
The authorization server ignores any unknown hints and tries to revoke the token in any case. A hint may simply speed up the request slightly.
Client Authentication
The client authenticates as part of the token request. There are many ways for a client to authenticate. The most common being client secret. The Curity Identity Server supports the following authentication mechanisms for clients:
- No authentication (public client)
- Secret in POST body
- Secret using Basic Authentication
- Client Assertion JWT
- Mutual TLS (mTLS) client certificate
- Asymmetric Key
- Symmetric Key
- Credential Manager
- JWKS URI
Revoking tokens
When implementing revocation, it's important to understand the token hierarchy, because revocation has different effects depending on the type of the revoked token.
Revoking Opaque Access Tokens
Opaque access tokens become inactive at the moment of revocation because APIs rely on the authorization server to provide the validity status for such tokens which in turn can reflect any status updates immediately in its responses. However, if a corresponding refresh token is still live, the authorization server may continue to issue new access tokens for the client without additional user interaction.
Revoking JWT Access Tokens
JSON Web Tokens (JWTs) are by-value tokens. This means that all identity data and metadata such as the expiration time are part of the token. APIs typically accept a valid JWT until it expires without checking any validity status with the authorization server. Consequently, they do not receive any token status updates and continue to accept access tokens that have been revoked.
APIs must not operate on revoked tokens. When using by-value tokens like JWTs, you need a mechanism of some sort to prevent APIs from accepting or receiving revoked tokens. There are two general approaches for such a mechanism:
- Notify back-end APIs about revoked JWTs. For example, monitor revoked token events at the authorization server to trigger a notification mechanism for the APIs.
- Use the phantom token pattern and, if necessary, notify the API gateway about revoked tokens. In this way, APIs receive only valid JWT access tokens, as the API gateway can filter out requests with invalid tokens.
At Curity, we recommend the phantom token flow to combine the benefits of both opaque and JWT access tokens.
Revoking Refresh Tokens
When the authorization server revokes an access token, that token becomes invalid and clients cannot use it anymore. A revoked access token does not necessarily revoke the client's ability to operate on the user's behalf because the client may have a refresh token with which it can obtain new access tokens. To actually disrupt any access from the client, it is necessary to revoke the refresh token.
A refresh token relates to a delegation. A delegation is an abstraction that represents the user's consent to the application operating on their behalf. It is the root of all tokens. The following figure illustrates the token hierarchy.
When revoking an active refresh token, the authorization server revokes the corresponding delegation and all related access tokens. This ultimately results in the application not being able to operate on the user's behalf anymore. The client needs to start a new OAuth flow to create a new delegation and retrieve a new set of access tokens for the user to continue its operations.
The Revoke Request
Request Parameters
- Method:
POST - Content-Type:
application/x-www-form-urlencoded - Response Type:
json
| Parameter | Value | Mandatory | Description |
|---|---|---|---|
| client_id | The client ID | yes | The ID of the requesting client. |
| client_secret | The client secret | yes* | The secret of the client. *Mandatory if client authentication is of type secret, and the authentication is not done using basic authentication. |
| token_type_hint | access_token or refresh_token | no | Can be sent to inform the server of the type of token; if not sent, the server will attempt to figure out the token type. |
| token | A token | yes | The token to revoke. |
Response
The response is very simple: it's always an HTTP 200 if the token is revoked or otherwise invalid. In such a situation, the client should disregard the body of the response.
If the authorization server responds with any other HTTP status code, the client needs to assume that it did not revoke the token.
Conclusion
Revocation is a simple API that can be used to revoke tokens and delegations (the root of all tokens). By promptly revoking tokens that are no longer needed or have been compromised, you can prevent unauthorized access to protected resources. It's essential to handle both access token and refresh token revocation appropriately. For instance, when a user logs out or changes their credentials, the associated tokens should be revoked to ensure continued security. By-value tokens, like JWTs, can be revoked, but clients may continue using them, unaware of their cancellation; to avoid this, consider phantom tokens.
Jacob Ideskog
Identity Specialist and CTO at Curity
Join our Newsletter
Get the latest on identity management, API Security and authentication straight to your inbox.
Start Free Trial
Try the Curity Identity Server for Free. Get up and running in 10 minutes.
Start Free Trial
