koa-jwt
Koa middleware that validates JSON Web Tokens and sets ctx.state.user
(by default) if a valid token is provided.
This module lets you authenticate HTTP requests using JSON Web Tokens
in your Koa (node.js) applications.
See this article
for a good introduction.
Install
$ npm install koa-jwt@koa2
Usage
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 opts.cookie
option
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:
The resolution order for the token is the following. The first non-empty token resolved will be the one that is verified.
opts.getToken
function- check the cookies (if
opts.cookie
is set) - check the Authorization header for a bearer token
Passing the secret
Normally you provide a single shared secret in opts.secret
, but another
alternative is to have an earlier middleware set ctx.state.secret
,
typically per request. If this property exists, it will be used instead
of the one in opts.secret
.
Example
var Koa = require('koa');
var jwt = require('koa-jwt');
var app = new Koa();
app.use(function(ctx, next){
return next().catch((err) => {
if (401 == err.status) {
ctx.status = 401;
ctx.body = 'Protected resource, use Authorization header to get access\n';
} else {
throw err;
}
});
});
app.use(function(ctx, next){
if (ctx.url.match(/^\/public/)) {
ctx.body = 'unprotected\n';
} else {
return next();
}
});
app.use(jwt({ secret: 'shared-secret' }));
app.use(function(ctx){
if (ctx.url.match(/^\/api/)) {
ctx.body = 'protected\n';
}
});
app.listen(3000);
Alternatively you can conditionally run the jwt
middleware under certain conditions:
var koa = require('koa');
var jwt = require('koa-jwt');
var app = new Koa();
app.use(jwt({ secret: 'shared-secret' }).unless({ path: [/^\/public/] }));
app.use(function(ctx, next){
if (ctx.url.match(/^\/public/)) {
ctx.body = 'unprotected\n';
} else {
return next();
}
});
app.use(function(ctx){
if (ctx.url.match(/^\/api/)) {
ctx.body = 'protected\n';
}
});
app.listen(3000);
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:
app.use(jwt({ secret: 'shared-secret', passthrough: true }));
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:
app.use(jwt({ secret: 'shared-secret', key: 'jwtdata' }));
This makes the decoded data available as ctx.state.jwtdata
.
You can specify audience and/or issuer as well:
app.use(jwt({ secret: 'shared-secret',
audience: 'http://myapi/protected',
issuer: 'http://issuer' }));
If the JWT has an expiration (exp
), it will be checked.
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.readFileSync('/path/to/public.pub');
app.use(jwt({ secret: publicKey }));
Related Modules
Note that koa-jwt exports the sign
, verify
and decode
functions from the above module as a convenience.
Tests
$ npm install
$ npm test
Author
Stian Grytøyr
Credits
This code is largely based on express-jwt.
Contributors
License
The MIT License