nest-authz

To use nest-authz, you must register the AuthZModule in your AppModule. You can configure the enforcer using two methods: providing a model and policy directly, or using an enforcerProvider (the preferred method).

Configuration Options

import { TypeOrmModule } from '@nestjs/typeorm';

@Module({
  imports: [
    AuthZModule.register({
      model: 'model.conf',
      policy: TypeORMAdapter.newAdapter({
        type: 'mysql',
        host: 'localhost',
        port: 3306,
        username: 'root',
        password: 'password',
        database: 'nestdb'
      }),
      userFromContext: (ctx) => {
        const request = ctx.switchToHttp().getRequest();
        return request.user && request.user.username;
      },
      resourceFromContext: (ctx, perm) => {
        const request = ctx.switchToHttp().getRequest();
        return { type: perm.resource, id: request.id };
      }
    }),
  ],
  controllers: [AppController],
  providers: [AppService]
})

The preferred way to configure the enforcer is by providing an enforcerProvider. This allows you to use NestJS dependency injection and factory patterns to initialize the Casbin enforcer, for example, by using a ConfigService to load settings.

import { TypeOrmModule } from '@nestjs/typeorm';
import { ConfigModule, ConfigService } from './config.module';
import { AUTHZ_ENFORCER } from 'nest-authz';

@Module({
  imports: [
    ConfigModule,
    AuthZModule.register({
      imports: [ConfigModule],
      enforcerProvider: {
        provide: AUTHZ_ENFORCER,
        useFactory: async (configSrv: ConfigService) => {
          const config = await configSrv.getAuthConfig();
          return casbin.newEnforcer(config.model, config.policy);
        },
        inject: [ConfigService],
      },
      userFromContext: (ctx) => {
        const request = ctx.switchToHttp().getRequest();
        return request.user && {
          username: request.user.username, 
          isAdmin: request.user.isAdmin 
        };
      }
    }),
  ],
  controllers: [AppController],
  providers: [AppService]
});

The @UsePermissions decorator is the most common way to enforce authorization on controller methods. You must also include AuthZGuard in your @UseGuards() list.

Decorator Options

  @Get('users')
  @UseGuards(AuthZGuard)
  @UsePermissions({
    action: AuthActionVerb.READ,
    resource: 'USER',
    possession: AuthPossession.ANY
  })
  async findAllUsers() {}

If you need to perform authorization checks inside a method's body rather than at the route level, inject AuthZService. This service provides a wrapper around the Casbin API to check permissions for a specific user.

import { Controller, Get, UnauthorizedException, Req } from '@nestjs/common';
import {
  AuthZGuard,
  AuthZService,
  AuthActionVerb,
  AuthPossession,
  UsePermissions
} from 'nest-authz';

@Controller()
export class AppController {
  constructor(private readonly authzSrv: AuthZService) {}

  @Get('users')
  async findAllUsers(@Req() request: Request) {
    let username = request.user['username'];
    
    // Check permission manually
    const isPermitted = await this.authzSrv.hasPermissionForUser(username, "user", "read:any");
    
    if (!isPermitted) {
      throw new UnauthorizedException(
        'You are not authorized to read users list'
      );
    }
    // ...
  }
}

When initializing the AuthZModule, you must provide an options object of type AuthZModuleOptions. This configuration defines how users and resources are extracted from the request context, how the Casbin model and policy are loaded, and how permissions are checked.

Required Options

• userFromContext: A function that takes the NestJS ExecutionContext and returns an AuthUser. This is used to identify the subject performing the action.

Optional Options

• model: A string representing the Casbin model definition.
• policy: A string or a Promise that resolves to the policy data.
• enablePossession: A boolean to enable/disable possession-based authorization logic.
• resourceFromContext: An optional function to extract the resource being accessed from the ExecutionContext.
• batchApproval: An optional BatchApproval configuration for handling multiple permission checks.
• enforcerProvider: An optional NestJS Provider used to supply a custom Casbin enforcer.
• imports: An optional list of NestJS modules required by this module.

const options: AuthZModuleOptions = {
  model: '...', // Casbin model string
  policy: '...', // Casbin policy string or promise
  userFromContext: (context: ExecutionContext) => {
    const request = context.switchToHttp().getRequest();
    return request.user; // Returns AuthUser
  },
  resourceFromContext: (context: ExecutionContext) => {
    // Logic to extract resource from context
  },
  enablePossession: true,
};

These functions allow you to manipulate the underlying policy rules (permissions) and grouping rules (roles/hierarchies) stored in the enforcer.

Policy (Permission) Management

• addPolicy(enforcer, ...params) / addPolicies(enforcer, rules): Adds new permission rules.
• removePolicy(enforcer, ...params) / removePolicies(enforcer, rules): Removes permission rules.
• updatePolicy(enforcer, oldRule, newRule): Updates an existing rule.
• hasPolicy(enforcer, ...params): Checks if a specific policy rule exists.
• getPolicy(enforcer): Retrieves all permission rules.
• getFilteredPolicy(enforcer, fieldIndex, ...fieldValues): Retrieves policies filtered by specific field values.

Grouping (Role) Management

• addGroupingPolicy(enforcer, ...params) / addGroupingPolicies(enforcer, rules): Adds role hierarchy rules.
• removeGroupingPolicy(enforcer, ...params) / removeGroupingPolicies(enforcer, rules): Removes role hierarchy rules.
• updateGroupingPolicy(enforcer, oldRule, newRule): Updates a grouping rule.
• hasGroupingPolicy(enforcer, ...params): Checks if a grouping rule exists.
• getGroupingPolicy(enforcer): Retrieves all grouping rules.

Named Policies

If your model uses named types (e.g., g2), use the Named variants:

• addNamedPolicy(enforcer, ptype, ...params)
• removeNamedPolicy(enforcer, ptype, ...params)
• getNamedPolicy(enforcer, ptype)
• updateNamedPolicy(enforcer, ptype, oldRule, newRule)