NestJS Firebase Auth

July 20, 2026 · View on GitHub

NestJS Passport Strategy for Firebase Auth using Firebase Admin SDK, which includes the Firebase SDK library for use.

Check out the Wiki for full documentation and guides!

Installation
Usage
Migration Guide (v2.0.0)
Migration Guide (v1.9.x)
Documentation
Resources
Stay in touch
License

⚠️ Breaking change in v2.0.0: the minimum required Node.js version is now 22.12, and the bundled Firebase Admin SDK moved to v14. See the v2.0.0 Migration Guide before upgrading.

Installation

npm i @alpha018/nestjs-firebase-auth firebase-admin

Usage

Import The Module

To use Firebase authentication in your application, import the module into your main module.

import { FirebaseAdminModule } from '@alpha018/nestjs-firebase-auth';

@Module({
  imports: [
    ...
      FirebaseAdminModule.forRootAsync({
        imports: [ConfigModule],
        useFactory: (configService: ConfigService) => ({
          // SELECT ONLY ONE: BASE64 OR OPTIONS (Firebase Options)!
          base64: configService.get('FIREBASE_SERVICE_ACCOUNT_BASE64'), // Base64 encoded service account JSON string
          options: {}, // Use this if not using base64
          auth: {
            config: {
              extractor: ExtractJwt.fromAuthHeaderAsBearerToken(), // Choose your extractor from the Passport library
              checkRevoked: true, // Set to true if you want to check for revoked Firebase tokens
              validateRole: true, // Set to true if you want to validate user roles
              useLocalRoles: true, // Set to true if you want to validate user roles locally without firebase call
              rolesClaimKey: 'user_roles' // Set the name of the key within the Firebase custom claims that stores user roles
            },
          },
        }),
        inject: [ConfigService],
      }),
    ...
  ],
})

Parameter Options

Parameter	Type	Required	Description
`base64`	`string`	Yes*	Base64 encoded service account JSON string. Required if `options` is not provided.
`options`	`object`	Yes*	Firebase Admin SDK configuration options. Required if `base64` is not provided.
`auth.config.extractor`	`function`	Optional	A custom extractor function from the Passport library to extract the token from the request.
`auth.config.checkRevoked`	`boolean`	Optional	Set to `true` to check if the Firebase token has been revoked. Defaults to `false`.
`auth.config.validateRole`	`boolean`	Optional	Set to `true` to validate user roles using Firebase custom claims. Defaults to `false`.
`auth.config.useLocalRoles`	`boolean`	Optional	Set to `true` to validate user roles using local custom claims inside the JWT token. Defaults to `false`. Note: If you update the claims, previously issued tokens may still contain outdated roles and remain valid.
`auth.config.rolesClaimKey`	`string`	Optional	The name of the key within the Firebase custom claims that stores user roles. Defaults to `'roles'`. This allows you to customize the property name for roles in your custom claims object.

Auth Guard Without Role Validation

⚠️ Deprecation Warning: Direct usage of UseGuards(FirebaseGuard) is deprecated. Please use the @Auth decorator instead.

To protect an endpoint without validating user roles, use the Auth Guard to ensure the Firebase user's token is valid.

import { Auth, FirebaseProvider } from '@alpha018/nestjs-firebase-auth';

export class AppController {
  constructor(
    private readonly firebaseProvider: FirebaseProvider,
  ) {}

  @Auth() // This line protects your endpoint with Firebase Auth
  @Get()
  mainFunction() {
    return 'Hello World';
  }
}

Auth Guard With Role Validation

To enforce role-based access control, you need to set role-based custom claims in Firebase. Here's how you can set roles for a user using setClaimsRoleBase:

import { FirebaseProvider } from '@alpha018/nestjs-firebase-auth';

enum Roles {
  ADMIN,
  USER,
}

@Controller('')
export class AppController {
  constructor(
    private readonly firebaseProvider: FirebaseProvider,
  ) {}

  @Get()
  async setUserRoles() {
    await this.firebaseProvider.setClaimsRoleBase<Roles>(
      'some-firebase-uid', // The UID of the user you want to set roles for
      [Roles.ADMIN]
    );
    return { status: 'ok' }
  }
}

Then, use the Auth Guard with role validation to check if a user has the necessary permissions to access an endpoint:

import { Roles } from '@alpha018/nestjs-firebase-auth';
enum Roles {
  ADMIN,
  USER,
}

