A RetroSearch Logo

Home - News ( United States | United Kingdom | Italy | Germany ) - Football scores

Search Query:

Showing content from https://github.com/fastify/fastify-jwt below:

fastify/fastify-jwt: JWT utils for Fastify

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.

Register as a plugin. This will decorate your fastify instance with the following methods: decode, sign, and verify; refer to their documentation to find out 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) => {
  // some code
  const token = fastify.jwt.sign({ payload })
  reply.send({ token })
})

fastify.listen({ port: 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 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.

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.

In cases where your incoming JWT tokens are issued by a trusted external service, and you need only to verify their signature without issuing, there is an option to configure fastify-jwt in verify-only mode by passing the secret object containing only a public key: { public }.

When only a public key is provided, decode and verification functions will work as described below, but an exception will be thrown at an attempt to use any form of sign functionality.

const { readFileSync } = require('node:fs')
const path = require('node:path')
const fastify = require('fastify')()
const jwt = require('@fastify/jwt')
// secret as a string
fastify.register(jwt, { secret: 'supersecret' })
// secret as a function with callback
fastify.register(jwt, {
  secret: function (request, token, callback) {
    // do something
    callback(null, 'supersecret')
  }
})
// secret as a function returning a promise
fastify.register(jwt, {
  secret: function (request, token) {
    return Promise.resolve('supersecret')
  }
})
// secret as an async function
fastify.register(jwt, {
  secret: async function (request, token) {
    return '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' }
})
// secret as an object with RSA public key
// fastify-jwt is configured in VERIFY-ONLY mode
fastify.register(jwt, {
  secret: {
    public: process.env.JWT_ISSUER_PUBKEY
  }
})

Optionally you can define global default options that will be used by @fastify/jwt API if you do not override them.

const { readFileSync } = require('node:fs')
const path = require('node: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',
    iss: 'api.example.tld'
  },
  // Global default verifying method options
  verify: { allowedIss: '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.iss = '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 }
  /**
   * Will return:
   *
   * {
   *   "decodedToken": {
   *     "header": {
   *       "alg": "ES256",
   *       "typ": "JWT"
   *     },
   *     "payload": {
   *       "foo": "bar",
   *       "iat": 1540305336
   *       "iss": "api.example.tld"
   *     },
   *     "signature": "gVf5bzROYB4nPgQC0nbJTWCiJ3Ya51cyuP-N50cidYo"
   *   },
   *   decodedTokenAlt: {
   *     "foo": "bar",
   *     "iat": 1540305337
   *     "iss": "another.example.tld"
   *   },
   * }
   */
})

fastify.listen({ port: 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 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):

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, // 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({ port: 3000 }, err => {
  if (err) throw err
})

Setting this option to true will decode only the cookie in the request. This is useful for refreshToken implementations where the request typically has two tokens: token and refreshToken. The main authentication token usually has a shorter timeout and the refresh token normally stored in the cookie has a longer timeout. This allows you to check to make sure that the cookie token is still valid, as it could have a different expiring time than the main token. The payloads of the two different tokens could also be different.

const fastify = require('fastify')()
const jwt = require('@fastify/jwt')

fastify.register(jwt, {
  secret: 'foobar',
  cookie: {
    cookieName: 'refreshToken',
  },
  sign: {
    expiresIn: '10m'
  }
})

fastify
  .register(require('@fastify/cookie'))

fastify.get('/cookies', async (request, reply) => {

  const token = await reply.jwtSign({
    name: 'foo'
  })

  const refreshToken = await reply.jwtSign({
    name: 'bar'
  }, {expiresIn: '1d'})

  reply
    .setCookie('refreshToken', refreshToken, {
      domain: 'your.domain',
      path: '/',
      secure: true, // send cookie over HTTPS only
      httpOnly: true,
      sameSite: true // alternative CSRF protection
    })
    .code(200)
    .send({token})
})

fastify.addHook('onRequest', (request) => request.jwtVerify({onlyCookie: true}))

fastify.get('/verifycookie', (request, reply) => {
  reply.send({ code: 'OK', message: 'it works!' })
})

