NestJS Firebase Auth

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

Table of Contents

• Installation
• Usage
  • Import the Module
  • Parameter Options
  • Auth Guard Without Role Validation
  • Auth Guard With Role Validation
  • Additional Information
• Resources
• Stay in touch
• License

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 { FirebaseAuthGuard } 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
            },
          },
        }),
        inject: [TicketServiceConfig],
      }),
    ...
  ],
})

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 Guard Without Role Validation

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

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

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

  @UseGuards(FirebaseGuard) // This line protects your endpoint. If `validateRole` is enabled, it also validates the user's role.
  @Get()
  mainFunction() {
    return 'Hello World';
  }
}

Auth Guard With Role Validation

To enforce role-based access control, you need to set custom claims in Firebase. Here's how you can set custom claims:

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

enum Roles {
  ADMIN,
  USER,
}

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

  @Get()
  async setClaims() {
    await this.firebaseProvider.setClaimsRoleBase<Roles>(
      'FirebaseUID',
      [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 { FirebaseGuard, FirebaseProvider, RolesGuard } from '@alpha018/nestjs-firebase-auth';
enum Roles {
  ADMIN,
  USER,
}

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

  @RolesGuard(Roles.ADMIN, Roles.USER) // This line checks the custom claims of the Firebase user to protect the endpoint
  @UseGuards(FirebaseGuard) // This line protects your endpoint and, if `validateRole` is enabled, validates the user's role
  @Get()
  mainFunction() {
    return 'Hello World';
  }
}

Additional Information

To retrieve user claims, use the following example:

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

enum Roles {
  ADMIN,
  USER,
}

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

  @Get()
  async mainFunction() {
    const claims = await this.firebaseProvider.getClaimsRoleBase<Roles>(
      'FirebaseUID',
    );
    return claims; // This returns an array of the user's claims
  }
}

To retrieve Decode ID Token and Claims, use the following example:

import {
  FirebaseGuard,
  FirebaseProvider, FirebaseUser, FirebaseUserClaims,
  RolesGuard,
} from '@alpha018/nestjs-firebase-auth';

import { auth } from 'firebase-admin';

enum Roles {
  ADMIN,
  USER,
}

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

  @RolesGuard(Roles.ADMIN, Roles.USER)
  @UseGuards(FirebaseGuard)
  @Get()
  async mainFunction(
    @FirebaseUser() user: auth.DecodedIdToken,
    @FirebaseUserClaims() claims: Roles[],
  ) {
    return {
      user,
      claims
    };
  }
}

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.