aws-jwt-verify

AWS JWT Verify

JavaScript library for verifying JWTs signed by Amazon Cognito, Application Load Balancer, and any OIDC-compatible IDP.

Installation

npm install aws-jwt-verify

This library can be used with Node.js 18 or higher. If used with TypeScript, TypeScript 4 or higher is required.

This library can also be used in Web browsers.

Basic usage

Amazon Cognito

import { CognitoJwtVerifier } from "aws-jwt-verify";

// Verifier that expects valid access tokens:
const verifier = CognitoJwtVerifier.create({
  userPoolId: "",
  tokenUse: "access",
  clientId: "",
});

try {
  const payload = await verifier.verify(
    "eyJraWQeyJhdF9oYXNoIjoidk..." // the JWT as string
  );
  console.log("Token is valid. Payload:", payload);
} catch {
  console.log("Token not valid!");
}

See all verify parameters for Amazon Cognito JWTs here.

Other IDPs

import { JwtVerifier } from "aws-jwt-verify";

const verifier = JwtVerifier.create({
  issuer: "https://example.com/", // set this to the expected "iss" claim on your JWTs
  audience: "", // set this to the expected "aud" claim on your JWTs
  jwksUri: "https://example.com/.well-known/jwks.json", // set this to the JWKS uri from your OpenID configuration
});

try {
  const payload = await verifier.verify("eyJraWQeyJhdF9oYXNoIjoidk...");
  console.log("Token is valid. Payload:", payload);
} catch {
  console.log("Token not valid!");
}

See all verify parameters for JWTs from any IDP here.

Non-standard IDPs

To make special cases work, you can use lower level constructs directly:

…

Application Load Balancer

When the Application Load Balancer authentication feature at listener level is enabled, 2 JWTs tokens are forwarded via HTTP headers (see docs):

• x-amzn-oidc-accesstoken: access token signed by Cognito or another IDP. This token can be verified with CognitoJwtVerifier (if signed by Cognito) or JwtVerifier (if signed by another IDP), see the examples above.
• x-amzn-oidc-data: user claims JWT signed by the ALB.

The user claims token can be verified with the AlbJwtVerifier:

import { AlbJwtVerifier } from "aws-jwt-verify";

// Verifier that expects valid user claims tokens:
const verifier = AlbJwtVerifier.create({
  albArn: "",
  issuer: "", // set this to the expected "iss" claim on your JWTs
  clientId: "", // set this to the expected "client" claim on your JWTs
});

try {
  const payload = await verifier.verify(
    "eyJraWQeyJhdF9oYXNoIjoidk..." // the user claims JWT as string, provided in the x-amzn-oidc-data HTTP header
  );
  console.log("Token is valid. Payload:", payload);
} catch {
  console.log("Token not valid!");
}

See all verify parameters for Amazon Application Load Balancer JWTs here.

Philosophy of this library

• Do one thing and do it well. Focus solely on verifying JWTs.
• Pure TypeScript library that can be used in Node.js v18 and above (both CommonJS and ESM supported), as well in the modern evergreen Web browser.
• Support both Amazon Cognito as well as any other OIDC-compatible IDP as first class citizen.
• 0 runtime dependencies, batteries included. This library includes all necessary code to verify JWTs. E.g. it contains a simple (and pluggable) HTTP helper to fetch the JWKS from the JWKS URI.
• Opinionated towards the best practices as described by the IETF in JSON Web Token Best Current Practices.
• Make it easy for users to use this library in a secure way. For example, this library requires users to specify issuer and audience, as these should be checked for (see best practices linked to above). Standard claims, such as exp and nbf, are checked automatically.

Currently, the following signature algorithms are supported:

• RS256 (RSA)
• RS384 (RSA)
• RS512 (RSA)
• ES256 (ECDSA)
• ES384 (ECDSA)
• ES512 (ECDSA)
• Ed25519 (EdDSA)
• Ed448 (EdDSA)

Please leave us a GitHub issue if you need another algorithm.

Intended Usage

This library was specifically designed to be easy to use in:

• API Gateway Lambda authorizers
• AppSync Lambda authorizers
• CloudFront Lambda@Edge
• Node.js APIs, e.g. running in AWS Fargate, that need to verify incoming JWTs

Usage in the Web browser

Many webdev toolchains (e.g. CreateReactApp) make including npm libraries in your web app easy, in which case using this library in your web app should just work.

If you need to bundle this library manually yourself, be aware that this library uses subpath imports, to automatically select the Web crypto implementation when bundling for the browser. This is supported out-of-the-box by webpack and esbuild. An example of using this library in a Vite web app, with Cypress tests, is included in this repository here.

Table of Contents

