Access Denied: Token Revocation
Have you ever had a notification about a suspicious login attempt from a digital destination you’ve never been to? Hopefully it came with the option to say it wasn’t you, allowing you to deny access to that specific place and rebuff the user trying to sneak into your account or information. If so, you probably have token revocation to thank for the security measure.
Token revocation means a token is no longer able to be used for access to a protected digital place, and it’s often behind the scenes in the denying process. It’s similar to session revocation in that you’re blocking access at some level, but there’s a key difference. With session revocation, you can deny one or more sessions and still access protected information. But token revocation is more permanent because it “kills” the token that might otherwise be reused for the duration of the token’s lifetime.
Tokens play a big role in OAuth 2.0, which is designed to protect resources from wandering or malicious hands by using tokens to securely authorize users. You could build your own method of verifying access tokens and get a decent way there with open source packages, but a ready-made solution—token introspection—is easy to use and gives you the ability to offload the work from the app team to the identity platform’s team. PingOne for Customers handles the messy job of building a token verification system by giving you an API endpoint that does the work for you on our backend. In this blog post, I’ll walk you through how to use token revocation in PingOne for Customers.
What Is Token Revocation?
In a previous post, we discussed token introspection as a means for verifying the validity of an access or ID token in order to gain access to a protected resource in an OAuth 2.0 schema. Before digging into token revocation, let’s revisit the analogy from the previous post:
“The idea behind token introspection is that a special key will be required to access the protected resource, and that key is only given to those that the original owner explicitly authorizes. You can think of it like owning an apartment for lease. You (the resource owner) want to keep squatters out and protect the stuff inside the apartment, so you put a lock on the door and require a key to get in."
“In this analogy, the apartment is the resource server. It houses the resource and protects it by allowing only those with legitimate access rights (rental agents, potential renters, trusted friends, etc.) to enter via a key. And to obtain that key, a person has to go through a process of applying for it.”
Using this analogy, you can think about token revocation as a means to change the locks on the door to the apartment. While access and ID tokens have expiration times (which can be configured based on your preferences/needs), chances are you will need a mechanism to immediately terminate the validity of a compromised token.
How to Revoke a Token in PingOne for Customers
In the example I’m about to walk you through, first we need to obtain an access or ID token. To do so, we follow the same steps as in the previous article and create a single page OIDC application that has been configured for an auth code grant type. Auth code is a common grant type used by confidential and public clients to exchange an authorization code for an access token or ID token.
Using our auth code obtained from the application, we exchange the auth code for an access and ID token using the token (auth code) endpoint found in the Ping Postman collection. Once we have both tokens, we introspect both tokens using the introspection endpoint, also found in the Ping Postman collection.
To start, we first need to configure a new application. We begin by navigating to the Connections tab in the PingOne for Customers admin console and then creating our app connection.
IMPORTANT NOTE: When configuring the redirection URL, it must be formatted as https://
For demonstration purposes, let’s include a static attribute that can be customized to our ID token based on our company’s needs. While introspection will not return this attribute in the introspection response—since the endpoint only returns PingOne attributes—I will demonstrate that the attribute does exist in the ID token.
Now that we’ve created our Single Page Application, we need to enable our application by clicking the slider to the green position found on the right side of the application. From there, we need to edit our application to permit the auth code grant type. To do so, we expand the application and select the pencil icon on the right side of the application.
Now that we have an application, the next step is to create a user to sign into our application. We begin by navigating to the identities tab, selecting Add User, and filling out the information form. Username is the only required attribute, but we are free to add any other extraneous information.
We make sure to enable this using the same slider as performed before (two steps above) for the newly created application. Now we select Reset Password and provide a one-time password, which will be used when first signing in and will allow us to set a permanent password for this user.
We are now ready to obtain our auth code from our application. To do so, we emulate the URL that is contacted by an application attempting to obtain an auth code. We replace the attributes of the URL below with our own application’s details and input it into a new web browser tab.
After logging in, we can find our auth code in the URL of our redirected URL. We copy this value, as it will be used to exchange the code for our access and ID token.
Now that we have the auth code, we can exchange it in the Postman collection for an ID and access token. During our application’s configuration, we had set the token authorization method to none. Since authorization is not required in the authorization tab of this Postman endpoint, we set authorization to No Auth. In addition to this, we need to configure other required attributes for the exchange.
At long last, we are just about ready for revocation! But before that, let’s copy the token returned from the auth code exchange body and input it into our request body for introspection before and after revocation.
Now that we have verified validity of our tokens, let’s terminate them using revocation.
A successful revocation will return an empty response body and 200 HTTP code.
Lastly, we can confirm that the token is no longer active and revocation has been successful!
That’s it: you’ve seen how to revoke a token with PingOne for Customers. And if you want to try this out for yourself, sign up for a free trial today.