@Controller('')
export class AppController {
  constructor(
    private readonly firebaseProvider: FirebaseProvider,
  ) {}

  @Roles(Roles.ADMIN, Roles.USER) // This line checks the custom claims of the Firebase user AND ensures the user is authenticated (implicitly applies FirebaseGuard)
  @Get()
  mainFunction() {
    return 'Hello World';
  }
}

Controller-Level Authentication with Method-Level Authorization

You can apply authentication at the controller level using @Auth() and then define specific roles for individual routes using @Roles(). The library is optimized to prevent redundant token verification in this scenario.

import { Auth, Roles } from '@alpha018/nestjs-firebase-auth';

enum AppRoles {
  ADMIN,
  USER,
}

@Auth() // Protects all routes in this controller (ensures valid token)
@Controller('users')
export class UsersController {
  
  @Get('profile')
  getProfile() {
    // Accessible by any authenticated user
    return { status: 'ok' };
  }

  @Roles(AppRoles.ADMIN) // Adds specific authorization requirement
  @Get('admin-dashboard')
  getAdminDashboard() {
    // Accessible ONLY by authenticated users with ADMIN role
    return { status: 'secure' };
  }
}

Additional Information

To retrieve the Decoded ID Token and role claims within a protected route, use the @FirebaseUser and @FirebaseRolesClaims parameter decorators.

import {
  FirebaseProvider,
  FirebaseUser,
  FirebaseRolesClaims,
  Roles,
} from '@alpha018/nestjs-firebase-auth';

import { DecodedIdToken } from 'firebase-admin/auth';

enum Roles {
  ADMIN,
  USER,
}

@Controller('')
export class AppController {
  constructor(
    private readonly firebaseProvider: FirebaseProvider,
  ) {}

  @Roles(Roles.ADMIN, Roles.USER)
  @Get()
  async mainFunction(
    @FirebaseUser() user: DecodedIdToken,
    @FirebaseRolesClaims() claims: Roles[],
  ) {
    return {
      user,
      claims
    };
  }
}

Difference Between `@FirebaseUser` and `@FirebaseRolesClaims`

Note: Starting from version >=1.7.x, these two decorators are explicitly separated to avoid confusion (see issue #11):

@FirebaseUser() → Returns the full decoded token (DecodedIdToken).
@FirebaseRolesClaims() → Returns only the custom role claims (roles/permissions) defined for the user.

@FirebaseUserClaims() is a deprecated alias of @FirebaseRolesClaims(). It still works and returns the same value, but new code should use @FirebaseRolesClaims().

This separation ensures that developers can access both the raw Firebase user object and the role/claims information independently.

Migration Guide (v2.0.0)

v2.0.0 upgrades the bundled Firebase Admin SDK from v13 to v14. This library's own API is unchanged; the breaking changes come from the SDK:

Change	Action required
Minimum Node.js is now `22.12`	Upgrade your runtime — Node.js 20 is end-of-life
`auth` namespace removed from the `firebase-admin` root	Import `DecodedIdToken` from `firebase-admin/auth`

➡️ Full details, including Jest configuration, are in the Migrations guide.

Migration Guide (v1.9.x)

To improve semantic clarity and developer experience, direct usage of guards has been deprecated in favor of more descriptive decorators.

1. Replace `RolesGuard` with `@Roles`

Deprecated:

@UseGuards(FirebaseGuard) // or alone if global
@RolesGuard(Roles.ADMIN)

New Way:

@Roles(Roles.ADMIN)

Note: @Roles automatically applies the authentication guard.

2. Replace `UseGuards(FirebaseGuard)` with `@Auth`

Deprecated:

@UseGuards(FirebaseGuard)

New Way:

@Auth()

Why migrate?

Better readability: @Auth vs @UseGuards(FirebaseGuard) clearly states intent.
Optimized Performance: The new decorators use an optimized guard that prevents redundant token verification checks when composing controllers and methods.
Future Proofing: Direct class exports for guards will be removed in the next major version.

Documentation

For more detailed information, guides, and advanced examples, please visit our Project Wiki.

Resources

Check out a few resources that may come in handy when working with NestJS:

Visit the NestJS Documentation to learn more about the framework.
Visualize your application graph and interact with the NestJS application in real-time using NestJS Devtools.

Stay in touch

Author - Tomás Alegre

License

Nest is MIT licensed.