JWT Access Token Validation – OAuth Architecture Guidance


Previously we drilled into API Coding Key Points for the initial code sample. Next we will describe some details and technical choices when validating JWTs in APIs.

Common Requirements

When designing token validation in APIs there are a few factors to consider:

Factor Description
Simple Code Validating a JWT should not require a great amount of code or complicate your API
Understanding You should understand how the validation works, so that you can ensure it is doing the right things
Extensible JWT validation should fit with a wider plan to ensure that APIs have what they need to authorize requests
Security Capabilities Some libraries have better capabilities than others, such as the ability to use financial-grade algorithms
Useful Errors You must ensure that API clients receive useful error responses when access tokens fail validation

Libraries v Frameworks

Some technology stacks provide a ‘Resource Server Framework’ that operates like a black box and requires very little code. This is fine when all you need is the default behaviour, but this blog uses a library approach for better control over the above behaviour.

JOSE Libraries

This blog will provide APIs developed in the following languages and in each case will use a JOSE library, so that the most leading edge security options are available, in case ever needed in future:

JOSE libraries support a number of OAuth related security specifications:

JWT Validation Code

The JWT validation code in our initial API required very little code, and we will explain the key behaviour in the following sections:

Viewing JWT Access Tokens

JWT access tokens are issued by the Authorization Server and consist of three parts. Cognito uses an asymmetric private key to create the digital signature:

Here is an example AWS Cognito JWT access token:


We can paste this into an Online JWT Viewer, to view the details, and note the Key Identifier (kid) field in the JWT header:

API Validation Steps

APIs must validate JWT access tokens on every request, which is designed to be a fast and scalable operation. The API must provide correct inputs to the security library in order for this to be done correctly:

Check Description
Algorithm The API specifies one or more algorithms that can be used, and AWS Cognito tokens use the mainstream RS256 option
Issuer The API expects the issuer in the token to be the value from OpenID Connect metadata
Audience The audience represents a set of related APIs, and the API must specify a value such as
Time Access tokens should be short lived, such as 30 minutes, and the API must check the token is valid for use and not expired
Public Key The API provides the token signing public key to the library, and the most common way to do this is via a trusted download URL

API OAuth Configuration

The initial API reflected the above settings in its configuration file. Note that AWS Cognito does not support an audience claim for access tokens so this was left blank.

Failed Token Validation

When any token validation checks fail, the API should return an error response with a 401 status code. I also like to return a clear payload as follows:

"code": "unauthorized",
"message": "Missing, invalid or expired access token"

In production systems this type of error is expected to occur frequently, since UI clients use short lived access tokens. When a client receives this response, a token refresh operation will be performed.

JWT Algorithms

An attacker could send an untrusted JWT with ‘alg: none’ in the JWT header, to bypass cryptographic security, but this cannot happen if you provide only secure algorithms to the security library.

Token Signing Public Keys

The API provides the security library with a trusted JWKS Endpoint and that for my AWS Cognito endpoint is at the below address:

This endpoint returns multiple public keys in a JSON Web Keyset and each of these has a key identifier. The entry whose kid value matches that in the access token’s JWT header is used to verify the token:

JWT Signature Verification

The above JWT Viewer website allows us to manually paste in a JSON Web Key. If we paste in a value from the JWKS endpoint whose kid does not match that in the JWT header we get a verification failure:

This result will also be returned if an attacker manually creates a JWT and sends it to the API, or if the JWT is tampered with and its contents altered.

JSON Web Keyset Caching

Any good JWT library will also cache the JSON Web Keyset details, with the following behaviour on subsequent requests:

Check Description
Same kid The cached JSON Web Key is used, to prevent the need for further calls to the Authorization Server’s JWKS endpoint
New kid A new call to the JWKS Endpoint is used, to get updated JSON Web Keys that include the new key identifier

Token Signing Key Rotation

The Authorization Server will rotate its cryptographic keys occasionally, which will result in a new private key being used to sign JWTs and new public keys being made available for verification.

For a while the JWKS Endpoint will then return both old and new keys, until the old one is retired. A good API security library will cache JWKs correctly, so that the API automatically and reliably copes with renewal.

API Authorization

Once the JWT processing is done, the claims in the JWT payload can be trusted by the API and used to authorize requests for API data. We will discuss use of claims in further detail in this blog’s Authorization Design.

Where Are We?

We covered the key behaviour and design choices when validating JWTs in APIs. Next we will make some recommendations on getting started with your own Authorization Server.

Next Steps