NestJS RBAC実装 - カスタムデコレータとGuardでロール管理する

1
2
3
4
5
6
7

// src/auth/enums/role.enum.ts
export enum Role {
  User = 'user',
  Moderator = 'moderator',
  Admin = 'admin',
  SuperAdmin = 'super_admin',
}

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12

// src/users/entities/user.entity.ts
import { Role } from '../../auth/enums/role.enum';

export class User {
  id: number;
  username: string;
  email: string;
  password: string;
  roles: Role[];
  createdAt: Date;
  updatedAt: Date;
}

1
2
3
4
5
6

// src/auth/decorators/roles.decorator.ts
import { SetMetadata } from '@nestjs/common';
import { Role } from '../enums/role.enum';

export const ROLES_KEY = 'roles';
export const Roles = (...roles: Role[]) => SetMetadata(ROLES_KEY, roles);

1
2
3
4
5

// src/auth/decorators/roles.decorator.ts
import { Reflector } from '@nestjs/core';
import { Role } from '../enums/role.enum';

export const Roles = Reflector.createDecorator<Role[]>();

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31

// src/articles/articles.controller.ts
import { Controller, Get, Post, Body, Delete, Param } from '@nestjs/common';
import { Roles } from '../auth/decorators/roles.decorator';
import { Role } from '../auth/enums/role.enum';
import { ArticlesService } from './articles.service';
import { CreateArticleDto } from './dto/create-article.dto';

@Controller('articles')
export class ArticlesController {
  constructor(private readonly articlesService: ArticlesService) {}

  // すべてのユーザーがアクセス可能（認証のみ必要）
  @Get()
  findAll() {
    return this.articlesService.findAll();
  }

  // Moderator以上のロールが必要
  @Post()
  @Roles(Role.Moderator, Role.Admin, Role.SuperAdmin)
  create(@Body() createArticleDto: CreateArticleDto) {
    return this.articlesService.create(createArticleDto);
  }

  // Admin以上のロールが必要
  @Delete(':id')
  @Roles(Role.Admin, Role.SuperAdmin)
  remove(@Param('id') id: string) {
    return this.articlesService.remove(+id);
  }
}

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29

// src/auth/guards/roles.guard.ts
import { Injectable, CanActivate, ExecutionContext } from '@nestjs/common';
import { Reflector } from '@nestjs/core';
import { Role } from '../enums/role.enum';
import { Roles } from '../decorators/roles.decorator';

@Injectable()
export class RolesGuard implements CanActivate {
  constructor(private reflector: Reflector) {}

  canActivate(context: ExecutionContext): boolean {
    // メタデータからロールを取得
    const requiredRoles = this.reflector.getAllAndOverride<Role[]>(Roles, [
      context.getHandler(),
      context.getClass(),
    ]);

    // ロールが設定されていない場合はアクセスを許可
    if (!requiredRoles) {
      return true;
    }

    // リクエストからユーザー情報を取得
    const { user } = context.switchToHttp().getRequest();

    // ユーザーが必要なロールのいずれかを持っているか確認
    return requiredRoles.some((role) => user.roles?.includes(role));
  }
}

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15

// get() の使用例
const roles = this.reflector.get(Roles, context.getHandler());

// getAllAndOverride() の使用例（推奨）
const roles = this.reflector.getAllAndOverride(Roles, [
  context.getHandler(), // メソッドレベルを優先
  context.getClass(),   // クラスレベルをフォールバック
]);

// getAllAndMerge() の使用例
const roles = this.reflector.getAllAndMerge(Roles, [
  context.getHandler(),
  context.getClass(),
]);
// 結果: メソッドとクラスのロールが結合された配列

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11

@Controller('users')
@Roles(Role.User) // デフォルト: Userロール
export class UsersController {
  @Get()
  // Userロールが適用される
  findAll() {}

