NestJS 消防基地管理局

NestJS 使用Firebase admin SDK的Firebase Auth护照策略,其中包括用于使用的Firebase SDK库.

请检查wiki的完整文档和指南!

目录

• 安装
• 使用量
  • 导入模块
  • 参数选项
  • Auth 守护无作用验证
  • Auth 守护与角色验证
  • 基于索赔的授权(良好)
  • 具有方法级授权的主计长级认证
  • 补充资料
• 移徙指南(v2.0.0)
• 移徙指南(v1.9.x)
• 文档
• 资源
• 保持联系
• 许可证

v2.0.0中的突破变化: 现在需要的最小节点.js版本 22.12 对,则 捆绑的消防基地管理员SDK已移至 页:1见 v 2.0.0 移徙指南 升级前.

安装

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

使用量

导入模块

要在应用程序中使用 Firebase 认证,请将模块导入您的主模块 .

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
              useLocalDecode: true, // Set to true to resolve roles and claims locally from the token, without a Firebase call
              rolesClaimKey: 'user_roles' // Set the name of the key within the Firebase custom claims that stores user roles
            },
          },
        }),
        inject: [ConfigService],
      }),
    ...
  ],
})

参数选项

Auth 守护无作用验证

为了在不验证用户角色的情况下保护一个端点,使用Auth Guard来确保Firebase用户的令牌是有效的.

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 守护与角色验证

为了执行基于角色的访问控制,需要在Firebase设置基于角色的自定义索赔. 以下是您如何为用户设定角色 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' }
  }
}

然后,使用带有角色验证的Auth Guard来检查用户是否有访问端点的必要权限:

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';
  }
}

基于索赔的授权(良好)

@RequireClaims 检查访问比角色更细:用户必须持有 每个 所列索赔,没有 只有一个 它读取一个单独的自定义要求密钥( :permissions 默认情况下,可通过 claimsClaimKey) (中文(简体) ).

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

enum UsersClaim {
  READ = 'users:read',
  WRITE = 'users:write',
}

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

  @Get()
  async setUserClaims() {
    await this.firebaseProvider.setClaimsPermissionBase<UsersClaim>(
      'some-firebase-uid', // The UID of the user you want to set claims for
      [UsersClaim.READ, UsersClaim.WRITE],
    );
    return { status: 'ok' }
  }
}

然后,使用 @RequireClaims 以检查用户是否持有访问端点所需的所有要求:

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

enum UsersClaim {
  READ = 'users:read',
  WRITE = 'users:write',
}

@Controller('')
export class AppController {
  @RequireClaims(UsersClaim.READ, UsersClaim.WRITE) // Requires BOTH claims AND ensures the user is authenticated (implicitly applies FirebaseGuard)
  @Get()
  mainFunction() {
    return 'Hello World';
  }
}

@RequireClaims 属于一般性质,因此来自不同领域的债权(UsersClaim, (中文(简体) ), InvoicesClaim, (中文(简体) ), ReportsClaim,.)可以共存,作为普通字符串在同一自定义请求数组中. 也结合了 在单一路线上发挥作用和制定政策 @Auth({ roles, claims, policies })。 。 。 .

具有方法级授权的主计长级认证

您可以使用 @Auth() ,然后使用 @Roles()。该库被优化,以防止在此情况下进行冗余符号验证.

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' };
  }
}

补充资料

要在受保护的路由中检索已解码的ID Token和角色要求,请使用 @FirebaseUser 财务报告和审定财务报表 @FirebaseRolesClaims 参数装饰.

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
    };
  }
}

差异 @FirebaseUser 财务报告和审定财务报表 @FirebaseRolesClaims

说明: 从版本开始 >=1.7.x,这两个装饰器明确分开,以避免混淆(见 问题11:

• @FirebaseUser() • 返回 已完全解码的令牌 (单位:千美元)DecodedIdToken) (中文(简体) ).
• @FirebaseRolesClaims() - 仅返回 自定义角色索赔 (作用/许可)为用户定义.

这种分离确保了开发者既可以独立访问原始的Firebase用户对象,也可以独立访问角色/要求信息.

移徙指南(v2.0.0)

v2.0.0 将捆绑的 Firebase 管理器 SDK 从 v13 升级到 页:1。这个图书馆的 API 是 不变; 断开变化来自 SDK :

包括杰斯特配置在内的全部细节都在 移徙指南。 。 。 .

移徙指南(v1.9.x)

为了提高语义上的清晰度和开发者的经验,对警卫的直接使用被贬低,更倾向于描述性的装饰. 截止 v3.0.0, (中文(简体) ), RolesGuard 与公众 FirebaseGuard 已完全去除出口——见 移徙指南。 。 。 .

1. 替换 RolesGuard 与 @Roles

在 v3. 0.0 中被删除 :

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

新途径 :

@Roles(Roles.ADMIN)

说明: @Roles 自动应用认证守护.

2. 替换 UseGuards(FirebaseGuard) 与 @Auth

在 v3. 0.0 中被删除 :

@UseGuards(FirebaseGuard)

新途径 :

@Auth()

为什么移民?

• 更好的可读性数字 : @Auth 对 @UseGuards(FirebaseGuard) 明确表明意图.
• 最佳业绩: 新的装饰器使用一个最优化的后卫来防止在编组控制器和方法时进行冗余的符号验证检查.

文档

欲了解更详细的情况、指南和先进实例,请访问 工程维基。 。 。 .

资源

请检查date=中的日期值 (帮助) NestJS工作时可能有用的资源:

• 访问 NestJS 文档 了解更多的框架.
• 可视化您的应用图并实时与 NestJS 应用交互 NestJS Devtools (英语)。 。 。 .

保持联系

• 作者 - 翻译 托马斯·阿雷格里

许可证

巢为 麻省理工学院执照。 。 。 .