fastify.listen({ port: 3000 }, err => {
  if (err) throw err
})

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.

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({ port: 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)
}
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}.`;
});

To define multiple JWT validators on the same routes, you may use the namespace option. You can combine this with custom names for jwtVerify, jwtDecode, and jwtSign.

When you omit the jwtVerify, jwtDecode, or jwtSign options, the default function name will be <namespace>JwtVerify, <namespace>JwtDecode and <namespace>JwtSign correspondingly.

const fastify = require('fastify')

fastify.register(jwt, {
  secret: 'test',
  namespace: 'security',
  // will decorate request with `securityVerify`, `securitySign`,
  // and default `securityJwtDecode` since no custom alias provided
  jwtVerify: 'securityVerify',
  jwtSign: 'securitySign'
})

fastify.register(jwt, {
  secret: 'fastify',
  // will decorate request with default `airDropJwtVerify`, `airDropJwtSign`,
  // and `airDropJwtDecode` since no custom aliases provided
  namespace: 'airDrop'
})

// use them like this:
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)
  }
})

Setting this option will allow you to extract a token using function passed in for extractToken option. The function definition should be (request: FastifyRequest) => token. Fastify JWT will check if this option is set, if this option is set it will use the function defined in the option. When this option is not set then it will follow the normal flow.

const fastify = require('fastify')
const jwt = require('@fastify/jwt')

fastify.register(jwt, { secret: 'test', verify: { extractToken: (request) => request.headers.customauthheader } })

fastify.post('/sign', function (request, reply) {
  return reply.jwtSign(request.body)
    .then(function (token) {
      return { token }
    })
})

fastify.get('/verify', function (request, reply) {
  // token avaiable via `request.headers.customauthheader` as defined in fastify.register above
  return request.jwtVerify()
    .then(function (decodedToken) {
      return reply.send(decodedToken)
    })
})

fastify.listen(3000, function (err) {
  if (err) throw err
})

To simplify the use of namespaces in TypeScript you can use the FastifyJwtNamespace helper type:

declare module 'fastify' {
  interface FastifyInstance extends
  FastifyJwtNamespace<{namespace: 'security'}> {
  }
}

Alternatively you can type each key explicitly:

declare module 'fastify' {
  interface FastifyInstance extends
  FastifyJwtNamespace<{
    jwtDecode: 'securityJwtDecode',
    jwtSign: 'securityJwtSign',
    jwtVerify: 'securityJwtVerify',
  }> { }
}

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]',
  badCookieRequestErrorMessage: 'Cookie could not be parsed in request',
  noAuthorizationInHeaderMessage: 'No Authorization was found in request.headers',
  noAuthorizationInCookieMessage: 'No Authorization was found in request.cookies',
  authorizationTokenExpiredMessage: 'Authorization token expired',
  authorizationTokenUntrusted: 'Untrusted authorization token',
  authorizationTokenUnsigned: 'Unsigned authorization token'
  // 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
})

ERR_ASSERTION - Missing required parameter or option

FST_JWT_BAD_REQUEST - Bad format in request authorization header. Example of correct format Authorization: Bearer [token]

FST_JWT_BAD_COOKIE_REQUEST - Cookie could not be parsed in request object

FST_JWT_NO_AUTHORIZATION_IN_HEADER - No Authorization header was found in request.headers

FST_JWT_NO_AUTHORIZATION_IN_COOKIE - No Authorization header was found in request.cookies

FST_JWT_AUTHORIZATION_TOKEN_EXPIRED - Authorization token has expired

FST_JWT_AUTHORIZATION_TOKEN_INVALID - Authorization token provided is invalid.

FST_JWT_AUTHORIZATION_TOKEN_UNTRUSTED - Untrusted authorization token was provided

FAST_JWT_MISSING_SIGNATURE - Unsigned or missing authorization token

If this plugin is used together with fastify/passport, we might get an error as both plugins use the same name for a decorator. We can change the name of the decorator, or user will default

const fastify = require('fastify')
fastify.register(require('@fastify/jwt'), {
  secret: 'supersecret',
  decoratorName: 'customName'
})
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.

const token = fastify.jwt.sign({ foo: 'bar' })
// synchronously
const decoded = fastify.jwt.verify(token)
// asynchronously
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.

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, 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.

const { readFileSync } = require('node:fs')
const path = require('node: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

  // 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.allowedAud = 'bar'
  modifiedVerifyOptions.allowedSub = 'test'

  return { globalOptions, modifiedVerifyOptions }
  /**
   * Will return :
   * {
   *   globalOptions: {
   *     decode: {},
   *     sign: {
   *       algorithm: 'RS256',
   *       aud: 'foo',
   *       iss: 'example.tld'
   *     },
   *     verify: {
   *       allowedAud: 'foo',
   *       allowedIss: 'example.tld'
   *     }
   *   },
   *   modifiedVerifyOptions: {
   *     allowedAud: 'bar',
   *     allowedIss: 'example.tld',
   *     allowedSub: 'test'
   *   }
   * }
   */
})

fastify.listen({ port: 3000 }, err => {
  if (err) throw err
})

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.

options must be an Object and can contain verify and decode options.

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.

Here are some examples of 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) {
    // 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({ port: 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 example integrates the get-jwks package to fetch a JWKS and verify a JWT against a valid public JWK.

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({ port: 3000 })

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

// fastify-jwt.d.ts
import "@fastify/jwt"

declare module "@fastify/jwt" {
  interface FastifyJWT {
    payload: { id: number } // payload type is used for signing and verifying
    user: {
      id: number,
      name: string,
      age: number
    } // user type is return type of `request.user` object
  }
}

// index.ts
fastify.get('/', async (request, reply) => {
  request.user.name // string

  const token = await reply.jwtSign({
    id: '123'
    // ^ Type 'string' is not assignable to type 'number'.
  });
})

This project is kindly sponsored by:

Licensed under MIT.


RetroSearch is an open source project built by @garambo | Open a GitHub Issue

Search and Browse the WWW like it's 1997 | Search results from DuckDuckGo

HTML: 3.2 | Encoding: UTF-8 | Version: 0.7.4