Verifying Cognito access tokens - Comparing three JWT packages for Lambda authorizers

03 Apr 2025
9 min read
AWS
When using Cognito access tokens to secure our API, we can choose from several JSON Web Token packages to verify tokens in Lambda authorizer functions.

1. The scenario

When the built-in Amazon API Gateway authorization methods don’t fully meet our needs, we can set up Lambda authorizers to manage the access control process. Even when using Cognito user pools and Cognito access tokens, there may still be a need for custom authorization logic.

The Lambda authorizer code decodes and verifies the token, and its business logic determines whether the request should proceed to the backend or be denied. Cognito access tokens are JSON Web Tokens (JWTs), and to simplify our coding, we might opt for an external package to handle token verification.

This article compares three JWT packages designed for Node.js and TypeScript.

2. Requirements

The comparison and final verdict are based on my specific requirements:

  • Lambda authorizers are necessary due to unique validation needs.
  • I use Cognito access tokens with scopes, which I verify in the authorizer (not covered in this article).
  • The authorizer should immediately return a deny policy if called with invalid, expired, or non-access tokens.
  • I rely on certain token properties in the authorizer logic, so decoding and verification are required.

3. Pre-requisites

This post will not go into the details of setting up the following:

  • A Cognito user pool.
  • A REST-type API Gateway.
  • A Lambda authorizer.

Links to relevant documentation will be provided at the end for those who need them.

As always, the solution I have chosen works for my use case, but your opinion or experience might differ.

4. Comparison

I explored three packages: AWS JWT Verify, jose, and jsonwebtoken.

The code examples I provide focus solely on the verification process. The custom logic for why the authorizer exists is omitted - you can substitute it with your logic. I also use utility functions to group similar logic, but I have left them out to keep things concise, so some snippets include pseudo-code.

Results in the Performance sections are based on tests with a 512 MB Lambda authorizer memory configuration.

After this necessary but lengthy introduction, let’s dive into the packages.

4.1. aws-jwt-verify

Since I’m working with Cognito tokens, I started with AWS JWT Verify.

Purpose

Maintained by AWS, this package is specifically designed to verify JWTs issued by Cognito.

Code

Here’s how the token verification flow might look with aws-jwt-verify:

import { CognitoJwtVerifier } from 'aws-jwt-verify';
import { APIGatewayRequestAuthorizerEvent } from 'aws-lambda';
import { CognitoAccessTokenPayload } from 'aws-jwt-verify/jwt-model';

// import util methods

// 1. Instantiate the verifier outside the handler
const verifier = CognitoJwtVerifier.create({
  userPoolId: process.env.USER_POOL_ID!,
  tokenUse: 'access',
  clientId: process.env.APP_CLIENT_ID!,
});

export async function handler(event: APIGatewayRequestAuthorizerEvent, context: Context) {
  const { headers, methodArn: resource } = event;

  // util function to extract the JWT from the header
  const token = extractAuthorizationToken(headers);
  if (!token) {
    // util function to generate the DENY IAM policy
    return generatePolicy({
      resource,
      effect: 'Deny',
      principalId: 'principal_id',
      message: 'Some error message',
    });
  }

  let payload: CognitoAccessTokenPayload;
  try {
    // 2. Use the verifier's "verify" method
    payload = await verifier.verify(token);
  } catch (error) {
    return generatePolicy({
      resource,
      effect: 'Deny',
      principalId: 'principal_id',
      message: 'Some error message',
    });
  }

  const { sub: userId, scope } = payload;

  // custom endpoint access control logic to verify scope here
}

Some key points to note.

First, we create a Cognito JWT verifier (1) by specifying the user pool ID, app client ID, and the token type to verify (access, id, or null). Setting null skips checking the token_use property. The authorizer pulls the user pool and app client ID from environment variables.

It’s best to instantiate the verifier outside the handler function. Since the user pool and app client ID are static and their values don’t depend on the event payload, this approach improves the Lambda function’s runtime. Code outside the handler is pre-loaded in the execution environment.

The core logic relies on the verifier’s verify method (2), which returns the token payload upon successful verification. As shown, no extra logic is needed. The package handles everything internally, keeping the code clean and readable.

Performance

My tests showed an initial cold start of 650–670 milliseconds. The first invocation took around 200 milliseconds, with subsequent calls typically under 100 ms, regardless of the verification result. I even saw a few single-digit durations, which was impressive!

Pros

  • Handles all Cognito-specific validation
  • Built-in TypeScript support
  • Minimal configuration and no extra methods required
  • Fetches and caches JSON Web Key Set under the hood

Cons

  • Limited to AWS tokens
  • Limited algorithm support (AWS use cases)
  • Restrictions apply when used with non-AWS identity providers

Best to use it

The aws-jwt-verify package shines when your application relies on Cognito as an identity provider.

