How to Validate a JWT Access Token (2024)

1. Home >
2. Validate a JWT Access Token >
3. Tools >
4. How to Validate a JWT Access Token

In a world where single-page apps (SPAs) and APIs are becoming increasingly popular, authorization is becoming increasinglydifficult.

In the past, developers commonly handled API authorization via API keys. API callers would send the API key with each request, and the API receiving the request would look up the key to ensure the caller had permission to access the resource they hadrequested.

API keys have disadvantages,however.

First, they’re vulnerable to data breaches. They typically don’t expire, so attackers can fraudulently use stolen API keys to accessAPIs.

Even worse, API key compromises often occur even without a known data breach. If they’re sent as part of an unencrypted HTTP request — or obtained via a Man-in-the-middle attack on an HTTPS request — an attacker can obtain a copy of the key without anyone realizingit.

Also, API keys usually require extra database lookups. When an API receives a request with an API key, it must load the user and roles associated with the key and ensure the user has permission to access the requestedresource.

There must be a betterway.

A Note on API AuthorizationServers

You can configure an OIDC app to behave as a simple authorization (“authz”) and authentication (“authn”) mechanism, allowing your application access to standard identity information, but you can also connect any OIDC app to an API Authorization Server configuration. This allows greater control over the content of the access tokensthemselves.

When appropriate we will call out any differences you might see when an access token is requested in a basic OIDC flow versus in a flow against an API Authorization Server-enabled OIDCapp.

JSON WebTokens

JSON Web Tokens (JWTs) are one solution to the drawbacks of API keys. JWTs offer a standardized way of securely storing and sharing data in JSON format. Each JWT is cryptographically signed, so it’s easy to verify that it is legitimate. An API user can’t just make up their own JWT and use it to access the API because that user won’t have access to the secret key used to generate the correct JWTsignature.

JWTs contain threeparts:

• header
• payload
• signature

Each piece of the JWT is base-64 encoded separately, and then all three elements are joined by a dot to form a single string. A token’s payload contains a JSON object, and each of the object’s properties is called aclaim.

While you can roll your own JWT generation and verification infrastructure, it’s usually best to leave security to the experts. That’s where OneLogin comes in. OneLogin is a cloud-based identity and access provider that can handle all of your application’s authentication needs - including generating JWTs and verifying theirsignatures.

But even when a JWT’s signature is valid, it’s still important to perform additional validation to ensure that the token isn’t expired and grants access to the requestedresource(s).

This article will examine the steps needed to validate a OneLogin JWT access token inNode.js.

Obtaining a JWT withOneLogin

Before we can validate a JWT, we must first obtain a JWT. Fortunately, OneLogin makes thateasy.

In a typical application, users will authenticate with OneLogin and receive a JWT that grants them access to your API. To keep things simple, we’re going to use OneLogin’s Node.js sample code as a base. This approach simulates the way we’d use JWTs in a real-world webapplication.

Start by creating an OpenID Connect (OIDC) application in the OneLogin portal. To get the code up and running, follow the instructions on this page, with a couple of smallchanges:

• After creating the OIDC application, set the callback URI tohttp://localhost:3000/oauth/callback.
• In the .env file of the Node.js project, set the SUBDOMAIN variable to match the subdomain you chose when you created your OneLoginaccount.

Note that our application is using the standard OIDC Authorization Code flow to obtain an access token. While this flow is very secure, it requires your OIDC application’s client secret, so you can only use it when you’re working on a web application with a back end you control. If you’re working with an app where you don’t control the back end, you should instead use the Implicit flow (for web apps) or Authorization code with PKCE (for native desktop and mobile apps) to obtain an accesstoken.

Next, run npm install to download all of the project’sdependencies.

The project you’ve just set up is a straightforward Express.js application that uses Passport.js to integrate with OneLogin OpenID applications. To see it in action, run npm run start from the project directory. Then, open http://localhost:3000 in a web browser. You’ll see an application that lets you log in usingOneLogin:

After login, you’ll see a simple mainmenu:

We’re going to add a token page under the users route to make it easy to acquire and inspect a JWTtoken.

Let’s begin by adding a new route toroutes/users.js:

router.get('/token', function(req, res, next) {});

To inspect a JWT token, we must first obtain one. Fortunately, OneLogin’s sample app provides it. Once a user has logged in to the Express app, it stores a copy of the access token weneed.

We can access it inside any Express request via the req.session.accessToken variable. We must send the access token to the OneLogin OIDC app’s introspection endpoint to validate thetoken.

If the token is valid, the introspection endpoint will respond with an HTTP 200 response code. The body of the response will also contain an augmented version of the original JWT token’spayload.

To start the validation process, add the following code inside the route function we create above in the users.jsfile:

