Table of Contents
This module lets you authenticate HTTP requests using JSON Web Tokens in your Koa (node.js) applications.
See this article for a good introduction.
- If you are using
koaversion 2+, and you have a version of node < 7.6, install
koa-jwtversion 3+ on the master branch uses
awaitand hence requires node >= 7.6.
- If you are using
koaversion 1, you need to install
koa-jwt@1from npm. This is the code on the koa-v1 branch.
npm install koa-jwt
The JWT authentication middleware authenticates callers using a JWT
token. If the token is valid,
ctx.state.user (by default) will be set
with the JSON object decoded to be used by later middleware for
authorization and access control.
Retrieving the token
The token is normally provided in a HTTP header (
Authorization), but it
can also be provided in a cookie by setting the
to the name of the cookie that contains the token. Custom token retrieval
can also be done through the
opts.getToken option. The provided function
should match the following interface:
/*** Your custom token resolver* @this The ctx object passed to the middleware** @param* @return*/
The resolution order for the token is the following. The first non-empty token resolved will be the one that is verified.
- check the cookies (if
- check the Authorization header for a bearer token
Passing the secret
One can provide a single secret, or array of secrets in
alternative is to have an earlier middleware set
typically per request. If this property exists, it will be used instead
Checking if the token is revoked
You can provide a async function to jwt for it check the token is revoked.
Only you set the function in
opts.isRevoked. The provided function should
match the following interface:
/*** Your custom isRevoked resolver** @param* @param* @param* @return*/
var Koa = ;var jwt = ;var app = ;// Custom 401 handling if you don't want to expose koa-jwt errors to usersapp;// Unprotected middlewareapp;// Middleware below this line is only reached if JWT token is validapp;// Protected middlewareapp;app;
Alternatively you can conditionally run the
jwt middleware under certain conditions:
var koa = ;var jwt = ;var app = ;// Middleware below this line is only reached if JWT token is valid// unless the URL starts with '/public'app;// Unprotected middlewareapp;// Protected middlewareapp;app;
For more information on
unless exceptions, check koa-unless.
You can also add the
passthrough option to always yield next,
even if no valid Authorization header was found:
This lets downstream middleware make decisions based on whether
ctx.state.user is set.
If you prefer to use another ctx key for the decoded data, just pass in
key, like so:
This makes the decoded data available as
You can specify audience and/or issuer as well:
You can specify an array of secrets.
The token will be considered valid if it validates successfully against any of the supplied secrets. This allows for rolling shared secrets, for example:
Token Verification Exceptions
If the JWT has an expiration (
exp), it will be checked.
All error codes for token verification can be found at: https://github.com/auth0/node-jsonwebtoken#errors--codes.
Notifying a client of error codes (e.g token expiration) can be achieved by sending the
err.originalError.message error code to the client.
// Custom 401 handling (first middleware)app;
tokenKey option is present, and a valid token is found, the original raw token
is made available to subsequent middleware as
This module also support tokens signed with public/private key pairs. Instead of a secret, you can specify a Buffer with the public key:
var publicKey = fs;app;
secret option is a function, this function is called for each JWT received in
order to determine which secret is used to verify the JWT.
The signature of this function should be
(header, payload) => [Promise(secret)], where
header is the token header and
payload is the token payload. For instance to support JWKS token header should contain
kid: algorithm and key id fields respectively.
This option can be used to support JWKS (JSON Web Key Set) providers by using node-jwks-rsa. For example:
const koaJwtSecret = ;app;
- jsonwebtoken — JSON Web Token signing and verification
Note that koa-jwt no longer exports the
decode functions from
jsonwebtoken in the koa-v2 branch.
npm installnpm test
The initial code was largely based on express-jwt.