Experience

I found this package fast and straightforward to use. It handles common verification scenarios (expired tokens, an ID token is sent instead of the access token) effectively and manages caching internally.

4.2. jose

Next up, I tested jose.

Purpose

jose is a well-maintained package that fully implements the JavaScript Object Signing and Encryption (JOSE) specification. It’s larger than aws-jwt-verify and offers more features.

Code

Here’s how I implemented jose for Cognito access tokens:

import { APIGatewayRequestAuthorizerEvent, Context } from 'aws-lambda';
import { createRemoteJWKSet, jwtVerify, errors } from 'jose';
import { CognitoAccessTokenPayload } from 'aws-jwt-verify/jwt-model';

// import util methods

const { JSON_WEB_KEY_SET_URL, ISSUER_URL } = process.env;

// 1. Cache the JSON Web Key Set
let cachedJWKS: ReturnType<typeof createRemoteJWKSet> | null = null;

export async function handler(event: APIGatewayRequestAuthorizerEvent) {
  const { headers, methodArn: resource } = event;

  // util function to extract the JWT from the header
  const token = extractAuthorizationToken(headers);
  if (!token) {
    return generatePolicy({
      resource,
      effect: 'Deny',
      principalId: 'principal_id',
      message: 'Some error message',
    });
  }

  // 2. Don’t feed the verifier with the token if it’s not an access token
  const decodedPayload = JSON.parse(
    Buffer.from(token.split('.')[1], 'base64').toString()
  );
  if (decodedPayload.token_use !== 'access') {
    return generatePolicy({
      resource,
      effect: 'Deny',
      principalId: 'principal_id',
      message: 'Some error message',
    });
  }

  let payload: CognitoAccessTokenPayload;
  try {
    // 3. Verifier util method is created to make the code
    // more readable
    payload = await verifyToken(token, {
      jwkUrl: JSON_WEB_KEY_SET_URL,
      issuerUrl: ISSUER_URL,
    });
  } catch (error) {
    // util method to handle different types of verification errors
    return tokenVerificationError(error);
  }

  const { sub: userId, scope } = payload;

  // custom endpoint access control logic to verify scope here
}

// Verifier utility function
interface VerifyTokenProps {
  jwkUrl: string;
  issuerUrl: string;
}
async function verifyToken(token: string, props: VerifyTokenProps) {
  if (!cachedJWKS) {
    cachedJWKS = createRemoteJWKSet(new URL(props.jwkUrl));
  }

  const verifyResult = await jwtVerify<CognitoAccessTokenPayload>(
    token,
    cachedJWKS,
    {
      issuer: props.issuerUrl, // the user pool’s
      maxTokenAge: 3600, // (4)
    }
  );

  return verifyResult.payload;
}

First, we cache the function that resolves the JSON Web Key Set (JWKS) from the Cognito JWKS endpoint (1). This prevents repeated calls to the endpoint for every authorizer invocation.

Next, I ensured the authorizer exits early if the token is not an access token (2). Since only access tokens include the scope property, there’s no point in proceeding with an incorrect token type.

The token verification happens in the verifyToken utility function (3). It checks for a local JWKS cache and downloads it from the remote endpoint if needed.

The jwtVerify function validates the token and returns the decoded payload on success. I discovered that without specifying maxTokenAge, the verifier hangs until the authorizer times out when given an expired token (4).

Performance

The Lambda cold start was similar to aws-jwt-verify. The first call took about 3.5 seconds due to the external API call to the Cognito JWKS endpoint. Subsequent calls ranged from 150–250 milliseconds.

Pros

  • Complete implementation of JOSE specifications
  • Supports a wide range of algorithms
  • TypeScript support
  • Supports both JWS (signing) and JWE (encryption)

Cons

  • Larger package
  • May be overkill for simple JWT use cases
  • More complex API, requiring additional configuration

Best to use it

The jose package excels with complex security needs, token creation, or non-AWS JWT implementations.

Experience

Initially, the authorizer timed out after 6 seconds with invalid or missing tokens. I realized I needed more memory. Calls consistently used over 300 MB of RAM, so configure the Lambda accordingly.

4.3. jsonwebtoken

The final package I evaluated was jsonwebtoken.

Purpose

The last commit to the jsonwebtoken repository was two years ago. I didn’t dig into the source code to assess the need for updates. With nearly 20 million weekly downloads, this popular package maintains the strong trust of developers and other libraries.

Code

Here’s how I implemented the logic with jsonwebtoken:

import {
  APIGatewayAuthorizerResult,
  APIGatewayRequestAuthorizerEvent,
} from 'aws-lambda';
import { decode, verify } from 'jsonwebtoken';
import jwkToPem from 'jwk-to-pem';
import axios from 'axios';
import { CognitoAccessTokenPayload } from 'aws-jwt-verify/jwt-model';