  @Delete(':id')
  @Roles(Role.Admin) // 上書き: Adminロールのみ
  remove(@Param('id') id: string) {}
}

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15

import { Controller, Post, UseGuards } from '@nestjs/common';
import { AuthGuard } from '../auth/guards/auth.guard';
import { RolesGuard } from '../auth/guards/roles.guard';
import { Roles } from '../auth/decorators/roles.decorator';
import { Role } from '../auth/enums/role.enum';

@Controller('admin')
export class AdminController {
  @Post('settings')
  @UseGuards(AuthGuard, RolesGuard)
  @Roles(Role.Admin)
  updateSettings() {
    return { message: 'Settings updated' };
  }
}

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14

@Controller('admin')
@UseGuards(AuthGuard, RolesGuard)
@Roles(Role.Admin)
export class AdminController {
  @Get('dashboard')
  getDashboard() {
    return { message: 'Admin dashboard' };
  }

  @Post('settings')
  updateSettings() {
    return { message: 'Settings updated' };
  }
}

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19

// src/app.module.ts
import { Module } from '@nestjs/common';
import { APP_GUARD } from '@nestjs/core';
import { AuthGuard } from './auth/guards/auth.guard';
import { RolesGuard } from './auth/guards/roles.guard';

@Module({
  providers: [
    {
      provide: APP_GUARD,
      useClass: AuthGuard,
    },
    {
      provide: APP_GUARD,
      useClass: RolesGuard,
    },
  ],
})
export class AppModule {}

1
2
3
4
5

// src/auth/decorators/public.decorator.ts
import { SetMetadata } from '@nestjs/common';

export const IS_PUBLIC_KEY = 'isPublic';
export const Public = () => SetMetadata(IS_PUBLIC_KEY, true);

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29

// src/auth/guards/auth.guard.ts
import { Injectable, CanActivate, ExecutionContext } from '@nestjs/common';
import { Reflector } from '@nestjs/core';
import { IS_PUBLIC_KEY } from '../decorators/public.decorator';

@Injectable()
export class AuthGuard implements CanActivate {
  constructor(private reflector: Reflector) {}

  canActivate(context: ExecutionContext): boolean {
    const isPublic = this.reflector.getAllAndOverride<boolean>(IS_PUBLIC_KEY, [
      context.getHandler(),
      context.getClass(),
    ]);

    if (isPublic) {
      return true;
    }

    // JWT検証などの認証ロジック
    const request = context.switchToHttp().getRequest();
    return this.validateRequest(request);
  }

  private validateRequest(request: any): boolean {
    // 実際のJWT検証ロジック
    return !!request.user;
  }
}

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18

// src/auth/auth.controller.ts
import { Controller, Post, Body } from '@nestjs/common';
import { Public } from './decorators/public.decorator';

@Controller('auth')
export class AuthController {
  @Public()
  @Post('login')
  login(@Body() loginDto: LoginDto) {
    // ログイン処理
  }

  @Public()
  @Post('register')
  register(@Body() registerDto: RegisterDto) {
    // 登録処理
  }
}

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15

// src/auth/enums/role.enum.ts
export enum Role {
  User = 'user',
  Moderator = 'moderator',
  Admin = 'admin',
  SuperAdmin = 'super_admin',
}

// ロールの階層レベルを定義
export const ROLE_HIERARCHY: Record<Role, number> = {
  [Role.User]: 1,
  [Role.Moderator]: 2,
  [Role.Admin]: 3,
  [Role.SuperAdmin]: 4,
};

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44

// src/auth/guards/roles.guard.ts
import { Injectable, CanActivate, ExecutionContext } from '@nestjs/common';
import { Reflector } from '@nestjs/core';
import { Role, ROLE_HIERARCHY } from '../enums/role.enum';
import { Roles } from '../decorators/roles.decorator';

@Injectable()
export class RolesGuard implements CanActivate {
  constructor(private reflector: Reflector) {}

