{"id":13485022,"url":"https://github.com/awslabs/aws-jwt-verify","last_synced_at":"2026-04-02T01:29:14.990Z","repository":{"id":37624914,"uuid":"407226090","full_name":"awslabs/aws-jwt-verify","owner":"awslabs","description":"JS library for verifying JWTs signed by Amazon Cognito, and any OIDC-compatible IDP that signs JWTs with RS256, RS384, RS512, ES256, ES384, ES512, Ed25519 and Ed448","archived":false,"fork":false,"pushed_at":"2026-03-27T02:34:44.000Z","size":2365,"stargazers_count":728,"open_issues_count":9,"forks_count":50,"subscribers_count":12,"default_branch":"main","last_synced_at":"2026-03-27T06:42:23.738Z","etag":null,"topics":["amazon-cognito","amplify","jwt","nodejs","typescript"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/awslabs.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":"NOTICE","maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2021-09-16T15:53:42.000Z","updated_at":"2026-03-26T20:21:04.000Z","dependencies_parsed_at":"2025-02-03T15:30:35.416Z","dependency_job_id":null,"html_url":"https://github.com/awslabs/aws-jwt-verify","commit_stats":{"total_commits":86,"total_committers":14,"mean_commits":6.142857142857143,"dds":"0.34883720930232553","last_synced_commit":"16a3d538c6477109ae4f06b319e7080d463892e8"},"previous_names":[],"tags_count":18,"template":false,"template_full_name":"amazon-archives/__template_Apache-2.0","purl":"pkg:github/awslabs/aws-jwt-verify","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/awslabs%2Faws-jwt-verify","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/awslabs%2Faws-jwt-verify/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/awslabs%2Faws-jwt-verify/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/awslabs%2Faws-jwt-verify/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/awslabs","download_url":"https://codeload.github.com/awslabs/aws-jwt-verify/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/awslabs%2Faws-jwt-verify/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31218016,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-03-31T03:16:13.749Z","status":"ssl_error","status_checked_at":"2026-03-31T03:15:17.442Z","response_time":111,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["amazon-cognito","amplify","jwt","nodejs","typescript"],"created_at":"2024-07-31T17:01:42.917Z","updated_at":"2026-04-02T01:29:14.976Z","avatar_url":"https://github.com/awslabs.png","language":"TypeScript","funding_links":[],"categories":["TypeScript"],"sub_categories":[],"readme":"# AWS JWT Verify\n\n**JavaScript** library for **verifying** JWTs signed by **Amazon Cognito**, **Application Load Balancer**, and any **OIDC-compatible IDP**.\n\n## Installation\n\n`npm install aws-jwt-verify`\n\nThis library can be used with Node.js 18 or higher. If used with TypeScript, TypeScript 4 or higher is required.\n\nThis library can also be used in Web browsers.\n\n## Basic usage\n\n### Amazon Cognito\n\n```typescript\nimport { CognitoJwtVerifier } from \"aws-jwt-verify\";\n\n// Verifier that expects valid access tokens:\nconst verifier = CognitoJwtVerifier.create({\n  userPoolId: \"\u003cuser_pool_id\u003e\",\n  tokenUse: \"access\",\n  clientId: \"\u003cclient_id\u003e\",\n});\n\ntry {\n  const payload = await verifier.verify(\n    \"eyJraWQeyJhdF9oYXNoIjoidk...\" // the JWT as string\n  );\n  console.log(\"Token is valid. Payload:\", payload);\n} catch {\n  console.log(\"Token not valid!\");\n}\n```\n\nSee all verify parameters for Amazon Cognito JWTs [here](#cognitojwtverifier-verify-parameters).\n\n### Other IDPs\n\n```typescript\nimport { JwtVerifier } from \"aws-jwt-verify\";\n\nconst verifier = JwtVerifier.create({\n  issuer: \"https://example.com/\", // set this to the expected \"iss\" claim on your JWTs\n  audience: \"\u003caudience\u003e\", // set this to the expected \"aud\" claim on your JWTs\n  jwksUri: \"https://example.com/.well-known/jwks.json\", // set this to the JWKS uri from your OpenID configuration\n});\n\ntry {\n  const payload = await verifier.verify(\"eyJraWQeyJhdF9oYXNoIjoidk...\");\n  console.log(\"Token is valid. Payload:\", payload);\n} catch {\n  console.log(\"Token not valid!\");\n}\n```\n\nSee all verify parameters for JWTs from any IDP [here](#JwtVerifier-verify-parameters).\n\n### Non-standard IDPs\n\nTo make special cases work, you can use lower level constructs directly:\n\n```typescript\nimport { verifyJwt } from \"aws-jwt-verify/jwt-verifier\"; // there is also verifyJwtSync() for if you already have the JWK(S) at hand\nimport { SimpleJwksCache } from \"aws-jwt-verify/jwk\";\n\n// E.g. use SimpleJwksCache to fetch and cache JSON Web Key Sets (JWKS)\n// SimpleJwksCache will deal with key rotations automatically\nconst jwksCache = new SimpleJwksCache();\n\ntry {\n  const payload = await verifyJwt(\n    \"eyJraWQeyJhdF9oYXNoIjoidk...\", // the JWT as string\n    \"https://example.com/.well-known/jwks.json\", // set this to the JWKS uri from your OpenID configuration\n    {\n      issuer: \"\u003ciss\u003e\", // set this to the expected iss claim on the JWT (or to null, to skip this check)\n      audience: \"\u003caud\u003e\", // set this to the expected aud claim on the JWT (or to null, to skip this check)\n    },\n    jwksCache.getJwk.bind(jwksCache) // use JWKS cache (optional)\n  );\n  console.log(\"Token is valid. Payload:\", payload);\n} catch {\n  console.log(\"Token not valid!\");\n}\n```\n\n### Application Load Balancer\n\nWhen the [Application Load Balancer authentication feature at listener level](https://docs.aws.amazon.com/elasticloadbalancing/latest/application/listener-authenticate-users.html) is enabled, 2 JWTs tokens are forwarded via HTTP headers (see [docs](https://docs.aws.amazon.com/elasticloadbalancing/latest/application/listener-authenticate-users.html#user-claims-encoding)):\n\n- `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.\n- `x-amzn-oidc-data`: user claims JWT signed by the ALB.\n\nThe user claims token can be verified with the `AlbJwtVerifier`:\n\n```typescript\nimport { AlbJwtVerifier } from \"aws-jwt-verify\";\n\n// Verifier that expects valid user claims tokens:\nconst verifier = AlbJwtVerifier.create({\n  albArn: \"\u003calb_arn\u003e\",\n  issuer: \"\u003cissuer\u003e\", // set this to the expected \"iss\" claim on your JWTs\n  clientId: \"\u003cclient_id\u003e\", // set this to the expected \"client\" claim on your JWTs\n});\n\ntry {\n  const payload = await verifier.verify(\n    \"eyJraWQeyJhdF9oYXNoIjoidk...\" // the user claims JWT as string, provided in the x-amzn-oidc-data HTTP header\n  );\n  console.log(\"Token is valid. Payload:\", payload);\n} catch {\n  console.log(\"Token not valid!\");\n}\n```\n\nSee all verify parameters for Amazon Application Load Balancer JWTs [here](#albjwtverifier-verify-parameters).\n\n## Philosophy of this library\n\n- Do one thing and do it well. Focus solely on **verifying** JWTs.\n- 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.\n- Support both **Amazon Cognito** as well as any other **OIDC-compatible IDP** as first class citizen.\n- **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.\n- Opinionated towards the **best practices** as described by the IETF in [JSON Web Token Best Current Practices](https://datatracker.ietf.org/doc/html/draft-ietf-oauth-jwt-bcp-02#section-3).\n- 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.\n\nCurrently, the following signature algorithms are supported:\n\n- **`RS256` (RSA)**\n- **`RS384` (RSA)**\n- **`RS512` (RSA)**\n- **`ES256` (ECDSA)**\n- **`ES384` (ECDSA)**\n- **`ES512` (ECDSA)**\n- **`Ed25519` (EdDSA)**\n- **`Ed448` (EdDSA)**\n\nPlease leave us a GitHub issue if you need another algorithm.\n\n## Intended Usage\n\nThis library was specifically designed to be easy to use in:\n\n- [API Gateway Lambda authorizers](#api-gateway-lambda-authorizer---rest)\n- [AppSync Lambda authorizers](#appsync-lambda-authorizer)\n- [CloudFront Lambda@Edge](#cloudfront-lambdaedge)\n- Node.js APIs, e.g. running in AWS Fargate, that need to verify incoming JWTs\n\n## Usage in the Web browser\n\nMany webdev toolchains (e.g. [CreateReactApp](https://github.com/facebook/create-react-app)) make including `npm` libraries in your web app easy, in which case using this library in your web app should just work.\n\nIf you need to bundle this library manually yourself, be aware that this library uses [subpath imports](https://nodejs.org/api/packages.html#subpath-imports), to automatically select the Web crypto implementation when bundling for the browser. This is supported out-of-the-box by [webpack](https://webpack.js.org/) and [esbuild](https://esbuild.github.io/). An example of using this library in a Vite web app, with Cypress tests, is included in this repository [here](tests/vite-app/).\n\n## Table of Contents\n\n- [Verifying JWTs from Amazon Cognito](#Verifying-JWTs-from-Amazon-Cognito)\n  - [Verify parameters](#cognitojwtverifier-verify-parameters)\n  - [Checking scope](#checking-scope)\n  - [Custom JWT and JWK checks](#custom-jwt-and-jwk-checks)\n  - [Trusting multiple User Pools](#trusting-multiple-user-pools)\n  - [Using the generic JWT verifier for Cognito JWTs](#using-the-generic-jwt-verifier-for-cognito-jwts)\n- [Verifying JWTs from any OIDC-compatible IDP](#verifying-jwts-from-any-oidc-compatible-idp)\n  - [Verify parameters](#JwtVerifier-verify-parameters)\n- [Verifying user claims JWTs from Application Load Balancers](#verifying-user-claims-jwts-from-application-load-balancers)\n  - [Verify parameters](#albjwtverifier-verify-parameters)\n  - [Trusting multiple User Pools](#trusting-multiple-application-load-balancers)\n- [How the algorithm (`alg`) is selected to verify the JWT signature with](#how-the-algorithm-alg-is-selected-to-verify-the-jwt-signature-with)\n- [Peeking inside unverified JWTs](#peeking-inside-unverified-jwts)\n- [Verification errors](#verification-errors)\n  - [Peek inside invalid JWTs](#peek-inside-invalid-jwts)\n- [The JWKS cache](#the-jwks-cache)\n  - [Loading the JWKS from file](#loading-the-jwks-from-file)\n  - [Rate limiting](#rate-limiting)\n  - [Explicitly hydrating the JWKS cache](#explicitly-hydrating-the-jwks-cache)\n  - [Clearing the JWKS cache](#clearing-the-jwks-cache)\n  - [Customizing the JWKS cache](#customizing-the-jwks-cache)\n  - [Sharing the JWKS cache amongst different verifiers](#sharing-the-jwks-cache-amongst-different-verifiers)\n  - [Using a different `Fetcher` with `SimpleJwksCache`](#using-a-different-fetcher-with-simplejwkscache)\n  - [Configuring the JWKS response timeout and other HTTP options with `Fetcher`](#configuring-the-jwks-response-timeout-and-other-http-options-with-fetcher)\n  - [Using a different `penaltyBox` with `SimpleJwksCache`](#using-a-different-penaltybox-with-simplejwkscache)\n- [Usage examples](#Usage-examples)\n  - [CloudFront Lambda@Edge](#cloudfront-lambdaedge)\n  - [API Gateway Lambda Authorizer - REST](#api-gateway-lambda-authorizer---rest)\n  - [HTTP API Authorizer](#http-api-lambda-authorizer)\n  - [AppSync Lambda Authorizer](#appsync-lambda-authorizer)\n  - [Fastify](#fastify)\n  - [Express](#express)\n- [Security](#security)\n- [License](#license)\n\n## Verifying JWTs from Amazon Cognito\n\nCreate a `CognitoJwtVerifier` instance and use it to verify JWTs:\n\n```typescript\nimport { CognitoJwtVerifier } from \"aws-jwt-verify\";\n\n// Verifier that expects valid access tokens:\nconst verifier = CognitoJwtVerifier.create({\n  userPoolId: \"\u003cuser_pool_id\u003e\",\n  tokenUse: \"access\",\n  clientId: \"\u003cclient_id\u003e\",\n});\n\ntry {\n  const payload = await verifier.verify(\n    \"eyJraWQeyJhdF9oYXNoIjoidk...\" // the JWT as string\n  );\n  console.log(\"Token is valid. Payload:\", payload);\n} catch {\n  console.log(\"Token not valid!\");\n}\n```\n\nYou can also use `verifySync`, if you've made sure the JWK has already been cached, see further below.\n\n### `CognitoJwtVerifier` `verify` parameters\n\nExcept the User Pool ID, parameters provided when creating the `CognitoJwtVerifier` act as defaults, that can be overridden upon calling `verify` or `verifySync`.\n\nSupported parameters are:\n\n- `userPoolId` (mandatory): the Cognito User Pool ID. The issuer (`iss`) and `jwksUri` will be determined from this.\n- `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`.\n- `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).\n- `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).\n- `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](#Checking-scope).\n- `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.\n- `customJwtCheck` (optional): your custom function with additional JWT (and JWK) checks to execute (see also below).\n- `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](#peek-inside-invalid-jwts).\n\n```typescript\nimport { CognitoJwtVerifier } from \"aws-jwt-verify\";\n\nconst verifier = CognitoJwtVerifier.create({\n  userPoolId: \"\u003cuser_pool_id\u003e\", // mandatory, can't be overridden upon calling verify\n  tokenUse: \"id\", // needs to be specified here or upon calling verify\n  clientId: \"\u003cclient_id\u003e\", // needs to be specified here or upon calling verify\n  groups: \"admins\", // optional\n  graceSeconds: 0, // optional\n  scope: \"my-api/read\", // optional\n  customJwtCheck: (payload, header, jwk) =\u003e {}, // optional\n});\n\ntry {\n  const payload = await verifier.verify(\"eyJraWQeyJhdF9oYXNoIjoidk...\", {\n    groups: \"users\", // Cognito groups overridden: should be users (not admins)\n  });\n  console.log(\"Token is valid. Payload:\", payload);\n} catch {\n  console.log(\"Token not valid!\");\n}\n```\n\n### Checking scope\n\nIf you provide scopes to the `CognitoJwtVerifier`, the verifier will make sure the `scope` claim in the JWT includes at least one of those scopes:\n\n```typescript\nimport { CognitoJwtVerifier } from \"aws-jwt-verify\";\n\nconst verifier = CognitoJwtVerifier.create({\n  userPoolId: \"\u003cuser_pool_id\u003e\",\n  tokenUse: \"access\", // scopes are only present on Cognito access tokens\n  clientId: \"\u003cclient_id\u003e\",\n  scope: [\"my-api:write\", \"my-api:admin\"],\n});\n\ntry {\n  const payload = await verifier.verify(\"eyJraWQeyJhdF9oYXNoIjoidk...\");\n  console.log(\"Token is valid. Payload:\", payload);\n} catch {\n  console.log(\"Token not valid!\");\n}\n```\n\nSo a JWT payload like the following would have a valid scope:\n\n```javascript\n{\n  \"client_id\": \"\u003cclient_id\u003e\",\n  \"scope\": \"my-api:write someotherscope yetanotherscope\", // scope string is split on spaces to gather the array of scopes to compare with\n  \"iat\": 1234567890,\n  \"...\": \"...\"\n}\n```\n\nThis scope would not be valid:\n\n```javascript\n{\n  \"client_id\": \"\u003cclient_id\u003e\",\n  \"scope\": \"my-api:read someotherscope yetanotherscope\", // Neither \"my-api:write\" nor \"my-api:admin\" present\n  \"iat\": 1234567890,\n  \"...\": \"...\"\n}\n```\n\n### Custom JWT and JWK checks\n\nIt's possible to provide a function with your own custom JWT checks. This function will be called if the JWT is valid, at the end of the JWT verification.\n\nThe function will be called with:\n\n- the decoded JWT header\n- the decoded JWT payload\n- the JWK that was used to verify the JWT\n\nThrow an error in this function if you want to reject the JWT.\n\n```typescript\nimport { CognitoJwtVerifier } from \"aws-jwt-verify\";\n\nconst idTokenVerifier = CognitoJwtVerifier.create({\n  userPoolId: \"\u003cuser_pool_id\u003e\",\n  tokenUse: \"id\",\n  clientId: \"\u003cclient_id\u003e\",\n  customJwtCheck: async ({ header, payload, jwk }) =\u003e {\n    if (header.someHeaderField !== \"expected\") {\n      throw new Error(\"something wrong with the header\");\n    }\n    if (payload.somePayloadField !== \"expected\") {\n      throw new Error(\"something wrong with the payload\");\n    }\n    if (jwk.someJwkfField !== \"expected\") {\n      throw new Error(\"something wrong with the jwk\");\n    }\n    await someAsyncCheck(...); // can call out to a DB or do whatever\n  },\n});\n\n// This will now throw, even if the JWT is otherwise valid, if your custom function throws:\nawait idTokenVerifier.verify(\"eyJraWQeyJhdF9oYXNoIjoidk...\");\n```\n\nNote that `customJwtCheck` may be an async function, but only if you use `verify` (not supported for `verifySync`).\n\n### Trusting multiple User Pools\n\nIf you want to allow JWTs from multiple User Pools, provide an array with these User Pools upon creating the verifier:\n\n```typescript\nimport { CognitoJwtVerifier } from \"aws-jwt-verify\";\n\n// This verifier will trust both User Pools\nconst idTokenVerifier = CognitoJwtVerifier.create([\n  {\n    userPoolId: \"\u003cuser_pool_id\u003e\",\n    tokenUse: \"id\",\n    clientId: \"\u003cclient_id\u003e\", // clientId is mandatory at verifier level now, to disambiguate between User Pools\n  },\n  {\n    userPoolId: \"\u003cuser_pool_id_2\u003e\",\n    tokenUse: \"id\",\n    clientId: \"\u003cclient_id_2\u003e\",\n  },\n]);\n\ntry {\n  const idTokenPayload = await idTokenVerifier.verify(\n    \"eyJraWQeyJhdF9oYXNoIjoidk...\" // token must be signed by either of the User Pools\n  );\n  console.log(\"Token is valid. Payload:\", idTokenPayload);\n} catch {\n  console.log(\"Token not valid!\");\n}\n```\n\n### Using the generic JWT verifier for Cognito JWTs\n\nThe generic `JwtVerifier` (see [below](#verifying-jwts-from-any-oidc-compatible-idp)) can also be used for Cognito, which is useful if you want to define a verifier that trusts multiple IDPs, i.e. Cognito and another IDP.\n\nIn this case, leave `audience` to `null`, but rather manually add `validateCognitoJwtFields` in the `customJwtCheck`.\n(Only Cognito ID tokens have an `audience` claim, Cognito Access token have a `client_id` claim instead. The `validateCognitoJwtFields` function handles this difference automatically for you)\n\n```typescript\nimport { JwtVerifier } from \"aws-jwt-verify\";\nimport { validateCognitoJwtFields } from \"aws-jwt-verify/cognito-verifier\";\n\nconst verifier = JwtVerifier.create([\n  {\n    issuer: \"https://cognito-idp.eu-west-1.amazonaws.com/\u003cuser_pool_id\u003e\",\n    audience: null, // audience (~clientId) is checked instead, by the Cognito specific checks below\n    customJwtCheck: ({ payload }) =\u003e\n      validateCognitoJwtFields(payload, {\n        tokenUse: \"access\", // set to \"id\" or \"access\" (or null if both are fine)\n        clientId: \"\u003cclient_id\u003e\", // provide the client id, or an array of client ids (or null if you do not want to check client id)\n        groups: [\"admin\", \"others\"], // optional, provide a group name, or array of group names\n      }),\n  },\n  {\n    issuer: \"https://example.com/my/other/idp\",\n    audience: \"myaudience\", // do specify audience for other IDPs\n  },\n]);\n```\n\n## Verifying JWTs from any OIDC-compatible IDP\n\nThe generic `JwtVerifier` works for any OIDC-compatible IDP:\n\n```typescript\nimport { JwtVerifier } from \"aws-jwt-verify\";\n\nconst verifier = JwtVerifier.create({\n  issuer: \"https://example.com/\", // set this to the expected \"iss\" claim on your JWTs\n  audience: \"\u003caudience\u003e\", // set this to the expected \"aud\" claim on your JWTs\n  jwksUri: \"https://example.com/.well-known/jwks.json\", // set this to the JWKS uri from your OpenID configuration\n});\n\ntry {\n  const payload = await verifier.verify(\"eyJraWQeyJhdF9oYXNoIjoidk...\");\n  console.log(\"Token is valid. Payload:\", payload);\n} catch {\n  console.log(\"Token not valid!\");\n}\n```\n\nSupport Multiple IDP's:\n\n```typescript\nconst verifier = JwtVerifier.create([\n  {\n    issuer: \"https://example.com/idp1\",\n    audience: \"expectedAudienceIdp1\",\n  },\n  {\n    issuer: \"https://example.com/idp2\",\n    audience: \"expectedAudienceIdp2\",\n  },\n]);\n\ntry {\n  const otherPayload = await verifier.verify(\"eyJraWQeyJhdF9oYXNoIjoidk...\"); // Token must be from either idp1 or idp2\n  console.log(\"Token is valid. Payload:\", otherPayload);\n} catch {\n  console.log(\"Token not valid!\");\n}\n```\n\n### `JwtVerifier` `verify` parameters\n\nExcept `issuer`, parameters provided when creating the `JwtVerifier` act as defaults, that can be overridden upon calling `verify` or `verifySync`.\n\nSupported parameters are:\n\n- `issuer` (mandatory): set this to the expected `iss` claim on the JWTs. Provide a single string, or set to `null` to skip checking issuer (not recommended unless you know what you are doing).\n- `jwksUri` (optional, can only be provided at verifier level): the URI where the JWKS can be downloaded from. To find this URI for your IDP, consult your IDP's OpenId configuration (e.g. by opening the OpenId configuration in your browser). Usually, it is `${issuer}/.well-known/jwks.json`, which is the default value that will be used if you don't explicitly provide `jwksUri`.\n- `audience` (mandatory): verify that the JWT's `aud` claim matches your expectation. Provide a string, or an array of strings to allow multiple client ids (i.e. one of these audiences must match the JWT). Set to `null` to skip checking audience (not recommended unless you know what you are doing). Note that a JWT's `aud` claim might be an array of audiences. The `JwtVerifier` will in that case make sure that at least one of these audiences matches with at least one of the audiences that were provided to the verifier.\n- `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](#checking-scope).\n- `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.\n- `customJwtCheck` (optional): your custom function with additional JWT checks to execute (see [Custom JWT and JWK checks](#custom-jwt-and-jwk-checks)).\n- `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](#peek-inside-invalid-jwts).\n\n## Verifying user claims JWTs from Application Load Balancers\n\nThe generic `JwtVerifier` can verify user claims JWTs provided by Application Load Balancers with [authentication feature enabled](https://docs.aws.amazon.com/elasticloadbalancing/latest/application/listener-authenticate-users.html). This token is present in the HTTP header `x-amzn-oidc-data` forwarded by the Application Load Balancer to the backend.\n\n### `AlbJwtVerifier` `verify` parameters\n\nExcept `albArn` and `issuer`, parameters provided when creating the `AlbJwtVerifier` act as defaults, that can be overridden upon calling `verify` or `verifySync`.\n\nSupported parameters are:\n\n- `albArn` (mandatory): the Application Load Balancer ARN sending the user claims JWT to verify.\n- `issuer` (mandatory): set this to the expected `iss` claim on the JWTs. Provide a single string, or set to `null` to skip checking issuer (not recommended unless you know what you are doing). If the ALB listener authentication is configured with cognito as the IDP, this parameter should be `https://cognito-idp.${region}.amazonaws.com/${userPoolId}`.\n- `jwksUri` (optional, default `https://public-keys.auth.elb.${region}.amazonaws.com`): the ALB public key FQDN. For the default value, the region is automatically extracted from the `albArn`. If the application is hosted on the AWS GovCloud (US), this parameter needs to be specified with one of these values: `https://s3-us-gov-west-1.amazonaws.com/aws-elb-public-keys-prod-us-gov-west-1` or `https://s3-us-gov-east-1.amazonaws.com/aws-elb-public-keys-prod-us-gov-east-1` depending on the region.\n- `clientId` (mandatory): verify that the JWT's `client_id` 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).\n- `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.\n- `customJwtCheck` (optional): your custom function with additional JWT (and JWK) checks to execute (see also below).\n- `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](#peek-inside-invalid-jwts).\n\n```typescript\nimport { AlbJwtVerifier } from \"aws-jwt-verify\";\n\nconst verifier = AlbJwtVerifier.create({\n  albArn: \"\u003calb_arn\u003e\",\n  issuer: \"\u003cissuer\u003e\",\n  clientId: \"\u003cclient_id\u003e\", // needs to be specified here or upon calling verify\n  graceSeconds: 0, // optional\n  customJwtCheck: (payload, header, jwk) =\u003e {}, // optional\n});\n\ntry {\n  const payload = await verifier.verify(\"eyJraWQeyJhdF9oYXNoIjoidk...\");\n  console.log(\"Token is valid. Payload:\", payload);\n} catch {\n  console.log(\"Token not valid!\");\n}\n```\n\n### Trusting multiple Application Load Balancers\n\nIf you want to allow JWTs from multiple Application Load Balancers with different issuers, provide an array of configuration objects upon creating the verifier (each distinct issuer must be represented in a separate configuration object):\n\n```typescript\nimport { AlbJwtVerifier } from \"aws-jwt-verify\";\n\n// This verifier will trust both Application Load Balancers\nconst idTokenVerifier = AlbJwtVerifier.create([\n  {\n    albArn: \"\u003calb_arn_1\u003e\",\n    issuer: \"\u003cissuer_1\u003e\",\n    clientId: \"\u003cclient_id_1\u003e\",\n  },\n  {\n    albArn: \"\u003calb_arn_2\u003e\",\n    issuer: \"\u003cissuer_2\u003e\",\n    clientId: \"\u003cclient_id_2\u003e\",\n  },\n]);\n\ntry {\n  const idTokenPayload = await idTokenVerifier.verify(\n    \"eyJraWQeyJhdF9oYXNoIjoidk...\" // token must be signed by either of the Application Load Balancer\n  );\n  console.log(\"Token is valid. Payload:\", idTokenPayload);\n} catch {\n  console.log(\"Token not valid!\");\n}\n```\n\nIf you're using multiple Application Load Balancers with the same IDP (same Amazon Cognito User Pool or same IDP issuer), pass an array of `albArn` (each distinct issuer must be represented in only one configuration object):\n\n```typescript\nimport { AlbJwtVerifier } from \"aws-jwt-verify\";\n\n// This verifier will trust both Application Load Balancers\nconst idTokenVerifier = AlbJwtVerifier.create({\n  albArn: [\"\u003calb_arn_1\u003e\", \"\u003calb_arn_2\u003e\"],\n  issuer: \"\u003cissuer\u003e\",\n  clientId: \"\u003cclient_id\u003e\",\n});\n\ntry {\n  const idTokenPayload = await idTokenVerifier.verify(\n    \"eyJraWQeyJhdF9oYXNoIjoidk...\" // token must be signed by either of the Application Load Balancer\n  );\n  console.log(\"Token is valid. Payload:\", idTokenPayload);\n} catch {\n  console.log(\"Token not valid!\");\n}\n```\n\n## How the algorithm (`alg`) is selected to verify the JWT signature with\n\n`aws-jwt-verify` does not require users to specify the algorithm (`alg`) to verify JWT signatures with. Rather, the `alg` is selected automatically from the JWT header, and matched against the `alg` (if any) on the selected JWK. We believe this design decision makes it easier to use this library: one less parameter to provide, that developers potentially would not know which value to provide for.\n\nTo readers who are intimately aware of how JWT verification in general should work, this design decision may seem dubious, because the JWT header, and thus the `alg` in it, would be under potential threat actor control. But this is mitigated because `aws-jwt-verify` only allows a limited set of algorithms anyway, all asymmetric (see [above](#philosophy-of-this-library)). The egregious case of `alg` with value `none` is explicitly not supported, nor are symmetric algorithms, and such JWTs would be considered invalid.\n\nIf the JWK that's selected for verification (see [The JWKS cache](#the-jwks-cache)) has an `alg`, it must match the JWT header's `alg`, or the JWT is considered invalid. `alg` is an optional JWK field, but in practice present in most implementations (such as Amazon Cognito User Pools).\n\n### Advanced: enforcing the algorithm (`alg`)\n\nIf you really want to enforce a certain `alg`, you should use a JWKS that only contains JWKs which have that `alg` explicitly specified.\n\nIf the JWKS is not under your control, you can customize the way your JWKS is used by [customizing the JWKS cache](#customizing-the-jwks-cache). E.g. you could explicitly set the `alg` value on each JWK, or filter the JWKS to only those JWKs that have a specific `alg`, such as in the example below:\n\n```typescript\nimport { CognitoJwtVerifier } from \"aws-jwt-verify\";\nimport { SimpleJwksCache } from \"aws-jwt-verify/jwk\";\n\nclass Rs256OnlyJwksCache extends SimpleJwksCache {\n  async getJwks(jwksUri: string) {\n    const jwks = await super.getJwks(jwksUri);\n    // filter JWKS to RS256 only\n    jwks.keys = jwks.keys.filter((jwk) =\u003e jwk.alg === \"RS256\");\n    return jwks;\n  }\n}\n\nconst verifier = CognitoJwtVerifier.create(\n  {\n    userPoolId: \"\u003cuser_pool_id\u003e\",\n    tokenUse: \"access\",\n    clientId: \"\u003cclient_id\u003e\",\n  },\n  {\n    jwksCache: new Rs256OnlyJwksCache(),\n  }\n);\n```\n\nAlternatively, you can code a [custom JWT check](#custom-jwt-and-jwk-checks) to enforce that the JWT's header `alg` value matches the `alg` you want to enforce.\n\n## Peeking inside unverified JWTs\n\nYou can peek into the payload of an unverified JWT as follows.\n\nNote: this does NOT verify a JWT, do not trust the returned payload and header! For most use cases, you would not want to call this function directly yourself, rather you would call `verify()` with the JWT, which would call this function (and others) for you.\n\n```typescript\nimport { decomposeUnverifiedJwt } from \"aws-jwt-verify/jwt\";\n\n// danger! payload is sanity checked and JSON-parsed, but otherwise unverified, trust nothing in it!\nconst { payload } = decomposeUnverifiedJwt(\n  \"eyJraWQeyJhdF9oYXNoIjoidk...\" // the JWT as string\n);\n```\n\n## Verification errors\n\nWhen verification of a JWT fails, this library will throw an error. All errors are defined in [src/error.ts](./src/error.ts) and can be imported and tested for like so:\n\n```typescript\nimport { CognitoJwtVerifier } from \"aws-jwt-verify\";\nimport { JwtExpiredError } from \"aws-jwt-verify/error\";\n\nconst verifier = CognitoJwtVerifier.create({\n  userPoolId: \"\u003cuser_pool_id\u003e\",\n  tokenUse: \"access\",\n  clientId: \"\u003cclient_id\u003e\",\n});\n\ntry {\n  const payload = await verifier.verify(\n    \"eyJraWQeyJhdF9oYXNoIjoidk...\" // the JWT as string\n  );\n} catch (err) {\n  // An error is thrown, so the JWT is not valid\n  // Use `instanceof` to test for specific error cases:\n  if (err instanceof JwtExpiredError) {\n    console.error(\"JWT expired!\");\n  }\n  throw err;\n}\n```\n\n### Peek inside invalid JWTs\n\nIf you want to peek inside invalid JWTs, set `includeRawJwtInErrors` to `true` when creating the verifier. The thrown error will then include the raw JWT:\n\n```typescript\nimport { CognitoJwtVerifier } from \"aws-jwt-verify\";\nimport { JwtInvalidClaimError } from \"aws-jwt-verify/error\";\n\nconst verifier = CognitoJwtVerifier.create({\n  userPoolId: \"\u003cuser_pool_id\u003e\",\n  tokenUse: \"access\",\n  clientId: \"\u003cclient_id\u003e\",\n  includeRawJwtInErrors: true, // can also be specified as parameter to the `verify` call\n});\n\ntry {\n  const payload = await verifier.verify(\n    \"eyJraWQeyJhdF9oYXNoIjoidk...\" // the JWT as string\n  );\n} catch (err) {\n  if (err instanceof JwtInvalidClaimError) {\n    // You can log the payload of the raw JWT, e.g. to aid in debugging and alerting on authentication errors\n    // Be careful not to disclose information on the error reason to the the client\n    console.error(\"JWT invalid because:\", err.message);\n    console.error(\"Raw JWT:\", err.rawJwt.payload);\n  }\n  throw new Error(\"Unauthorized\");\n}\n```\n\nThe `instanceof` check in the `catch` block above is crucial, because not all errors will include the rawJwt, only errors that subclass `JwtInvalidClaimError` will. In order to understand why this makes sense, you should know that this library verifies JWTs in 3 stages, that all must succeed for the JWT to be considered valid:\n\n- Stage 1: Verify JWT structure and JSON parse the JWT\n- Stage 2: Verify JWT cryptographic signature (e.g. with algorithm ES256)\n- Stage 3: Verify JWT claims (such as e.g. its expiration)\n\nOnly in case of stage 3 verification errors, will the raw JWT be included in the error (if you set `includeRawJwtInErrors` to `true`). This way, when you look at the invalid raw JWT in the error, you'll know that its structure and signature are at least valid (stages 1 and 2 succeeded).\n\nNote that if you use [custom JWT checks](#custom-jwt-and-jwk-checks), you are in charge of throwing errors in your custom code. You can (optionally) subclass your errors from `JwtInvalidClaimError`, so that the raw JWT will be included on the errors you throw as well:\n\n```typescript\nimport { CognitoJwtVerifier } from \"aws-jwt-verify\";\nimport { JwtInvalidClaimError } from \"aws-jwt-verify/error\";\n\nclass CustomError extends JwtInvalidClaimError {}\n\nconst verifier = CognitoJwtVerifier.create({\n  userPoolId: \"\u003cuser_pool_id\u003e\",\n  tokenUse: \"access\",\n  clientId: \"\u003cclient_id\u003e\",\n  includeRawJwtInErrors: true,\n  customJwtCheck: ({ payload }) =\u003e {\n    if (payload.custom_claim !== \"expected\")\n      throw new CustomError(\"Invalid JWT\", payload.custom_claim, \"expected\");\n  },\n});\n\ntry {\n  const payload = await verifier.verify(\n    \"eyJraWQeyJhdF9oYXNoIjoidk...\" // the JWT as string\n  );\n} catch (err) {\n  if (err instanceof JwtInvalidClaimError) {\n    console.error(\"JWT invalid:\", err.rawJwt.payload);\n  }\n  throw new Error(\"Unauthorized\");\n}\n```\n\n## The JWKS cache\n\nThe JWKS cache is responsible for fetching the JWKS from the JWKS URI, caching it, and selecting the right JWK from it. Both the `CognitoJwtVerifier` and the (generic) `JwtVerifier` utilize an in-memory JWKS cache. For each `issuer` a JWKS cache is maintained, and each JWK in a JWKS is selected and cached using its `kid` (key id). The JWKS for an `issuer` will be fetched once initially, and thereafter only upon key rotations (detected by the occurrence of a JWT with a `kid` that is not yet in the cache).\n\nNote: examples below work the same for `CognitoJwtVerifier` and `JwtVerifier`.\n\n### Loading the JWKS from file\n\nIf e.g. your runtime environment doesn't have internet access, or you want to prevent the fetch over the network, you can load the JWKS explicitly yourself:\n\n```typescript\nimport { CognitoJwtVerifier } from \"aws-jwt-verify\";\nimport { readFileSync } from \"fs\";\n\nconst idTokenVerifier = CognitoJwtVerifier.create({\n  userPoolId: \"\u003cuser_pool_id\u003e\",\n  tokenUse: \"id\",\n  clientId: \"\u003cclient_id\u003e\",\n});\n\nconst jwks = JSON.parse(readFileSync(\"jwks.json\", { encoding: \"utf-8\" }));\nidTokenVerifier.cacheJwks(jwks);\n\n// Because the JWKS doesn't need to be downloaded now, you can use verifySync:\ntry {\n  const idTokenPayload = idTokenVerifier.verifySync(\n    \"eyJraWQeyJhdF9oYXNoIjoidk...\"\n  );\n  console.log(\"Token is valid. Payload:\", payload);\n} catch {\n  console.log(\"Token not valid!\");\n}\n\n// Async verify will of course work as well (and will use the cache also):\ntry {\n  const idTokenPayload = await idTokenVerifier.verify(\n    \"eyJraWQeyJhdF9oYXNoIjoidk...\"\n  );\n  console.log(\"Token is valid. Payload:\", idTokenPayload);\n} catch {\n  console.log(\"Token not valid!\");\n}\n```\n\nNote that the verifier will still try to fetch the JWKS, if it encounters a JWT with a kid that is not in it's cached JWKS (i.e. to cater for key rotations).\n\n### Rate limiting\n\nBoth the `CognitoJwtVerifier` and the `JwtVerifier` enforce a rate limit of 1 JWKS download per JWKS uri per 10 seconds. This protects users of this library from inadvertently flooding the JWKS uri with requests, and prevents wasting time doing network calls.\n\nThe rate limit works as follows (implemented by the `penaltyBox`, see below). When the verifier fetches the JWKS and fails to locate the JWT's kid in the JWKS, an error is thrown, and a timer of 10 seconds is started. Until that timer completes, the verifier will refuse to fetch the particular JWKS uri again. It will instead throw an error immediately on `verify` calls where that would require the JWKS to be downloaded.\n\nThe verifier will continue to verify JWTs for which the right JWK is already present in the cache, also it will still try other JWKS uris (for other issuers).\n\nIt is possible to implement a different rate limiting scheme yourself, by customizing the JWKS cache, or the `penaltyBox` implementation, see below.\n\n### Explicitly hydrating the JWKS cache\n\nIn a long running Node.js API (e.g. a Fargate container), it might make sense to hydrate the JWKS cache upon server start up. This will speed up the first JWT verification, as the JWKS doesn't have to be downloaded anymore.\n\nThis call will always fetch the current, latest, JWKS for each of the verifier's issuers (even though the JWKS might have been fetched and cached before):\n\n```typescript\nconst verifier = JwtVerifier.create([\n  {\n    issuer: \"https://example.com/idp1\",\n    audience: \"myappclient1\",\n  },\n  {\n    issuer: \"https://example.com/idp2\",\n    audience: \"myappclient2\",\n  },\n]);\n\n// Fetch and cache the JWKS for all configured issuers\nawait verifier.hydrate();\n```\n\nNote: it is only useful to call this method if your calling process has a time window, in which it might just as well fetch the JWKS. For example, during container start up, when the load balancer does not yet route traffic to the container. Calling this method in AWS Lambda functions only makes sense if you do it outside the Lambda handler, i.e. with a top-level await that is part of the code that runs during \"cold starts\". Awaiting `verifier.hydrate()` inside the Lambda handler will hurt performance as it always bypasses the existing cached JWKS.\n\n### Clearing the JWKS cache\n\nIf you have a predefined rotation schedule for your JWKS, you could set the refresh interval of the verifier aligned to this schedule:\n\n```typescript\nimport { JwtVerifier } from \"aws-jwt-verify\";\n\nconst verifier = JwtVerifier.create({\n  issuer: \"https://example.com/\",\n  audience: \"\u003caudience\u003e\",\n});\n\nsetInterval(\n  () =\u003e {\n    verifier.cacheJwks({ keys: [] }); // empty cache, by loading an empty JWKS\n  },\n  1000 * 60 * 60 * 4\n); // For a 4 hour refresh schedule\n```\n\nIf an automated rotation does not fit your use case, and you need to clear out the JWKS cache, you could use:\n\n```typescript\nverifier.cacheJwks({ keys: [] });\n```\n\n### Customizing the JWKS cache\n\nWhen you instantiate a `CognitoJwtVerifier` or `JwtVerifier` without providing a `JwksCache`, the `SimpleJwksCache` is used:\n\n```typescript\nimport { JwtVerifier } from \"aws-jwt-verify\";\nimport { SimpleJwksCache } from \"aws-jwt-verify/jwk\";\n\nconst verifier = JwtVerifier.create({\n  issuer: \"http://my-tenant.my-idp.com\",\n});\n\n// Equivalent:\nconst verifier2 = JwtVerifier.create(\n  {\n    issuer: \"http://my-tenant.my-idp.com\",\n  },\n  {\n    jwksCache: new SimpleJwksCache(),\n  }\n);\n```\n\nThe `SimpleJwksCache` can be tailored by using a different `penaltyBox` and/or `fetcher` (see below).\n\nAlternatively, you can implement an entirely custom `JwksCache` yourself, by creating a class that implements the interface `JwksCache` (from `\"aws-jwt-verify/jwk\"`). This allows for highly custom scenario's, e.g. you could implement a `JwksCache` with custom logic for selecting a JWK from the JWKS.\n\n### Sharing the JWKS cache amongst different verifiers\n\nIf you want to define multiple verifiers for the same JWKS uri, it makes sense to share the JWKS cache, so the JWKS will be downloaded and cached once:\n\n```typescript\nimport { JwtVerifier } from \"aws-jwt-verify\";\nimport { SimpleJwksCache } from \"aws-jwt-verify/jwk\";\n\nconst sharedJwksCache = new SimpleJwksCache();\n\nconst verifierA = JwtVerifier.create(\n  {\n    jwksUri: \"https://example.com/keys/jwks.json\",\n    issuer: \"https://example.com/\",\n    audience: \"\u003caudience\u003e\",\n  },\n  {\n    jwksCache: sharedJwksCache,\n  }\n);\n\nconst verifierB = JwtVerifier.create(\n  {\n    jwksUri: \"https://example.com/keys/jwks.json\", // same JWKS URI, so sharing cache makes sense\n    issuer: \"https://example.com/\",\n    audience: \"\u003caudience\u003e\",\n  },\n  {\n    jwksCache: sharedJwksCache,\n  }\n);\n```\n\n### Using a different `Fetcher` with `SimpleJwksCache`\n\nWhen instantiating `SimpleJwksCache`, the `fetcher` property can be populated with an instance of a class that implements the interface `Fetcher` (from `\"aws-jwt-verify/https\"`), such as the `SimpleFetcher` (which is the default).\n\nThe purpose of the fetcher, is to execute fetches against the JWKS uri (HTTPS GET) and return the response as an arraybuffer (that will be UTF-8 decoded and JSON parsed by the `SimpleJwksCache`).\nThe default implementation, the `SimpleFetcher`, has basic machinery to do fetches over HTTPS. It does 1 (immediate) retry in case of connection errors.\n\nBy supplying a custom fetcher when instantiating `SimpleJwksCache`, instead of `SimpleFetcher`, you can implement any retry and backoff scheme you want, or use another HTTPS library:\n\n```typescript\nimport { JwtVerifier } from \"aws-jwt-verify\";\nimport { SimpleJwksCache } from \"aws-jwt-verify/jwk\";\nimport { Fetcher } from \"aws-jwt-verify/https\";\nimport axios from \"axios\";\n\n// Use axios to do the HTTPS fetches\nclass CustomFetcher implements Fetcher {\n  instance = axios.create();\n  public async fetch(uri: string) {\n    return this.instance\n      .get(uri, { responseType: \"arraybuffer\" })\n      .then((response) =\u003e response.data);\n  }\n}\n\nconst verifier = JwtVerifier.create(\n  {\n    issuer: \"http://my-tenant.my-idp.com\",\n  },\n  {\n    jwksCache: new SimpleJwksCache({\n      fetcher: new CustomFetcher(),\n    }),\n  }\n);\n```\n\n### Using a different `JwksParser` with `SimpleJwksCache`\n\nThe default `JwksParser` takes the `ArrayBuffer` that the fetcher (see above) returns, and UTF-8 decodes and JSON parses it, and verifies it is a valid JWKS.\nIf your JWKS is non-standard, you can override the parser, giving you the option to do any transformations needed to make it a standard JWKS:\n\n```typescript\nimport { JwtVerifier } from \"aws-jwt-verify\";\nimport { SimpleJwksCache, assertIsJwks } from \"aws-jwt-verify/jwk\";\n\nconst verifier = JwtVerifier.create(\n  {\n    issuer: \"http://my-tenant.my-idp.com\",\n  },\n  {\n    jwksCache: new SimpleJwksCache({\n      jwksParser: (buf) =\u003e {\n        // This is roughly what the default JwksParser does,\n        // override with your own logic as needed:\n        const jwks = JSON.parse(new TextDecoder().decode(buf));\n        assertIsJwks(jwks);\n        return jwks;\n      },\n    }),\n  }\n);\n```\n\n### Configuring the JWKS response timeout and other HTTP options with `Fetcher`\n\nThe following configurations are equivalent, use the latter one to set a custom fetch timeout and other HTTP options.\n\n```typescript\nimport { CognitoJwtVerifier } from \"aws-jwt-verify\";\n\n// No jwksCache configured explicitly,\n// so the default `SimpleJwksCache` with `SimpleFetcher` will be used,\n// with a default response timeout of 3000 ms.:\nconst verifier = CognitoJwtVerifier.create({\n  userPoolId: \"\u003cuser_pool_id\u003e\",\n  tokenUse: \"access\", // or \"id\"\n  clientId: \"\u003cclient_id\u003e\",\n});\n```\n\nEquivalent explicit configuration:\n\n```typescript\nimport { CognitoJwtVerifier } from \"aws-jwt-verify\";\nimport { SimpleJwksCache } from \"aws-jwt-verify/jwk\";\nimport { Fetcher } from \"aws-jwt-verify/https\";\n\nconst verifier = CognitoJwtVerifier.create(\n  {\n    userPoolId: \"\u003cyour user pool id\u003e\",\n    tokenUse: \"access\", // or \"id\",\n    clientId: \"\u003cyour client id\u003e\",\n  },\n  {\n    jwksCache: new SimpleJwksCache({\n      fetcher: new SimpleFetcher({\n        defaultRequestOptions: {\n          responseTimeout: 3000,\n          // You can add additional request options:\n          // For NodeJS: https://nodejs.org/api/http.html#httprequestoptions-callback\n          // For Web (init object): https://developer.mozilla.org/en-US/docs/Web/API/fetch#syntax\n        },\n      }),\n    }),\n  }\n);\n```\n\n### Using a different `penaltyBox` with `SimpleJwksCache`\n\nWhen instantiating `SimpleJwksCache`, the `penaltyBox` property can be populated with an instance of a class that implements the interface `PenaltyBox` (from `\"aws-jwt-verify/jwk\"`), such as the `SimplePenaltyBox` (which is the default).\n\nThe `SimpleJwksCache` will always do `await penaltyBox.wait(jwksUri, kid)` before asking the `fetcher` to fetch the JWKS.\n\nBy supplying a custom penaltyBox when instantiating `SimpleJwksCache`, instead of `SimplePenaltyBox`, you can implement any waiting scheme you want, in your implementation of the `wait` function.\n\nThe `SimpleJwksCache` will call `penaltyBox.registerSuccessfulAttempt(jwksUri, kid)` when it succeeds in locating the right JWK in the JWKS, and call `penaltyBox.registerFailedAttempt(jwksUri, kid)` otherwise. You need to process these calls, so that you can determine the right amount of waiting in your `wait` implementation.\n\n```typescript\nimport { JwtVerifier } from \"aws-jwt-verify\";\nimport {\n  SimpleJwksCache,\n  SimplePenaltyBox,\n  PenaltyBox,\n} from \"aws-jwt-verify/jwk\";\n\n// In this example we use the SimplePenaltyBox, but override the default wait period\nconst verifier = JwtVerifier.create(\n  {\n    issuer: \"http://my-tenant.my-idp.com\",\n  },\n  {\n    jwksCache: new SimpleJwksCache({\n      penaltyBox: new SimplePenaltyBox({ waitSeconds: 1 }),\n    }),\n  }\n);\n\n// Or implement your own penaltyBox\n// The example here just stupidly waits 5 second always,\n// even on the first fetch of the JWKS uri\nclass CustomPenaltyBox implements PenaltyBox {\n  public async wait(jwksUri: string, kid: string) {\n    // implement something better\n    await new Promise((resolve) =\u003e setTimeout(resolve, 5000));\n  }\n  public registerFailedAttempt(jwksUri: string, kid: string) {\n    // implement\n  }\n  public registerSuccessfulAttempt(jwksUri: string, kid: string) {\n    // implement\n  }\n}\nconst verifier2 = JwtVerifier.create(\n  {\n    issuer: \"http://my-tenant.my-idp.com\",\n  },\n  {\n    jwksCache: new SimpleJwksCache({ penaltyBox: new CustomPenaltyBox() }),\n  }\n);\n```\n\n## Usage Examples\n\n### CloudFront Lambda@Edge\n\nThe verifier should be instantiated _outside_ the Lambda handler, so the verifier's cache can be reused for subsequent requests for as long as the Lambda functions stays \"hot\".\n\nThis is an example of a [Viewer Request Lambda@Edge](https://docs.aws.amazon.com/lambda/latest/dg/lambda-edge.html) function, that inspects each incoming request. It requires each incoming request to have a valid JWT (in this case an access token that includes scope \"read\") in the HTTP \"Authorization\" header.\n\n```javascript\nconst { CognitoJwtVerifier } = require(\"aws-jwt-verify\");\n\n// Create the verifier outside the Lambda handler (= during cold start),\n// so the cache can be reused for subsequent invocations. Then, only during the\n// first invocation, will the verifier actually need to fetch the JWKS.\nconst jwtVerifier = CognitoJwtVerifier.create({\n  userPoolId: \"\u003cuser_pool_id\u003e\",\n  tokenUse: \"access\",\n  clientId: \"\u003cclient_id\u003e\",\n  scope: \"read\",\n});\n\nexports.handler = async (event) =\u003e {\n  const { request } = event.Records[0].cf;\n  const accessToken = request.headers[\"authorization\"][0].value;\n  try {\n    await jwtVerifier.verify(accessToken);\n  } catch {\n    return {\n      status: \"403\",\n      body: \"Unauthorized\",\n    };\n  }\n  return request; // allow request to proceed\n};\n```\n\n### API Gateway Lambda Authorizer - REST\n\nThe verifier should be instantiated _outside_ the Lambda handler, so the verifier's cache can be reused for subsequent requests for as long as the Lambda functions stays \"hot\".\n\nTwo types of API Gateway Lambda authorizers could be created - token based and request-based. For both the types of authorizers, you could use the [AWS API Gateway Lambda Authorizer BluePrint](https://github.com/awslabs/aws-apigateway-lambda-authorizer-blueprints/blob/master/blueprints/nodejs/index.js) as a reference pattern where the [token validation](https://github.com/awslabs/aws-apigateway-lambda-authorizer-blueprints/blob/master/blueprints/nodejs/index.js#L17) could be achieved as follows\n\nFor token based authorizers, where lambda event payload is set to `Token` and token source is set to (http) `Header` with name `authorization`:\n\n```javascript\nconst { CognitoJwtVerifier } = require(\"aws-jwt-verify\");\n\n// Create the verifier outside the Lambda handler (= during cold start),\n// so the cache can be reused for subsequent invocations. Then, only during the\n// first invocation, will the verifier actually need to fetch the JWKS.\nconst jwtVerifier = CognitoJwtVerifier.create({\n  userPoolId: \"\u003cuser_pool_id\u003e\",\n  tokenUse: \"access\",\n  clientId: \"\u003cclient_id\u003e\",\n  scope: \"read\",\n});\n\nexports.handler = async (event) =\u003e {\n  const accessToken = event.authorizationToken;\n\n  let payload;\n  try {\n    // If the token is not valid, an error is thrown:\n    payload = await jwtVerifier.verify(accessToken);\n  } catch {\n    // API Gateway wants this *exact* error message, otherwise it returns 500 instead of 401:\n    throw new Error(\"Unauthorized\");\n  }\n\n  // Proceed with additional authorization logic\n  // ...\n};\n```\n\nFor request based authorizers, where lambda event payload is set to `Request` and identity source is set to (http) `Header` with name `authorization`:\n\n```javascript\nconst { CognitoJwtVerifier } = require(\"aws-jwt-verify\");\n\n// Create the verifier outside the Lambda handler (= during cold start),\n// so the cache can be reused for subsequent invocations. Then, only during the\n// first invocation, will the verifier actually need to fetch the JWKS.\nconst jwtVerifier = CognitoJwtVerifier.create({\n  userPoolId: \"\u003cuser_pool_id\u003e\",\n  tokenUse: \"access\",\n  clientId: \"\u003cclient_id\u003e\",\n  scope: \"read\",\n});\n\nexports.handler = async (event) =\u003e {\n  const accessToken = event.headers[\"authorization\"];\n\n  let payload;\n  try {\n    // If the token is not valid, an error is thrown:\n    payload = await jwtVerifier.verify(accessToken);\n  } catch {\n    // API Gateway wants this *exact* error message, otherwise it returns 500 instead of 401:\n    throw new Error(\"Unauthorized\");\n  }\n\n  // Proceed with additional authorization logic\n  // ...\n};\n```\n\n### HTTP API Lambda Authorizer\n\nAn example of a sample HTTP Lambda authorizer is included [here](tests/cognito/lib/lambda-authorizer/index.mjs) as part of the test suite for the solution ([format 2.0](https://docs.aws.amazon.com/apigateway/latest/developerguide/http-api-lambda-authorizer.html#http-api-lambda-authorizer.payload-format-response)).\n\n### AppSync Lambda Authorizer\n\nThe verifier should be instantiated _outside_ the Lambda handler, so the verifier's cache can be reused for subsequent requests for as long as the Lambda functions stays \"hot\".\n\nThis is an example of [AppSync Lambda Authorization](https://docs.aws.amazon.com/appsync/latest/devguide/security-authz.html#aws-lambda-authorization) function, that validates the JWT is valid (in this case an access token that includes scope \"read\") along with other authorization business logic\n\n```javascript\nconst { CognitoJwtVerifier } = require(\"aws-jwt-verify\");\n\n// Create the verifier outside the Lambda handler (= during cold start),\n// so the cache can be reused for subsequent invocations. Then, only during the\n// first invocation, will the verifier actually need to fetch the JWKS.\nconst jwtVerifier = CognitoJwtVerifier.create({\n  userPoolId: \"\u003cuser_pool_id\u003e\",\n  tokenUse: \"access\",\n  clientId: \"\u003cclient_id\u003e\",\n  scope: \"read\",\n});\n\nexports.handler = async (event) =\u003e {\n  const accessToken = event.authorizationToken;\n  try {\n    await jwtVerifier.verify(accessToken);\n  } catch {\n    return {\n      isAuthorized: false,\n    };\n  }\n  //Proceed with additional authorization logic\n};\n```\n\n### Fastify\n\n```javascript\nconst { CognitoJwtVerifier } = require(\"aws-jwt-verify\");\nconst fastify = require(\"fastify\")({ logger: true });\n\n// Create the verifier outside your route handlers,\n// so the cache is persisted and can be shared amongst them.\nconst jwtVerifier = CognitoJwtVerifier.create({\n  userPoolId: \"\u003cuser_pool_id\u003e\",\n  tokenUse: \"access\",\n  clientId: \"\u003cclient_id\u003e\",\n  scope: \"read\",\n});\n\nfastify.get(\"/\", async (request, reply) =\u003e {\n  try {\n    // A valid JWT is expected in the HTTP header \"authorization\"\n    await jwtVerifier.verify(request.headers.authorization);\n  } catch (authErr) {\n    fastify.log.error(authErr);\n    const err = new Error();\n    err.statusCode = 403;\n    throw err;\n  }\n  return { private: \"only visible to users sending a valid JWT\" };\n});\n\nconst startFastify = async () =\u003e {\n  try {\n    await fastify.listen(3000);\n  } catch (err) {\n    fastify.log.error(err);\n    process.exit(1);\n  }\n};\n\n// Hydrate the JWT verifier, and start Fastify.\n// Hydrating the verifier makes sure the JWKS is loaded into the JWT verifier,\n// so it can verify JWTs immediately without any latency.\n// (Alternatively, just start Fastify, the JWKS will be downloaded when the first JWT is being verified then)\nPromise.all([jwtVerifier.hydrate(), () =\u003e fastify.listen(3000)]).catch(\n  (err) =\u003e {\n    fastify.log.error(err);\n    process.exit(1);\n  }\n);\n```\n\n### Express\n\n```javascript\nconst { CognitoJwtVerifier } = require(\"aws-jwt-verify\");\nconst express = require(\"express\");\nconst app = express();\nconst port = 3000;\n\n// Create the verifier outside your route handlers,\n// so the cache is persisted and can be shared amongst them.\nconst jwtVerifier = CognitoJwtVerifier.create({\n  userPoolId: \"\u003cuser_pool_id\u003e\",\n  tokenUse: \"access\",\n  clientId: \"\u003cclient_id\u003e\",\n  scope: \"read\",\n});\n\napp.get(\"/\", async (req, res, next) =\u003e {\n  try {\n    // A valid JWT is expected in the HTTP header \"authorization\"\n    await jwtVerifier.verify(req.header(\"authorization\"));\n  } catch (err) {\n    console.error(err);\n    return res.status(403).json({ statusCode: 403, message: \"Forbidden\" });\n  }\n  res.json({ private: \"only visible to users sending a valid JWT\" });\n});\n\n// Hydrate the JWT verifier, then start express.\n// Hydrating the verifier makes sure the JWKS is loaded into the JWT verifier,\n// so it can verify JWTs immediately without any latency.\n// (Alternatively, just start express, the JWKS will be downloaded when the first JWT is being verified then)\njwtVerifier\n  .hydrate()\n  .catch((err) =\u003e {\n    console.error(`Failed to hydrate JWT verifier: ${err}`);\n    process.exit(1);\n  })\n  .then(() =\u003e\n    app.listen(port, () =\u003e {\n      console.log(`Example app listening at http://localhost:${port}`);\n    })\n  );\n```\n\n# Security\n\nSee [CONTRIBUTING](CONTRIBUTING.md#security-issue-notifications) for more information.\n\n# License\n\nThis project is licensed under the Apache-2.0 License.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fawslabs%2Faws-jwt-verify","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fawslabs%2Faws-jwt-verify","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fawslabs%2Faws-jwt-verify/lists"}