// import util methods

type JSONWebKey = jwkToPem.JWK & {
  kid: string;
  use: string;
};
interface JWKSResponse {
  keys: JSONWebKey[];
}

// 1. Implement caching for better performance
let jwksCache: JSONWebKey[] | null = null;
const jwksPemCache: { [key: string]: string } = {};

export const handler = async (
  event: APIGatewayRequestAuthorizerEvent
): Promise<APIGatewayAuthorizerResult> => {
  const { headers, methodArn: resource } = event;

  // util function to extract the JWT from the header
  const token = extractAuthorizationToken(headers);
  if (!token) {
    return generatePolicy({
      resource,
      effect: 'Deny',
      principalId: 'principal_id',
      message: 'Some error message',
    });
  }

  // built-in method to decode the JWT
  const decodedToken = decode(token, { complete: true });

  // Get the issuer from environment variables
  const issuer = 'https://cognito-idp.eu-central-1.amazonaws.com/USER_POOL_ID';

  let publicKey: string;
  try {
    // 2. Get the public key using a util function
    publicKey = await getPublicKey(decodedToken.header.kid, issuer);
  } catch (error) {
    return generatePolicy({
      resource,
      effect: 'Deny',
      principalId: 'principal_id',
      message: 'Some error message',
    });
  }

  // 3. Verify the token
  const verified = verify(token, publicKey, {
    issuer: issuer,
    algorithms: ['RS256'],
  }) as CognitoAccessTokenPayload;
  if (!verified) {
    return generatePolicy({
      resource,
      effect: 'Deny',
      principalId: 'principal_id',
      message: 'Some error message',
    });
  }

  const { sub: userId, scope } = verified;

  // custom endpoint access control logic to verify scope here
};

We can implement in-memory caching to enhance the authorizer’s performance (1).

Then, we fetch the public key from the Cognito JWKS endpoint using a utility function (2). Here’s what getPublicKey might look like:

async function getJwks(issuer: string) {
  if (jwksCache) {
    return jwksCache;
  }

  try {
    const response = await axios.get<JWKSResponse>(issuer);
    jwksCache = response.data.keys;
    return jwksCache;
  } catch (error) {
    throw error;
  }
}

async function getPublicKey(kid: string, issuer: string): Promise<string> {
  if (jwksPemCache[kid]) {
    return jwksPemCache[kid];
  }

  const jwks = await getJwks(issuer);
  const key = jwks.find((k) => k.kid === kid);
  if (!key) {
    throw new Error('Public key not found');
  }

  const publicKey = jwkToPem(key);
  jwksPemCache[kid] = publicKey;

  return publicKey;
}

We use axios, a popular HTTP client, to retrieve the key set.

Finally, the built-in verify method checks the token’s validity (3).

Performance

The Lambda cold start was comparable to the other packages. The first call lasted 250–300 milliseconds, with subsequent (cached) calls often under 100 milliseconds. Peak memory usage hovered around 180 MB.

Pros

  • Widely used, popular package with strong community support
  • General-purpose JWT library flexible enough for custom JWT implementations
  • Built-in methods for token decoding and verification
  • Offers greater control over the verification process

Cons

  • In-memory caching is recommended to boost performance
  • Requires extra code for full functionality
  • You need to implement logic to fetch the key set

Best to use it Use jsonwebtoken for simple JWTs from Cognito or non-AWS identity providers. It’s ideal if you want a lightweight, general-purpose package with built-in methods.

Experience

I used jsonwebtoken before, so its methods were familiar. It’s popular across frontend and backend development, and many packages depend on it. It performed reliably, though I had to invest some effort to match the logic of the other packages.

5. The verdict

After testing all three packages, I chose aws-jwt-verify for my project with Cognito access tokens.

The deciding factor was its minimal code requirements. It also proved fastest in my tests, though for my use case, the difference between an 80-millisecond and a 200-millisecond response is negligible.

For all packages, allocate sufficient memory to the authorizer function. I found 256 MB insufficient as functions often timed out with invalid tokens. I recommend at least 512 MB of RAM for each package.

These packages are not limited to Lambda. You can use them to validate tokens in Express servers running on EC2 instances or containers, for example.

6. Summary

Multiple npm packages can verify JWTs.

For a Cognito user pool as an identity provider, aws-jwt-verify offers a simple, lightweight solution.

For general JWT verification, jsonwebtoken is a solid choice. For advanced verification logic, consider jose.

7. Further reading

Getting started with user pools - How to create a user pool with an app client

Get started with API Gateway - How to create an API Gateway resource

Create your first function - AWS Lambda “Getting started”

Verifying a JSON Web Token - What aws-jwt-verify does for token validation

Previous post
Next post