@fastify/oauth2

The plugin decorates the Fastify instance with the simple-oauth2 instance. To allow multiple OAuth providers to coexist without collision, the instance is placed inside a namespace defined by the name property in your configuration.

The instance is accessible via two paths:

1. fastify.oauth2<name>.oauth2
2. fastify.<name>.oauth2

// If registered with name: 'facebook'
// Access via:
fastify.oauth2Facebook.oauth2
fastify.facebook.oauth2

Setting hostPrefixedCookies: true switches default cookie names to their __Host- prefixed forms (__Host-oauth2-redirect-state and __Host-oauth2-code-verifier).

Why use this? It protects against Login CSRF by ensuring cookies can only be written by a secure origin and are scoped to the host only. This is highly recommended if any host under your registrable domain is outside your control.

Requirements:

• The application must be reached via HTTPS (browsers enforce this for __Host- cookies).
• Local development on http://localhost still works as browsers treat it as a secure context.
• If you use an explicit redirectStateCookieName or verifierCookieName, those will override the prefixing.

fastify.register(oauthPlugin, {
  ...,
  hostPrefixedCookies: true
})

To get type-safe access to your OAuth2 decorators, use TypeScript declaration merging. The plugin applies decorations to your FastifyInstance based on the name provided in your configuration.

Ensure you have @types/node installed.

import { OAuth2Namespace } from '@fastify/oauth2';

declare module 'fastify' {
  interface FastifyInstance {
    facebookOAuth2: OAuth2Namespace;
    myCustomOAuth2: OAuth2Namespace;
  }
}

Some providers require client_id and client_secret to be explicitly included in the body of the token request. For Twitch and LinkedIn, you must pass these via the tokenRequestParams option.

Example for Twitch:

fastify.register(oauthPlugin, {
  name: 'twitchOauth2',
  credentials: {
    client: {
      id: '<CLIENT_ID>',
      secret: '<CLIENT_SECRET'
    },
    auth: oauthPlugin.TWITCH_CONFIGURATION
  },
  tokenRequestParams: {
    client_id: '<CLIENT_ID>',
    client_secret: '<CLIENT_SECRET>',
  },
  startRedirectPath: '/login/twitch',
  callbackUri: 'http://localhost:3000/login/twitch/callback'
})

Since v7.2.0, @fastify/oauth2 requires cookies for secure exchange. You must register @fastify/cookie before @fastify/oauth2.

By default, cookies are httpOnly and sameSite: 'Lax'. You can customize cookie settings, names, and signing via the configuration object.

const fastify = require('fastify')({ logger: { level: 'trace' } })
const oauthPlugin = require('@fastify/oauth2')

// Register cookie plugin FIRST
fastify.register(require('@fastify/cookie'), cookieOptions)
// Then register oauth plugin
fastify.register(oauthPlugin, oauthOptions)

Install the plugin using npm:

npm i @fastify/oauth2

If a preset is not available, you can manually define the OAuth2 endpoints in the auth object:

• authorizeHost: The base URL for authorization.
• authorizePath: The path to the authorization endpoint.
• tokenHost: The base URL for the token service.
• tokenPath: The path to the token endpoint.

You can also pass additional parameters to the callback via callbackUriParams.

fastify.register(oauthPlugin, {
  name: 'customOauth2',
  credentials: {
    client: {
      id: '<CLIENT_ID>',
      secret: '<CLIENT_SECRET'
    },
    auth: {
      authorizeHost: 'https://my-site.com',
      authorizePath: '/authorize',
      tokenHost: 'https://token.my-site.com',
      tokenPath: '/api/token'
    }
  },
  startRedirectPath: '/login',
  callbackUri: 'http://localhost:3000/login/callback',
  callbackUriParams: {
    exampleParam: 'example param value'
  }
})

You can provide a schema object to define the JSON schema for the startRedirectPath endpoint. This is particularly useful when using @fastify/swagger to generate documentation.

Note: The schema option overrides the tags option entirely; it does not merge them.

fastify.register(oauthPlugin, {
  name: 'facebookOAuth2',
  credentials: {
    client: {
      id: '<CLIENT_ID>',
      secret: '<CLIENT_SECRET>'
    },
    auth: oauthPlugin.FACEBOOK_CONFIGURATION
  },
  startRedirectPath: '/login/facebook',
  callbackUri: 'http://localhost:3000/login/facebook/callback',
  tags: ['facebook', 'oauth2'],
  schema: {
    tags: ['facebook', 'oauth2'] // this will take the precedence
  }
})

Use the callbackUriParams option to pass additional query parameters to the OAuth provider during the callback phase. This is useful for provider-specific requirements, such as requesting offline access in Google.

fastify.register(oauthPlugin, {
  name: 'googleOAuth2',
  scope: ['profile', 'email'],
  credentials: {
    client: {
      id: '<CLIENT_ID>',
      secret: '<CLIENT_SECRET>',
    },
    auth: oauthPlugin.GOOGLE_CONFIGURATION,
  },
  startRedirectPath: '/login/google',
  callbackUri: 'http://localhost:3000/login/google/callback',
  callbackUriParams: {
    access_type: 'offline', // will tell Google to send a refreshToken too
  },
  pkce: 'S256'
});