JWT utils for Fastify
JWT utils for Fastify, internally uses jsonwebtoken.
fastify-jwtsupports [email protected]
fastify-jwtv1.x supports both [email protected]
npm i fastify-jwt --save
Register as a plugin. This will decorate your
fastifyinstance with the standard jsonwebtoken methods
decode,
sign, and
verify; refer to their documentation to find how to use the utilities. It will also register
request.jwtVerifyand
reply.jwtSign. You must pass a
secretwhen registering the plugin.
const fastify = require('fastify')() fastify.register(require('fastify-jwt'), { secret: 'supersecret' })fastify.post('/signup', (req, reply) => { // some code const token = fastify.jwt.sign({ payload }) reply.send({ token }) })
fastify.listen(3000, err => { if (err) throw err })
For verifying & accessing the decoded token inside your services, you can use a global
onRequesthook to define the verification process like so:
const fastify = require('fastify')() fastify.register(require('fastify-jwt'), { secret: 'supersecret' })fastify.addHook("onRequest", async (request, reply) => { try { await request.jwtVerify() } catch (err) { reply.send(err) } })
Aftewards, just use
request.userin order to retrieve the user information:
module.exports = async function(fastify, opts) { fastify.get("/", async function(request, reply) { return request.user }) }
However, most of the time we want to protect only some of the routes in our application. To achieve this you can wrap your authentication logic into a plugin like
const fp = require("fastify-plugin")module.exports = fp(async function(fastify, opts) { fastify.register(require("fastify-jwt"), { secret: "supersecret" })
fastify.decorate("authenticate", async function(request, reply) { try { await request.jwtVerify() } catch (err) { reply.send(err) } }) })
Then use the
preValidationof a route to protect it & access the user information inside:
module.exports = async function(fastify, opts) { fastify.get( "/", { preValidation: [fastify.authenticate] }, async function(request, reply) { return request.user } ) }
Make sure that you also check fastify-auth plugin for composing more complex strategies.
If you need to verify Auth0 issued HS256 or RS256 JWT tokens, you can use fastify-auth0-verify, which is based on top of this module.
fastify-jwtis a fastify plugin. You must pass a
secretto the
optionsparameter. The
secretcan be a primitive type String, a function that returns a String or an object
{ private, public }.
In this object
{ private, public }the
privatekey is a string, buffer or object containing either the secret for HMAC algorithms or the PEM encoded private key for RSA and ECDSA. In case of a private key with passphrase an object
{ private: { key, passphrase }, public }can be used (based on crypto documentation), in this case be sure you pass the
algorithminside the signing options prefixed by the
signkey of the plugin registering options).
In this object
{ private, public }the
publickey is a string or buffer containing either the secret for HMAC algorithms, or the PEM encoded public key for RSA and ECDSA.
Function based
secretis supported by the
request.jwtVerify()and
reply.jwtSign()methods and is called with
request,
token, and
callbackparameters.
const { readFileSync } = require('fs') const path = require('path') const fastify = require('fastify')() const jwt = require('fastify-jwt') // secret as a string fastify.register(jwt, { secret: 'supersecret' }) // secret as a function fastify.register(jwt, { secret: function (request, token, callback) { // do something callback(null, 'supersecret') } }) // secret as an object of RSA keys (without passphrase) // the files are loaded as strings fastify.register(jwt, { secret: { private: readFileSync(`${path.join(__dirname, 'certs')}/private.key`, 'utf8'), public: readFileSync(`${path.join(__dirname, 'certs')}/public.key`, 'utf8') }, sign: { algorithm: 'RS256' } }) // secret as an object of P-256 ECDSA keys (with a passphrase) // the files are loaded as buffers fastify.register(jwt, { secret: { private: { key: readFileSync(`${path.join(__dirname, 'certs')}/private.pem`), passphrase: 'super secret passphrase' }, public: readFileSync(`${path.join(__dirname, 'certs')}/public.pem`) }, sign: { algorithm: 'ES256' } })
Optionally you can define global default options that will be used by
fastify-jwtAPI if you don't override them.
Additionally, it is also possible to reject tokens selectively (i.e: black-listing) by providing the option
trustedwith the following signature:
(request, decodedToken) => boolean|Promise|SignPayloadType|Promisewhere
requestis a
FastifyRequestand
decodedTokenis the parsed (and verified) token information. Its result should be
falseor
Promiseif the token should be rejected or, otherwise, be
trueor
Promiseif the token should be accepted and, considering that
request.userwill be used after that, the return should be
decodedTokenitself.
const { readFileSync } = require('fs') const path = require('path') const fastify = require('fastify')() const jwt = require('fastify-jwt') fastify.register(jwt, { secret: { private: readFileSync(`${path.join(__dirname, 'certs')}/private.pem`, 'utf8') public: readFileSync(`${path.join(__dirname, 'certs')}/public.pem`, 'utf8') }, // Global default decoding method options decode: { complete: true }, // Global default signing method options sign: { algorithm: 'ES256', issuer: 'api.example.tld' }, // Global default verifying method options verify: { issuer: 'api.example.tld' } })fastify.get('/decode', async (request, reply) => { // We clone the global signing options before modifying them let altSignOptions = Object.assign({}, fastify.jwt.options.sign) altSignOptions.issuer = 'another.example.tld'
// We generate a token using the default sign options const token = await reply.jwtSign({ foo: 'bar' }) // We generate a token using overrided options const tokenAlt = await reply.jwtSign({ foo: 'bar' }, altSignOptions)
// We decode the token using the default options const decodedToken = fastify.jwt.decode(token)
// We decode the token using completely overided the default options const decodedTokenAlt = fastify.jwt.decode(tokenAlt, { complete: false })
return { decodedToken, decodedTokenAlt } /**
"header": {
"alg": "ES256",
"typ": "JWT"
},
"payload": {
"foo": "bar",
"iat": 1540305336
"iss": "api.example.tld"
},
"signature": "gVf5bzROYB4nPgQC0nbJTWCiJ3Ya51cyuP-N50cidYo"
"foo": "bar",
"iat": 1540305337
"iss": "another.example.tld"
fastify.listen(3000, err => { if (err) throw err })
In some situations you may want to store a token in a cookie. This allows you to drastically reduce the attack surface of XSS on your webapp with the
httpOnlyand
secureflags. Cookies can be susceptible to CSRF. You can mitigate this by either setting the
sameSiteflag to
strict, or by using a CSRF library such as
fastify-csrf.
Note: This plugin will look for a decorated request with the
cookiesproperty.
fastify-cookiesupports this feature, and therefore you should use it when using the cookie feature. The plugin will fallback to looking for the token in the authorization header if either of the following happens (even if the cookie option is enabled):
const fastify = require('fastify')() const jwt = require('fastify-jwt')fastify.register(jwt, { secret: 'foobar' cookie: { cookieName: 'token' } })
fastify .register(require('fastify-cookie'))
fastify.get('/cookies', async (request, reply) => { const token = await reply.jwtSign({ name: 'foo', role: ['admin', 'spy'] })
reply .setCookie('token', token, { domain: 'your.domain', path: '/', secure: true, // send cookie over HTTPS only httpOnly: true, sameSite: true // alternative CSRF protection }) .code(200) .send('Cookie sent') })
fastify.addHook('onRequest', (request) => request.jwtVerify())
fastify.get('/verifycookie', (request, reply) => { reply.send({ code: 'OK', message: 'it works!' }) })
fastify.listen(3000, err => { if (err) throw err })
const fastify = require('fastify')()fastify.register(require('fastify-jwt'), { secret: 'foobar', trusted: validateToken })
fastify.addHook('onRequest', (request) => request.jwtVerify())
fastify.get('/', (request, reply) => { reply.send({ code: 'OK', message: 'it works!' }) })
fastify.listen(3000, (err) => { if (err) { throw err } })
// ideally this function would do a query against some sort of storage to determine its outcome
async function validateToken(request, decodedToken) { const denylist = ['token1', 'token2']return !denylist.includes(decodedToken.jti) }
You may customize the
request.userobject setting a custom sync function as parameter:
const fastify = require('fastify')(); fastify.register(require('fastify-jwt'), { formatUser: function (user) { return { departmentName: user.department_name name: user.name } }, secret: 'supersecret' });fastify.addHook('onRequest', (request, reply) => request.jwtVerify());
fastify.get("/", async (request, reply) => { return
Hello, ${request.user.name} from ${request.user.departmentName}.
; });
The
signmethod is an implementation of jsonwebtoken
.sign(). Can be used asynchronously by passing a callback function; synchronously without a callback.
The
verifymethod is an implementation of jsonwebtoken
.verify(). Can be used asynchronously by passing a callback function; synchronously without a callback.
const token = fastify.jwt.sign({ foo: 'bar' }) // synchronously const decoded = fastify.jwt.verify(token) // asycnhronously fastify.jwt.verify(token, (err, decoded) => { if (err) fastify.log.error(err) fastify.log.info(`Token verified. Foo is ${decoded.foo}`) })
The
decodemethod is an implementation of jsonwebtoken
.decode(). Can only be used synchronously.
const token = fastify.jwt.sign({ foo: 'bar' }) const decoded = fastify.jwt.decode(token) fastify.log.info(`Decoded JWT: ${decoded}`)
For your convenience, the
decode,
sign,
verifyand
messagesoptions you specify during
.registerare made available via
fastify.jwt.optionsthat will return an object
{ decode, sign, verify, messages }containing your options.
const { readFileSync } = require('fs') const path = require('path') const fastify = require('fastify')() const jwt = require('fastify-jwt') fastify.register(jwt, { secret: { private: readFileSync(`${path.join(__dirname, 'certs')}/private.key`), public: readFileSync(`${path.join(__dirname, 'certs')}/public.key`) }, sign: { algorithm: 'RS256', audience: 'foo', issuer: 'example.tld' }, verify: { audience: 'foo', issuer: 'example.tld', } })fastify.get('/', (request, reply) => { const globalOptions = fastify.jwt.options
// We recommend that you clone the options like this when you need to mutate them // modifiedVerifyOptions = { audience: 'foo', issuer: 'example.tld' } let modifiedVerifyOptions = Object.assign({}, fastify.jwt.options.verify) modifiedVerifyOptions.audience = 'bar' modifiedVerifyOptions.subject = 'test'
return { globalOptions, modifiedVerifyOptions } /**
decode: {},
sign: {
algorithm: 'RS256',
audience: 'foo',
issuer: 'example.tld'
},
verify: {
audience: 'foo',
issuer: 'example.tld'
}
audience: 'bar',
issuer: 'example.tld',
subject: 'test'
fastify.listen(3000, err => { if (err) throw err })
json: force JSON.parse on the payload even if the header doesn't contain
"typ":"JWT".
complete: return an object with the decoded payload and header.
algorithm(default:
HS256)
expiresIn: expressed in seconds or a string describing a time span zeit/ms. Eg:
60,
"2 days",
"10h",
"7d". A numeric value is interpreted as a seconds count. If you use a string be sure you provide the time units (days, hours, etc), otherwise milliseconds unit is used by default (
"120"is equal to
"120ms").
notBefore: expressed in seconds or a string describing a time span zeit/ms. Eg:
60,
"2 days",
"10h",
"7d". A numeric value is interpreted as a seconds count. If you use a string be sure you provide the time units (days, hours, etc), otherwise milliseconds unit is used by default (
"120"is equal to
"120ms").
audience
issuer
jwtid
subject
noTimestamp
header
keyid
mutatePayload: if true, the sign function will modify the payload object directly. This is useful if you need a raw reference to the payload after claims have been applied to it but before it has been encoded into a token.
algorithms: List of strings with the names of the allowed algorithms. For instance,
["HS256", "HS384"].
audience: if you want to check audience (
aud), provide a value here. The audience can be checked against a string, a regular expression or a list of strings and/or regular expressions. Eg:
"urn:foo",
/urn:f[o]{2}/,
[/urn:f[o]{2}/, "urn:bar"]
issuer(optional): string or array of strings of valid values for the
issfield.
ignoreExpiration: if
truedo not validate the expiration of the token.
ignoreNotBefore...
subject: if you want to check subject (
sub), provide a value here
clockTolerance: number of seconds to tolerate when checking the
nbfand
expclaims, to deal with small clock differences among different servers
maxAge: the maximum allowed age for tokens to still be valid. It is expressed in seconds or a string describing a time span zeit/ms. Eg:
1000,
"2 days",
"10h",
"7d". A numeric value is interpreted as a seconds count. If you use a string be sure you provide the time units (days, hours, etc), otherwise milliseconds unit is used by default (
"120"is equal to
"120ms").
clockTimestamp: the time in seconds that should be used as the current time for all necessary comparisons.
extractToken(request): token: Callback function allowing to use custom logic to extract the JWT token from the request.
For your convenience, you can override the default HTTP response messages sent when an unauthorized or bad request error occurs. You can choose the specific messages to override and the rest will fallback to the default messages. The object must be in the format specified in the example below.
const fastify = require('fastify')const myCustomMessages = { badRequestErrorMessage: 'Format is Authorization: Bearer [token]', noAuthorizationInHeaderMessage: 'Autorization header is missing!', authorizationTokenExpiredMessage: 'Authorization token expired', // for the below message you can pass a sync function that must return a string as shown or a string authorizationTokenInvalid: (err) => { return
Authorization token is invalid: ${err.message}
} }fastify.register(require('fastify-jwt'), { secret: 'supersecret', messages: myCustomMessages })
For your convenience, the
secretyou specify during
.registeris made available via
fastify.jwt.secret.
request.jwtVerify()and
reply.jwtSign()will wrap non-function secrets in a callback function.
request.jwtVerify()and
reply.jwtSign()use an asynchronous waterfall method to retrieve your secret. It's recommended that your use these methods if your
secretmethod is asynchronous.
For your convenience,
request.jwtVerify()will look for the token in the cookies property of the decorated request. You must specify
cookieName. Refer to the cookie example to see sample usage and important caveats.
These methods are very similar to their standard jsonwebtoken counterparts.
const fastify = require('fastify')() const jwt = require('fastify-jwt') const request = require('request')fastify.register(jwt, { secret: function (request, reply, callback) { // do something callback(null, 'supersecret') } })
fastify.post('/sign', function (request, reply) { reply.jwtSign(request.body.payload, function (err, token) { return reply.send(err || { 'token': token }) }) })
fastify.get('/verify', function (request, reply) { request.jwtVerify(function (err, decoded) { return reply.send(err || decoded) }) })
fastify.listen(3000, function (err) { if (err) fastify.log.error(err) fastify.log.info(
Server live on port: ${fastify.server.address().port}
)// sign payload and get JWT request({ method: 'POST', headers: { 'Content-Type': 'application/json' }, body: { payload: { foo: 'bar' } }, uri:
http://localhost:${fastify.server.address().port}/sign
, json: true }, function (err, response, body) { if (err) fastify.log.error(err) fastify.log.info(JWT token is ${body.token}
)// verify JWT request({ method: 'GET', headers: { 'Content-Type': 'application/json', authorization: 'Bearer ' + body.token }, uri: 'http://localhost:' + fastify.server.address().port + '/verify', json: true }, function (err, response, body) { if (err) fastify.log.error(err) fastify.log.info(`JWT verified. Foo is ${body.foo}`) })
}) })
The following algorithms are currently supported by jsonwebtoken that is internally used by
fastify-jwt.
algorithm(s) Parameter Value |
Digital Signature or MAC Algorithm |
---|---|
HS256 | HMAC using SHA-256 hash algorithm |
HS384 | HMAC using SHA-384 hash algorithm |
HS512 | HMAC using SHA-512 hash algorithm |
RS256 | RSASSA using SHA-256 hash algorithm |
RS384 | RSASSA using SHA-384 hash algorithm |
RS512 | RSASSA using SHA-512 hash algorithm |
ES256 | ECDSA using P-256 curve and SHA-256 hash algorithm |
ES384 | ECDSA using P-384 curve and SHA-384 hash algorithm |
ES512 | ECDSA using P-521 curve and SHA-512 hash algorithm |
none | No digital signature or MAC value included |
This plugin has two available exports, the default plugin function
fastifyJwtand the plugin options object
FastifyJWTOptions.
Import them like so:
import fastifyJwt, { FastifyJWTOptions } from 'fastify-jwt'
Define custom Payload Type
declare "fastify-jwt" { interface FastifyJWT { payload: { name: string } } }fastify.get('/', async (request, replay) => { request.user.name // string
const token = await replay.jwtSign({ name: 123 // ^ Type 'number' is not assignable to type 'string'. }); })
This project is kindly sponsored by: - LetzDoIt
Licensed under MIT.