Parameter Options

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 { auth } from 'firebase-admin';

enum Roles {
  ADMIN,
  USER,
}

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

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

Difference Between @FirebaseUser and @FirebaseUserClaims

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 (auth.DecodedIdToken).
• @FirebaseUserClaims() → Returns only the custom role claims (roles/permissions) defined for the user.

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

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.