Token Introspection with PingOne for Customers

OAuth 2.0 is designed to protect resources from wandering or malicious hands by using tokens to securely authorize users. You could decide to build your own method of verifying access tokens and get a decent way there with open source packages, but token introspection provides ease of use and the ability to offload the work from the app team to the identity platform’s team. PingOne for Customers takes the messy work of building a token verification system by giving you an API endpoint that does the work for you on our backend.

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. 

Much of the security provided by OAuth 2.0 is in the process of getting that key, or token as it’s referred to in OAuth. The resource server plays the role of protector by guarding the information you’re trying to restrict access to and denying access to those without that special key. And before a user can be granted access to a restricted resource, the resource server needs some way to verify the validity of the user’s token. 

In implementation, this is done through an introspection endpoint, which is called in the resource server each time an attempt is made to access the protected resource. After successful processing, this endpoint will return a successful HTML response code of 200 along with a response body composed of information about the token to be used by the resource server. This successful response guarantees the token’s validity.

In our example, we will create a single page OIDC application that has been configured for an auth code grant type. Auth code is a commonly used 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 will do just this and 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 will 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 creating 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 in 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 will 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.

We are now prompted with a login screen. We log into our newly created user using our user’s username and temporary password created earlier.

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, introspection! We simply copy the token returned from the auth code exchange body and input it into our request body.

Finally, let’s recall our custom static attribute we configured in our application earlier. As you saw above the introspection response only returned PingOne for Customers token attributes, but when we decode the JWT token using a custom script, we can see that this attribute does exist within the ID token. JWT token decoders can be found online, including ours, to do the same work as a custom script.

That’s it: you’ve seen how we successfully introspected a token with PingOne for Customers. And if you want to try this out for yourself, sign up for a free trial today!