  canActivate(context: ExecutionContext): boolean {
    const requiredRoles = this.reflector.getAllAndOverride<Role[]>(Roles, [
      context.getHandler(),
      context.getClass(),
    ]);

    if (!requiredRoles || requiredRoles.length === 0) {
      return true;
    }

    const { user } = context.switchToHttp().getRequest();

    if (!user || !user.roles) {
      return false;
    }

    // ユーザーの最高ロールレベルを取得
    const userMaxLevel = this.getMaxRoleLevel(user.roles);

    // 必要なロールの最低レベルを取得
    const requiredMinLevel = this.getMinRoleLevel(requiredRoles);

    // ユーザーのロールレベルが必要レベル以上であれば許可
    return userMaxLevel >= requiredMinLevel;
  }

  private getMaxRoleLevel(roles: Role[]): number {
    return Math.max(...roles.map((role) => ROLE_HIERARCHY[role] || 0));
  }

  private getMinRoleLevel(roles: Role[]): number {
    return Math.min(...roles.map((role) => ROLE_HIERARCHY[role] || 0));
  }
}

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31

@Controller('articles')
@UseGuards(AuthGuard, RolesGuard)
export class ArticlesController {
  // すべての認証済みユーザーがアクセス可能
  @Get()
  @Roles(Role.User)
  findAll() {
    return this.articlesService.findAll();
  }

  // Moderator以上がアクセス可能
  @Post()
  @Roles(Role.Moderator)
  create(@Body() dto: CreateArticleDto) {
    return this.articlesService.create(dto);
  }

  // Admin以上がアクセス可能
  @Delete(':id')
  @Roles(Role.Admin)
  remove(@Param('id') id: string) {
    return this.articlesService.remove(+id);
  }

  // SuperAdminのみアクセス可能
  @Post('bulk-delete')
  @Roles(Role.SuperAdmin)
  bulkDelete(@Body() ids: number[]) {
    return this.articlesService.bulkDelete(ids);
  }
}

1
2
3
4
5

{
  "statusCode": 403,
  "message": "Forbidden resource",
  "error": "Forbidden"
}

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15

// src/common/exceptions/insufficient-role.exception.ts
import { ForbiddenException } from '@nestjs/common';
import { Role } from '../../auth/enums/role.enum';

export class InsufficientRoleException extends ForbiddenException {
  constructor(requiredRoles: Role[], userRoles: Role[]) {
    super({
      statusCode: 403,
      error: 'Forbidden',
      message: 'アクセス権限が不足しています',
      requiredRoles,
      userRoles,
    });
  }
}

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45

// src/auth/guards/roles.guard.ts
import { Injectable, CanActivate, ExecutionContext } from '@nestjs/common';
import { Reflector } from '@nestjs/core';
import { Role, ROLE_HIERARCHY } from '../enums/role.enum';
import { Roles } from '../decorators/roles.decorator';
import { InsufficientRoleException } from '../../common/exceptions/insufficient-role.exception';

@Injectable()
export class RolesGuard implements CanActivate {
  constructor(private reflector: Reflector) {}

  canActivate(context: ExecutionContext): boolean {
    const requiredRoles = this.reflector.getAllAndOverride<Role[]>(Roles, [
      context.getHandler(),
      context.getClass(),
    ]);

    if (!requiredRoles || requiredRoles.length === 0) {
      return true;
    }

    const { user } = context.switchToHttp().getRequest();

    if (!user || !user.roles) {
      throw new InsufficientRoleException(requiredRoles, []);
    }

    const userMaxLevel = this.getMaxRoleLevel(user.roles);
    const requiredMinLevel = this.getMinRoleLevel(requiredRoles);

    if (userMaxLevel < requiredMinLevel) {
      throw new InsufficientRoleException(requiredRoles, user.roles);
    }

    return true;
  }

