OAuth2.0 Token Introspection and Token Revocation

The Authorisation Server giveth, and it taketh away

3 min readJan 10, 2023

Audience

This article will require a solid understanding of HTTP and the OAuth2.0 core standard. For the latter you can read through my ordered list of articles found here.

In the following article we will explore two different RFCs:

Token introspection: If you remember, in the OAuth2.0 Core RFC, tokens are opaque — non-authorisation-server parties don’t know what’s in them! This RFC defines a method for contacting the authorisation server in order to access some access or refresh token information.
Token revocation: Sometimes we may want to invalidate an access or refresh token, perhaps it’s been compromised and malicious agents are using it. This RFC defines a method for doing so.

Argument

Let’s take them one at a time.

Token Introspection

As covered in the introduction, introspection is a method for clients to retrieve information on the opaque tokens they hold. So why might we need this?

One of the things that access tokens contain are scopes. Resource servers can use these scopes to decide whether or not a bearer of an access token should be allowed their resources.

However, if an access token is opaque, how do resource servers know what scopes it contains? Token introspection can be used for this, amongst other applications.

The information you can obtain is:

Whether or not the token has been revoked (is it active).
What access rights the token has (generally the scopes).
The ‘authorisation context’ of the token (including which client it belongs to and who authorised it).

The implementation is incredibly straightforward. There is a single, new endpoint that takes a parameter representing the access token. It also looks for a token hint, which can be provided to help speed up authorisation server lookup times.

The endpoint must have a way of authorising whoever calls it. This could mean needing an access token itself, or client secret. It then returns a JSON document containing the token information.

Note, we can change what this endpoint returns depending on the authorisation the client has (mentioned previously). For example, we may not want to tell a non-admin client a token has admin rights.

Token Revocation

This RFC covers the case where we have issued tokens and would like to stop their usage. By issuing a revoke request we invalidate a token and potentially any tokens based on the authorisation grant it was part of, as well as the grant itself.

Some of the most commonly used applications of revocation include:

Logging Out: If a user logs out they may still have access to their refresh token. We don’t want them to continue using this to get access and so must invalidate it!
Removing Authorization: Let’s take the example of having given a third-party app access to our Google information. Sometimes we may want to remove that access. In this case we would want to remove the access and refresh tokens given to that app.
Token Compromise: If someone gets hold of our access tokens this is problematic, but they should expire quickly. However, if someone gets hold of our refresh token we’re in trouble. We need a way of marking it as compromised.

An example of a third party app that has been given access to a Google account, as well as the button used to invalidate their tokens.

The first thing to note is that OAuth2.0 implementations must allow you to revoke refresh tokens, but revoking access tokens is optional.

To request revocation we send two things in the request body:

The token: The access or refresh token
The token type hint: This is optional and can either be access_token or refresh_token depending on which token you are sending.

The request must also be authenticated (so we know who is sending the revocation).

From here it is the responsibility of the Authorisation Server to invalidate the access and refresh tokens such that they no longer work.

Conclusion

In conclusion, we have covered how to revoke a token and how to learn more about it!