• Verifying JWTs from Amazon Cognito
  • Verify parameters
  • Checking scope
  • Custom JWT and JWK checks
  • Trusting multiple User Pools
  • Using the generic JWT verifier for Cognito JWTs
  • Verifying JWTs from a Cognito identity pool
• Verifying JWTs from any OIDC-compatible IDP
  • Verify parameters
• Verifying user claims JWTs from Application Load Balancers
  • Verify parameters
  • Trusting multiple User Pools
• How the algorithm (alg) is selected to verify the JWT signature with
• Peeking inside unverified JWTs
• Verification errors
  • Peek inside invalid JWTs
• The JWKS cache
  • Loading the JWKS from file
  • Rate limiting
  • Explicitly hydrating the JWKS cache
  • Clearing the JWKS cache
  • Customizing the JWKS cache
  • Sharing the JWKS cache amongst different verifiers
  • Using a different Fetcher with SimpleJwksCache
  • Configuring the JWKS response timeout and other HTTP options with Fetcher
  • Using a different penaltyBox with SimpleJwksCache
• Usage examples
  • CloudFront Lambda@Edge
  • API Gateway Lambda Authorizer - REST
  • HTTP API Authorizer
  • AppSync Lambda Authorizer
  • Fastify
  • Express
• Security
• License

Verifying JWTs from Amazon Cognito

Create a CognitoJwtVerifier instance and use it to verify JWTs:

import { CognitoJwtVerifier } from "aws-jwt-verify";

// Verifier that expects valid access tokens:
const verifier = CognitoJwtVerifier.create({
  userPoolId: "",
  tokenUse: "access",
  clientId: "",
});

try {
  const payload = await verifier.verify(
    "eyJraWQeyJhdF9oYXNoIjoidk..." // the JWT as string
  );
  console.log("Token is valid. Payload:", payload);
} catch {
  console.log("Token not valid!");
}

You can also use verifySync, if you've made sure the JWK has already been cached, see further below.

CognitoJwtVerifier verify parameters

Except the User Pool ID, parameters provided when creating the CognitoJwtVerifier act as defaults, that can be overridden upon calling verify or verifySync.

Supported parameters are:

• userPoolId (mandatory): the Cognito User Pool ID. The issuer (iss) and jwksUri will be determined from this. There is seamless support to check both the original and updated OIDC issuer required for user pools with multi-Region replication.
• tokenUse (mandatory): verify that the JWT's token_use claim matches your expectation. Set to either id or access. Set to null to skip checking token_use.
• clientId (mandatory): verify that the JWT's aud (id token) or client_id (access token) claim matches your expectation. Provide a string, or an array of strings to allow multiple client ids (i.e. one of these client ids must match the JWT). Set to null to skip checking client id (not recommended unless you know what you are doing).
• groups (optional): verify that the JWT's cognito:groups claim matches your expectation. Provide a string, or an array of strings to allow multiple groups (i.e. one of these groups must match the JWT).
• scope (optional): verify that the JWT's scope claim matches your expectation (only of use for access tokens). Provide a string, or an array of strings to allow multiple scopes (i.e. one of these scopes must match the JWT). See also Checking scope.
• graceSeconds (optional, default 0): to account for clock differences between systems, provide the number of seconds beyond JWT expiry (exp claim) or before "not before" (nbf claim) you will allow.
• customJwtCheck (optional): your custom function with additional JWT (and JWK) checks to execute (see also below).
• includeRawJwtInErrors (optional, default false): set to true if you want to peek inside the invalid JWT when verification fails. Refer to: Peek inside invalid JWTs.

…

Checking scope

If you provide scopes to the CognitoJwtVerifier, the verifier will make sure the scope claim in the JWT includes at least one of those scopes:

import { CognitoJwtVerifier } from "aws-jwt-verify";

const verifier = CognitoJwtVerifier.create({
  userPoolId: "",
  tokenUse: "access", // scopes are only present on Cognito access tokens
  clientId: "",
  scope: ["my-api:write", "my-api:admin"],
});

try {
  const payload = await verifier.verify("eyJraWQeyJhdF9oYXNoIjoidk...");
  console.log("Token is valid. Payload:", payload);
} catch {
  console.log("Token not valid!");
}

So a JWT payload like the following would have a valid scope:

{
  "client_id": "",
  "scope": "my-api:write someotherscope yetanotherscope", // scope string is split on spaces to gather the array of scopes to compare with
  "iat": 1234567890,
  "...": "..."
}

This scope would not be valid:

{
  "client_id": "",
  "scope": "my-api:read someotherscope yetanotherscope", // Neither "my-api:write" nor "my-api:admin" present
  "iat": 1234567890,
  "...": "..."
}

Custom JWT and JWK checks

It's possible to provide a function with your own custom JWT c