@fastify/jwt

The namespace option allows you to define multiple independent JWT configurations on the same Fastify instance.

Behavior:

• fastify.jwt becomes a map of namespaces. For namespace: 'security', you access utilities via fastify.jwt.security.sign(), fastify.jwt.security.verify(), etc.
• Decorators: The plugin decorates the request object with names derived from the namespace. If you don't provide custom aliases, it uses <namespace>JwtVerify, <namespace>JwtSign, and <namespace>JwtDecode.

TypeScript Support: Use FastifyJwtNamespace to type the namespaces on the FastifyInstance and declare the namespaces in the FastifyJWT interface.

// Registering two different JWT configurations
fastify.register(jwt, {
  secret: 'test',
  namespace: 'security',
  jwtVerify: 'securityVerify',
  jwtSign: 'securitySign'
})

fastify.register(jwt, {
  secret: 'fastify',
  namespace: 'airDrop'
})

// Accessing them
fastify.post('/sign/:namespace', async (request, reply) => {
  if (request.params.namespace === 'security') {
    return reply.securitySign(request.body)
  }
  return reply.airDropJwtSign(request.body)
})

To store tokens in cookies (improving XSS protection via httpOnly and secure flags), configure the cookie option.

Requirements & Behavior:

• You must register @fastify/cookie alongside @fastify/jwt.
• The plugin looks for a decorated request.cookies property.
• Fallback: If the request contains both an Authorization header and a cookie, or if the cookie is empty but the header is present, the plugin falls back to the Authorization header.
• Signing: If you are signing your cookie, set signed: true to ensure 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' })
  reply.setCookie('token', token, { httpOnly: true, secure: true })
  return 'Cookie sent'
})

To protect only specific routes rather than the entire application, wrap the @fastify/jwt registration and a custom authentication logic into a fastify-plugin. This allows you to create a reusable decorator (e.g., fastify.authenticate) that can be applied to specific routes via the onRequest option.

const fp = require("fastify-plugin")

// 1. Create an authentication 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)
    }
  })
})

// 2. Use the decorator in your routes
module.exports = async function(fastify, opts) {
  fastify.get(
    "/",
    {
      onRequest: [fastify.authenticate]
    },
    async function(request, reply) {
      return request.user
    }
  )
}

If you provide a namespace option during registration, the plugin will not decorate fastify.jwt directly. Instead, it will decorate fastify.jwt[namespace].

When using a namespace, the request and reply decorators are also renamed based on the jwtDecode, jwtVerify, and jwtSign options provided. For example, if namespace: 'auth' and jwtVerify: 'check', the decorator will be request.check().

Note: If a namespace is used, the decoratorName (the property on request where the user is stored) is still applied to the request object directly.

// Registration with namespace
fastify.register(fastifyJwt, {
  namespace: 'auth',
  jwtVerify: 'verifyAuth',
  decoratorName: 'account'
})

// Usage in route
fastify.get('/profile', async (request, reply) => {
  await request.verifyAuth()
  return request.account
})

// Accessing the JWT API
const token = await fastify.jwt.auth.sign({ id: 1 })

The secret option is required. It defines how tokens are signed and verified. It supports several formats:

• Primitive: A simple String.
• Function: An async function, a function returning a Promise, or a function with a callback (request, token, callback). This is useful for dynamic secrets.
• Object { private, public }: Used for asymmetric algorithms (RSA, ECDSA).
  • private: A string, buffer, or object { key, passphrase } containing the private key.
  • public: A string or buffer containing the public key.

Verify-only mode: If you only provide a public key in the object (e.g., { public: '...' }), the plugin enters verify-only mode. Decoding and verification will work, but any attempt to use sign functionality will throw an exception.

// secret as a string
fastify.register(jwt, { secret: 'supersecret' })

// secret as an async function
fastify.register(jwt, {
  secret: async function (request, token) {
    return 'supersecret'
  }
})

// secret as an object of RSA keys
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' }
})

// VERIFY-ONLY mode (public key only)
fastify.register(jwt, {
  secret: {
    public: process.env.JWT_ISSUER_PUBKEY
  }
})