@fastify/passport

Since @fastify/passport can only store JSON objects in the session, you should not store rich class instances. Instead, store only a unique identifier (like a user ID) and use serializers/deserializers to fetch the full user object from your database on subsequent requests.

• registerUserSerializer(async (user, request) => ...): Defines what data to store in the session (e.g., user.id).
• registerUserDeserializer(async (id, request) => ...): Defines how to retrieve the user from the database using the stored ID.

// Store only the ID in the session
fastifyPassport.registerUserSerializer(async (user, request) => user.id);

// Fetch the full user from the database using the ID
fastifyPassport.registerUserDeserializer(async (id, request) => {
  return await User.findById(id);
});

To use @fastify/passport, you must add two mandatory hooks to your Fastify instance:

1. initialize(): Sets up the internal hooks for the @fastify/passport instance.
2. secureSession(): Connects @fastify/passport to @fastify/secure-session to enable session-based authentication storage.

Both must be added to your Fastify setup for the plugin to function correctly.

// Note: This is a conceptual representation of the required setup steps
await fastify.register(fastifyPassport);
fastify.after(async () => {
  await fastify.register(fastifyPassport.initialize);
  await fastify.register(fastifyPassport.secureSession);
});

Install the @fastify/passport package using npm:

npm i @fastify/passport

Since @fastify/passport is written in TypeScript, you can provide strong typing for the request.user property using declaration merging. You must re-declare the PassportUser interface within the fastify module to include the properties expected from your authentication strategies.

You can either define the properties directly or make PassportUser extend an existing type.

// Option 1: Define properties directly
declare module 'fastify' {
  interface PassportUser {
    id: string
  }
}

// Option 2: Extend an existing type
import { User } from './my/types'

declare module 'fastify' {
  interface PassportUser extends User {}
}

If you prefer using @fastify/session (the stateful approach), you can instantiate an Authenticator and register it with your server. You still need to register fastifyPassport.initialize() and fastifyPassport.secureSession().

import { Authenticator } from '@fastify/passport'
import fastifyCookie from '@fastify/cookie'
import fastifySession from '@fastify/session'

const server = fastify()
const fastifyPassport = new Authenticator()

server.register(fastifyCookie)
server.register(fastifySession, { secret: 'secret with minimum length of 32 characters' })

// Initialize and connect to session storage
server.register(fastifyPassport.initialize())
server.register(fastifyPassport.secureSession())

fastifyPassport.use('test', new SomePassportStrategy())

You can pass an array of strategies to an authentication handler to create a chain. The handler will attempt each strategy in series.

Behavioral Rules:

1. Success/Redirect/Error: The first strategy that succeeds, redirects, or encounters an error will halt the chain.
2. Failures: If a strategy calls fail(), the handler catches the failure and proceeds to the next strategy in the array.
3. Total Failure: If all strategies in the chain fail, the handler executes the failure logic (e.g., redirecting to failureRedirect or returning a 401).

Note: This pattern is ideal for API endpoints supporting multiple credential types (e.g., Basic, Digest, Token). It is not recommended for strategies involving redirects (like OAuth2 providers), as the first strategy that attempts a redirect will halt the chain before subsequent strategies can be tried.

By default, @fastify/passport cleans the session after a successful login for security. You can manage this behavior using the following options:

1. Set keepSessionInfo: true in the .authenticate() call.
2. Set keepSessionInfo: true in the request.login() call.
3. Configure the global settings:
   • clearSessionOnLogin: defaults to true.
   • clearSessionIgnoreFields: defaults to ['passport', 'session'].

The SessionStrategy works by checking the current session for a storable user value.

1. It retrieves the user data from the session via the sessionManager.
2. If valid data is found, it calls the provided deserializeUser function.
3. If deserializeUser returns a user, that user is assigned to request[request.passport.userProperty] (typically request.user).
4. If deserializeUser returns nothing (null/undefined), the strategy automatically calls logOut(request) to clear the invalid session.

This strategy ensures that once a user has logged in via an OAuth or Local strategy, they remain authenticated in subsequent requests as long as their session is valid.

The PassportSession type represents the structural shape of the session object provided by either @fastify/session or @fastify/secure-session. Since fastify-passport is compatible with both, it uses this local interface to ensure compatibility without requiring both session plugins to be installed.

Key methods include:

• get(key: string): unknown: Retrieves a value from the session.
• set(key: string, value: unknown): void: Sets a value in the session.
• data(): unknown: Returns the underlying session data.
• regenerate?(ignoreFields?: string[]): void | Promise<void>: (Optional) Regenerates the session ID, optionally ignoring specific fields.

export type PassportSession = {
  get(key: string): unknown
  set(key: string, value: unknown): void
  data(): unknown
  regenerate?(ignoreFields?: string[]): void | Promise<void>
}