@fastify/jwt
![js-standard-style](https://img.shields.io/badge/code%20style-standard-brightgreen.svg?style=flat)
JWT utils for Fastify, internally it uses fast-jwt.
NOTE: The plugin has been migrated from using jsonwebtoken
to fast-jwt
. Even though fast-jwt
has 1:1 feature implementation with jsonwebtoken
, some exotic implementations might break. In that case please open an issue with details of your implementation. See Upgrading notes for more details about what changes this migration introduced.
@fastify/jwt
supports Fastify@3.
@fastify/jwt
v1.x
supports both Fastify@2.
Install
npm i @fastify/jwt --save
Usage
Register as a plugin. This will decorate your fastify
instance with the following methods: decode
, sign
, and verify
; refer to their documentation to find how to use the utilities. It will also register request.jwtVerify
and reply.jwtSign
. You must pass a secret
when registering the plugin.
const fastify = require('fastify')()
fastify.register(require('@fastify/jwt'), {
secret: 'supersecret'
})
fastify.post('/signup', (req, reply) => {
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 onRequest
hook 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)
}
})
Afterwards, just use request.user
in 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 onRequest
of a route to protect it & access the user information inside:
module.exports = async function(fastify, opts) {
fastify.get(
"/",
{
onRequest: [fastify.authenticate]
},
async function(request, reply) {
return request.user
}
)
}
Make sure that you also check @fastify/auth plugin for composing more complex strategies.
Auth0 tokens verification
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.
Options
secret
(required)
You must pass a secret
to the options
parameter. The secret
can be a primitive type String, a function that returns a String or an object { private, public }
.
In this object { private, public }
the private
key 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 algorithm
inside the signing options prefixed by the sign
key of the plugin registering options).
In this object { private, public }
the public
key is a string or buffer containing either the secret for HMAC algorithms, or the PEM encoded public key for RSA and ECDSA.
Function based secret
is supported by the request.jwtVerify()
and reply.jwtSign()
methods and is called with request
, token
, and callback
parameters.
Example
const { readFileSync } = require('fs')
const path = require('path')
const fastify = require('fastify')()
const jwt = require('@fastify/jwt')
fastify.register(jwt, { secret: 'supersecret' })
fastify.register(jwt, {
secret: function (request, token, callback) {
callback(null, 'supersecret')
}
})
fastify.register(jwt, {
secret: function (request, token) {
return Promise.resolve('supersecret')
}
})
fastify.register(jwt, {
secret: async function (request, token) {
return 'supersecret'
}
})
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' }
})
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/jwt
API if you do not override them.
Additionally, it is also possible to reject tokens selectively (i.e. blacklisting) by providing the option trusted
with the following signature: (request, decodedToken) => boolean|Promise<boolean>|SignPayloadType|Promise<SignPayloadType>
where request
is a FastifyRequest
and decodedToken
is the parsed (and verified) token information. Its result should be false
or Promise<false>
if the token should be rejected or, otherwise, be true
or Promise<true>
if the token should be accepted and, considering that request.user
will be used after that, the return should be decodedToken
itself.
Example
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')
},
decode: { complete: true },
sign: {
algorithm: 'ES256',
iss: 'api.example.tld'
},
verify: { allowedIss: 'api.example.tld' }
})
fastify.get('/decode', async (request, reply) => {
let altSignOptions = Object.assign({}, fastify.jwt.options.sign)
altSignOptions.iss = 'another.example.tld'
const token = await reply.jwtSign({ foo: 'bar' })
const tokenAlt = await reply.jwtSign({ foo: 'bar' }, altSignOptions)
const decodedToken = fastify.jwt.decode(token)
const decodedTokenAlt = fastify.jwt.decode(tokenAlt, { complete: false })
return { decodedToken, decodedTokenAlt }
})
fastify.listen(3000, err => {
if (err) throw err
})
cookie
Example using cookie
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 web app with the httpOnly
and secure
flags. Cookies can be susceptible to CSRF. You can mitigate this by either setting the sameSite
flag to strict
, or by using a CSRF library such as @fastify/csrf
.
Note: This plugin will look for a decorated request with the cookies
property. @fastify/cookie
supports 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):
- The request has both the authorization and cookie header
- Cookie is empty, authorization header is present
If you are signing your cookie, you can set the signed
boolean to true
which will make sure the JWT is verified using the unsigned value.
const fastify = require('fastify')()
const jwt = require('@fastify/jwt')
fastify.register(jwt, {
secret: 'foobar'
cookie: {
cookieName: 'token',
signed: false
}
})
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,
httpOnly: true,
sameSite: true
})
.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
})
trusted
Example trusted tokens
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
}
})
async function validateToken(request, decodedToken) {
const denylist = ['token1', 'token2']
return !denylist.includes(decodedToken.jti)
}
formatUser
Example with formatted user
You may customize the request.user
object 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}.`;
});
namespace
To define multiple JWT validators on the same routes, you may use the namespace
option.
You can combine this with custom names for jwtVerify
and jwtSign
.
When you omit the jwtVerify
and jwtSign
options, the default function name will be <namespace>JwtVerify
and <namespace>JwtSign
.
Example with namespace
const fastify = require('fastify')
fastify.register(jwt, {
secret: 'test',
namespace: 'security',
jwtVerify: 'securityVerify',
jwtSign: 'securitySign'
})
fastify.register(jwt, {
secret: 'fastify',
namespace: 'airDrop'
})
fastify.post('/sign/:namespace', async function (request, reply) {
switch (request.params.namespace) {
case 'security':
return reply.securitySign(request.body)
default:
return reply.airDropJwtSign(request.body)
}
})
messages
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.
Example
const fastify = require('fastify')
const myCustomMessages = {
badRequestErrorMessage: 'Format is Authorization: Bearer [token]',
noAuthorizationInHeaderMessage: 'Autorization header is missing!',
authorizationTokenExpiredMessage: 'Authorization token expired',
authorizationTokenInvalid: (err) => {
return `Authorization token is invalid: ${err.message}`
}
}
fastify.register(require('@fastify/jwt'), {
secret: 'supersecret',
messages: myCustomMessages
})
decode
complete
: Return an object with the decoded header, payload, signature and input (the token part before the signature), instead of just the content of the payload. Default is false
.checkTyp
: When validating the decoded header, setting this option forces the check of the typ property against this value. Example: checkTyp: 'JWT'
. Default is undefined
.
sign
-
key
: A string or a buffer containing the secret for HS*
algorithms or the PEM encoded public key for RS*
, PS*
, ES*
and EdDSA
algorithms. The key can also be a function accepting a Node style callback or a function returning a promise. If provided, it will override the value of secret provided in the options.
-
algorithm
: The algorithm to use to sign the token. The default is autodetected from the key, using RS256 for RSA private keys, HS256 for plain secrets and the correspondent ES or EdDSA algorithms for EC or Ed* private keys.
-
mutatePayload
: If set to true
, the original payload will be modified in place (via Object.assign
) by the signing function. 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.
-
expiresIn
: Time span after which the token expires, added as the exp
claim in the payload. It is expressed in seconds or a string describing a time span (E.g.: 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"
). This will override any existing value in the claim.
-
notBefore
: Time span before the token is active, added as the nbf
claim in the payload. It is expressed in seconds or a string describing a time span (E.g.: 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"
). This will override any existing value in the claim.
-
... the rest of the sign options can be found here.
verify
key
: A string or a buffer containing the secret for HS*
algorithms or the PEM encoded public key for RS*
, PS*
, ES*
and EdDSA
algorithms. The key can also be a function accepting a Node style callback or a function returning a promise. If provided, it will override the value of secret provided in the options.algorithms
: List of strings with the names of the allowed algorithms. By default, all algorithms are accepted.complete
: Return an object with the decoded header, payload, signature and input (the token part before the signature), instead of just the content of the payload. Default is false
.cache
: A positive number specifying the size of the verified tokens cache (using LRU strategy). Setting this to true
is equivalent to provide the size 1000. When enabled the performance is dramatically improved. By default the cache is disabled.cacheTTL
: The maximum time to live of a cache entry (in milliseconds). If the token has a earlier expiration or the verifier has a shorter maxAge
, the earlier takes precedence. The default is 600000
, which is 10 minutes.maxAge
: The maximum allowed age for tokens to still be valid. It is expressed in seconds or a string describing a time span (E.g.: 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"
). By default this is not checked.- ... the rest of the verify options can be found here.
API Spec
fastify.jwt.sign(payload [,options] [,callback])
This method is used to sign the provided payload
. It returns the token.
The payload
must be an Object
. Can be used asynchronously by passing a callback function; synchronously without a callback.
options
must be an Object
and can contain sign options.
fastify.jwt.verify(token, [,options] [,callback])
This method is used to verify provided token. It accepts a token
(as Buffer
or a string
) and returns the payload or the sections of the token. Can be used asynchronously by passing a callback function; synchronously without a callback.
options
must be an Object
and can contain verify options.
Example
const token = fastify.jwt.sign({ foo: 'bar' })
const decoded = fastify.jwt.verify(token)
fastify.jwt.verify(token, (err, decoded) => {
if (err) fastify.log.error(err)
fastify.log.info(`Token verified. Foo is ${decoded.foo}`)
})
fastify.jwt.decode(token [,options])
This method is used to decode the provided token. It accepts a token (as a Buffer
or a string
) and returns the payload or the sections of the token.
options
must be an Object
and can contain decode options.
Can only be used synchronously.
Example
const token = fastify.jwt.sign({ foo: 'bar' })
const decoded = fastify.jwt.decode(token)
fastify.log.info(`Decoded JWT: ${decoded}`)
fastify.jwt.options
For your convenience, the decode
, sign
, verify
and messages
options you specify during .register
are made available via fastify.jwt.options
that will return an object { decode, sign, verify, messages }
containing your options.
Example
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',
aud: 'foo',
iss: 'example.tld'
},
verify: {
allowedAud: 'foo',
allowedIss: 'example.tld',
}
})
fastify.get('/', (request, reply) => {
const globalOptions = fastify.jwt.options
let modifiedVerifyOptions = Object.assign({}, fastify.jwt.options.verify)
modifiedVerifyOptions.allowedAud = 'bar'
modifiedVerifyOptions.allowedSub = 'test'
return { globalOptions, modifiedVerifyOptions }
})
fastify.listen(3000, err => {
if (err) throw err
})
fastify.jwt.cookie
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.
reply.jwtSign(payload, [options,] callback)
options
must be an Object
and can contain sign
options.
request.jwtVerify([options,] callback)
options
must be an Object
and can contain verify
and decode
options.
request.jwtDecode([options,] callback)
Decode a JWT without verifying
As of 3.2.0, decorated when options.jwtDecode
is truthy. Will become non-conditionally decorated in 4.0.0. This avoid breaking change that would effect fastify-auth0-verify.
options
must be an Object
and can contain verify
and decode
options.
Algorithms supported
The following algorithms are currently supported by fast-jwt that is internally used by @fastify/jwt
.
Name | Description |
---|
none | Empty algorithm - The token signature section will be empty |
HS256 | HMAC using SHA-256 hash algorithm |
HS384 | HMAC using SHA-384 hash algorithm |
HS512 | HMAC 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 |
RS256 | RSASSA-PKCS1-v1_5 using SHA-256 hash algorithm |
RS384 | RSASSA-PKCS1-v1_5 using SHA-384 hash algorithm |
RS512 | RSASSA-PKCS1-v1_5 using SHA-512 hash algorithm |
PS256 | RSASSA-PSS using SHA-256 hash algorithm |
PS384 | RSASSA-PSS using SHA-384 hash algorithm |
PS512 | RSASSA-PSS using SHA-512 hash algorithm |
EdDSA | EdDSA tokens using Ed25519 or Ed448 keys, only supported on Node.js 12+ |
You can find the list here.
Examples
Certificates Generation
Here some example on how to generate certificates and use them, with or without passphrase.
Signing and verifying (jwtSign, jwtVerify)
const fastify = require('fastify')()
const jwt = require('@fastify/jwt')
const request = require('request')
fastify.register(jwt, {
secret: function (request, reply, callback) {
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}`)
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}`)
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}`)
})
})
})
Verifying with JWKS
The following example integrates the get-jwks package to fetch a JWKS and verify a JWT against a valid public JWK.
Example
const Fastify = require('fastify')
const fjwt = require('@fastify/jwt')
const buildGetJwks = require('get-jwks')
const fastify = Fastify()
const getJwks = buildGetJwks()
fastify.register(fjwt, {
decode: { complete: true },
secret: (request, token) => {
const { header: { kid, alg }, payload: { iss } } = token
return getJwks.getPublicKey({ kid, domain: iss, alg })
}
})
fastify.addHook('onRequest', async (request, reply) => {
try {
await request.jwtVerify()
} catch (err) {
reply.send(err)
}
})
fastify.listen(3000)
TypeScript
This plugin has two available exports, the default plugin function fastifyJwt
and the plugin options object FastifyJWTOptions
.
Import them like so:
import fastifyJwt, { FastifyJWTOptions } from '@fastify/jwt'
Define custom Payload Type and Attached User Type to request object
typescript declaration merging
import "@fastify/jwt"
declare module "@fastify/jwt" {
interface FastifyJWT {
payload: { id: number }
user: {
id: number,
name: string,
age: number
}
}
}
fastify.get('/', async (request, reply) => {
request.user.name
const token = await reply.jwtSign({
id: '123'
});
})
Acknowledgements
This project is kindly sponsored by:
License
Licensed under MIT.