  private getMaxRoleLevel(roles: Role[]): number {
    return Math.max(...roles.map((role) => ROLE_HIERARCHY[role] || 0));
  }

  private getMinRoleLevel(roles: Role[]): number {
    return Math.min(...roles.map((role) => ROLE_HIERARCHY[role] || 0));
  }
}

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65

// src/auth/guards/roles.guard.spec.ts
import { Test, TestingModule } from '@nestjs/testing';
import { Reflector } from '@nestjs/core';
import { ExecutionContext } from '@nestjs/common';
import { RolesGuard } from './roles.guard';
import { Role } from '../enums/role.enum';

describe('RolesGuard', () => {
  let guard: RolesGuard;
  let reflector: Reflector;

  beforeEach(async () => {
    const module: TestingModule = await Test.createTestingModule({
      providers: [RolesGuard, Reflector],
    }).compile();

    guard = module.get<RolesGuard>(RolesGuard);
    reflector = module.get<Reflector>(Reflector);
  });

  const mockExecutionContext = (user: any): ExecutionContext => {
    return {
      switchToHttp: () => ({
        getRequest: () => ({ user }),
      }),
      getHandler: () => jest.fn(),
      getClass: () => jest.fn(),
    } as unknown as ExecutionContext;
  };

  it('ロールが設定されていない場合はtrueを返す', () => {
    jest.spyOn(reflector, 'getAllAndOverride').mockReturnValue(null);
    const context = mockExecutionContext({ roles: [Role.User] });

    expect(guard.canActivate(context)).toBe(true);
  });

  it('ユーザーが必要なロールを持っている場合はtrueを返す', () => {
    jest.spyOn(reflector, 'getAllAndOverride').mockReturnValue([Role.Admin]);
    const context = mockExecutionContext({ roles: [Role.Admin] });

    expect(guard.canActivate(context)).toBe(true);
  });

  it('上位ロールは下位ロールの権限にアクセスできる', () => {
    jest.spyOn(reflector, 'getAllAndOverride').mockReturnValue([Role.Moderator]);
    const context = mockExecutionContext({ roles: [Role.Admin] });

    expect(guard.canActivate(context)).toBe(true);
  });

  it('ユーザーが必要なロールを持っていない場合は例外をスロー', () => {
    jest.spyOn(reflector, 'getAllAndOverride').mockReturnValue([Role.Admin]);
    const context = mockExecutionContext({ roles: [Role.User] });

    expect(() => guard.canActivate(context)).toThrow();
  });

  it('ユーザー情報がない場合は例外をスロー', () => {
    jest.spyOn(reflector, 'getAllAndOverride').mockReturnValue([Role.User]);
    const context = mockExecutionContext(null);

    expect(() => guard.canActivate(context)).toThrow();
  });
});

1

npm run test -- --testPathPattern=roles.guard

1
2
3
4
5
6
7

PASS  src/auth/guards/roles.guard.spec.ts
  RolesGuard
    ✓ ロールが設定されていない場合はtrueを返す (3 ms)
    ✓ ユーザーが必要なロールを持っている場合はtrueを返す (1 ms)
    ✓ 上位ロールは下位ロールの権限にアクセスできる (1 ms)
    ✓ ユーザーが必要なロールを持っていない場合は例外をスロー (2 ms)
    ✓ ユーザー情報がない場合は例外をスロー (1 ms)

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20

src/
├── app.module.ts
├── auth/
│   ├── auth.module.ts
│   ├── decorators/
│   │   ├── public.decorator.ts
│   │   └── roles.decorator.ts
│   ├── enums/
│   │   └── role.enum.ts
│   └── guards/
│       ├── auth.guard.ts
│       ├── roles.guard.ts
│       └── roles.guard.spec.ts
├── common/
│   └── exceptions/
│       └── insufficient-role.exception.ts
└── articles/
    ├── articles.module.ts
    ├── articles.controller.ts
    └── articles.service.ts