request.post( `https://${ process.env.SUBDOMAIN }.onelogin.com/oidc/2/token/introspection`, { 'form': { 'token': req.session.accessToken, 'token_type_hint': 'access_token', 'client_id': process.env.OIDC_CLIENT_ID, 'client_secret': process.env.OIDC_CLIENT_SECRET } },function(err, response, body){ var token = JSON.parse(body); var tokenValid = false; // additional validation code goes here. });

This code creates an HTTP POST request to OneLogin’s token introspectionendpoint.

The introspection endpoint requires fourparameters:

• The token we’d like tovalidate
• A token typehint
• The OIDC application’s clientID
• The application’s clientsecret

We retrieve the user’s access token from Express’s session, set the token type hint to ‘access_token’ since that is the type of token we are sending, and we read the OIDC client ID from the app’s environmentvariables.

The endpoint expects the POST body to be in a URL-encoded form format. The request library accepts the form parameters as a JavaScript object and handles the encoding forus.

If we’ve supplied valid data to the token introspection endpoint, the body parameter of the callback function will contain a string holding a JSON object that looks similar tothis:

{ "active": true, "sub": "82690535", "client_id": "your-client-id", "exp": 1601043304, "iat": 1601039704, "sid": "9f8673aa-xxxx-xxxx-xxxx-17379f03d401", "iss": "https://contentlab-dev.onelogin.com/oidc/2", "jti": "VLlmnYZx0q7jYdYX_L9gs", "scope": "openid profile"}

Above, we see the signed-in user’s JWT token. The data returned by OneLogin only includes the token payload. We’d have to separate the token’s payload from its header and decrypt it if we had rolled our own JWT implementation. Fortunately, OneLogin has done the hard work forus.

OneLogin has altered the data slightly: the signed-in user’s access token would have stored the client ID in the JWT aud (audience) claim. OneLogin’s response also adds an active claim indicating whether the user is currently signed intoOneLogin.

Note that decoding a JWT via the introspection as we’ve done here is convenient, but not very efficient. In a backend web API, we wouldn’t want to call our OneLogin OIDC app’s introspection endpoint on every call our API receives. Instead, we could use a JWT library that loads and caches our OIDC app’s JSON Web Key Set (JWKS) uses it to verify the token’s authenticity, and then base64-decodes it so we can validate itsfields.

Understanding JWTClaims

Let’s start by looking at the client_id claim. In OneLogin-generated JWT tokens, the aud and client_id claims should equal the client ID of the OIDC app that generated the token. In access tokens generated by authorization servers created via OneLogin’s API Authorization API, the aud claim should contain the base URL that was provided when creating the authorizationserver.

In the route added above, add the following code to parse the token payload out of the response body and set up a variable to track whether our token isvalid.:

var token = JSON.parse(body);var tokenValid = false;

Next, add a line to make sure the client ID iscorrect:

var clientIdValid = body.client_id === process.env.OIDC_CLIENT_ID;

Then we must ensure the token hasn’t expired. A JWT token’s “exp” claim holds its expiry time. This claim is formatted as a Unix Timestamp — the number of seconds elapsed since the beginning of January 1, 1970,UTC.

var currentTimestamp = new Date().getTime() / 1000;var tokenIsNotExpired = body.exp > currentTimestamp;

We start by storing the current date and time in Unix timestamp format. The getTime method of JavaScript’s Date object almost gives us what we need, but provides the count in milliseconds instead of seconds. Dividing by 1000 turns it into a valid Unixtimestamp.

We then check that the token hasn’t expired by verifying that the exp claim’s value is greater than the currenttime.

Finally, check that the JWT includes a scope indicating that the user is authorized to make the request they’re making. OneLogin API Authorization servers contain a list of scopes that can be added to tokens requested fromit.

For example, an authorization server for a blogging app might add scopes such as post:create, post:edit, and post:delete. In this case, if a user asked your API to delete a blog post, you’d want to verify that their JWT token contains the post:delete claim. In our sample endpoint, the code to check for this scope might looklike:

var isAuthorized = body.scope.includes("post:delete")

In the end, our final token validation route looks likethis:

router.get('/token', async function(req, res, next) { request.post( `https://${ process.env.SUBDOMAIN }.onelogin.com/oidc/2/token/introspection`, { 'form': { 'token': req.session.accessToken, 'token_type_hint': 'access_token', 'client_id': process.env.OIDC_CLIENT_ID, 'client_secret': process.env.OIDC_CLIENT_SECRET } },function(err, response, body){ var token = JSON.parse(body); var tokenValid = false; var clientIdValid = token.client_id === process.env.OIDC_CLIENT_ID; console.log(token.client_id) console.log(process.env.OIDC_CLIENT_ID) // current time as Unix timestamp var currentTimestamp = new Date().getTime() / 1000; var tokenIsNotExpired = token.exp > currentTimestamp; // sample code to ensure that the required claim is included // var isAuthorized = token.scope.includes("post:delete") // uncomment isAuthorized if checking for a specific scope tokenValid = clientIdValid && tokenIsNotExpired //&& isAuthorized });});

Note that the code above contains some commented-out samples to demonstrate how you’d check for a specific scope in a realapplication.

NextSteps

And we’re done! Without much code, we’ve learned how to check the validity of the claims you can expect to find in a typical JWTtoken.

If you’re developing a web app or API, you know that authentication and authorization are pain points that distract you from delighting your users. Why not let OneLogin handle it for you so you can focus on all the other problems you need to solve? Get started today with a developeraccount.