본문으로 건너뛰기

NestJS RBAC 튜토리얼: 가드(Guard)를 사용한 역할 기반 접근 제어

이 튜토리얼에서는 node-casbin을 사용하여 NestJS API에 역할 기반 접근 제어(RBAC)를 추가합니다. 각 라우트는 데코레이터로 필요한 권한을 선언하고, 전역 가드는 현재 사용자가 해당 권한을 가지고 있는지 Casbin에 문의하며, 역할은 서로 상속되므로 admin은 자동으로 editor가 할 수 있는 모든 작업을 수행할 수 있습니다.

권한은 URL 경로 대신 리소스와 액션(articles, delete)으로 명명되며, 이는 NestJS 컨트롤러와 잘 맞습니다. 경로 기반 규칙의 경우 Express 버전을 참조하세요.

1. 설치​

NestJS 프로젝트(nest new my-app)에서 시작하여 Casbin을 추가합니다:

npm install casbin

2. 모델 작성​

프로젝트 루트에 model.conf로 저장합니다:

[request_definition]
r = sub, obj, act

[policy_definition]
p = sub, obj, act

[role_definition]
g = _, _

[policy_effect]
e = some(where (p.eft == allow))

[matchers]
m = g(r.sub, p.sub) && r.obj == p.obj && r.act == p.act
  • r = sub, obj, act: 각 요청은 사용자, 리소스 및 액션으로 구성됩니다.
  • g = _, _: 사용자는 역할에 할당될 수 있으며, 역할은 다른 역할에 할당될 수 있습니다.
  • g(r.sub, p.sub)는 사용자가 정책 규칙의 역할을 직접 또는 상속된 역할을 통해 가지고 있을 때 true입니다.

3. 정책 작성​

policy.csv로 저장합니다:

p, viewer, articles, read
p, editor, articles, create
p, editor, articles, update
p, admin, articles, delete

g, editor, viewer
g, admin, editor

g, alice, admin
g, bob, editor
g, carol, viewer

첫 번째 블록은 각 레벨에서 새로 추가되는 사항만 역할에 부여합니다. 두 번째 블록은 계층 구조를 구축합니다: editor는 또한 viewer이며, admin은 또한 editor입니다. 마지막 블록은 사용자를 역할에 할당합니다. 결과적으로:

사용자역할읽기생성업데이트삭제
aliceadminyesyesyesyes
bobeditoryesyesyesno
carolvieweryesnonono
dave(없음)nononono

4. 권한 데코레이터 추가​

src/permission.decorator.ts
import { SetMetadata } from '@nestjs/common';

export const PERMISSION_KEY = 'permission';

export interface Permission {
resource: string;
action: string;
}

// Declares which permission a route needs, for example @RequirePermission('articles', 'delete').
export const RequirePermission = (resource: string, action: string) =>
SetMetadata(PERMISSION_KEY, { resource, action } as Permission);

5. 가드(Guard) 추가​

가드는 라우트의 메타데이터에서 권한을 읽고 Casbin에 문의합니다. 데코레이터가 없는 라우트는 공개 상태로 유지됩니다.

src/casbin.guard.ts
import { CanActivate, ExecutionContext, ForbiddenException, Inject, Injectable } from '@nestjs/common';
import { Reflector } from '@nestjs/core';
import { Enforcer } from 'casbin';
import { Request } from 'express';
import { Permission, PERMISSION_KEY } from './permission.decorator';

export const ENFORCER = 'CASBIN_ENFORCER';

@Injectable()
export class CasbinGuard implements CanActivate {
constructor(
private readonly reflector: Reflector,
@Inject(ENFORCER) private readonly enforcer: Enforcer,
) {}

async canActivate(context: ExecutionContext): Promise<boolean> {
const permission = this.reflector.getAllAndOverride<Permission>(PERMISSION_KEY, [
context.getHandler(),
context.getClass(),
]);
if (!permission) {
return true; // Routes without @RequirePermission are public.
}

const request = context.switchToHttp().getRequest<Request>();
// Replace this with the user your authentication guard puts on the request, such as request.user.
const user = request.header('X-User') ?? '';

const allowed = await this.enforcer.enforce(user, permission.resource, permission.action);
if (!allowed) {
throw new ForbiddenException();
}
return true;
}
}
노트

X-User 헤더는 예제를 간결하게 유지하기 위해 사용됩니다. Casbin은 인가(authorization)만 처리합니다. 실제 애플리케이션에서는 @nestjs/passport 기반의 인증 가드와 같은 인증 가드가 먼저 실행되어 request.user를 설정하며, 사용자 이름이나 ID는 여기서 읽습니다.

6. 컨트롤러에서 사용​

src/articles.controller.ts
import { Controller, Delete, Get, Param, Post, Put } from '@nestjs/common';
import { RequirePermission } from './permission.decorator';

@Controller('articles')
export class ArticlesController {
@Get()
@RequirePermission('articles', 'read')
findAll() {
return { articles: [] };
}

@Post()
@RequirePermission('articles', 'create')
create() {
return { created: true };
}

@Put(':id')
@RequirePermission('articles', 'update')
update(@Param('id') id: string) {
return { updated: id };
}

@Delete(':id')
@RequirePermission('articles', 'delete')
remove(@Param('id') id: string) {
return { deleted: id };
}
}

7. Enforcer 및 가드 등록​

Enforcer는 팩토리 프로바이더에 의해 한 번 생성되어 가드에 주입됩니다. APP_GUARD로 가드를 등록하면 애플리케이션의 모든 라우트에 적용됩니다.

src/app.module.ts
import { Module } from '@nestjs/common';
import { APP_GUARD } from '@nestjs/core';
import { newEnforcer } from 'casbin';
import { ArticlesController } from './articles.controller';
import { CasbinGuard, ENFORCER } from './casbin.guard';

@Module({
controllers: [ArticlesController],
providers: [
{
provide: ENFORCER,
useFactory: () => newEnforcer('model.conf', 'policy.csv'),
},
{
provide: APP_GUARD,
useClass: CasbinGuard,
},
],
})
export class AppModule {}

8. 테스트해 보기​

npm run start
curl -i -X DELETE -H "X-User: alice" http://localhost:3000/articles/1 # 200, admins can delete
curl -i -X DELETE -H "X-User: bob" http://localhost:3000/articles/1 # 403, editors cannot
curl -i -X PUT -H "X-User: bob" http://localhost:3000/articles/1 # 200, editors can update
curl -i -X POST -H "X-User: carol" http://localhost:3000/articles # 403, viewers are read-only
curl -i -H "X-User: carol" http://localhost:3000/articles # 200
curl -i -H "X-User: dave" http://localhost:3000/articles # 403, no role

9. 런타임에 역할 관리​

관리자 서비스 등에서 필요할 때 @Inject(ENFORCER)를 사용하여 enforcer를 주입하세요:

await enforcer.addRoleForUser('dave', 'editor'); // dave becomes an editor
await enforcer.getImplicitRolesForUser('alice'); // [ 'admin', 'editor', 'viewer' ]
await enforcer.getImplicitPermissionsForUser('bob');
// [ [ 'editor', 'articles', 'create' ], [ 'editor', 'articles', 'update' ], [ 'viewer', 'articles', 'read' ] ]

getImplicitPermissionsForUser는 프론트엔드가 버튼을 표시하거나 숨기기 위해 사용하는 "내가 무엇을 할 수 있는지" 엔드포인트에 유용합니다. 전체 목록은 RBAC API 문서에 있습니다.

다음 단계​

  • 정책을 데이터베이스에 저장. policy.csv를 어댑터(adapter)로 교체하세요. 예를 들어 TypeORM, Prisma, Sequelize 또는 MongoDB를 사용할 수 있습니다. API를 통해 변경된 정책은 자동으로 저장됩니다.
  • 여러 인스턴스. 워처(watcher)를 사용하면 하나의 인스턴스에서 정책을 변경할 때 모든 인스턴스가 정책을 다시 로드합니다.
  • 소유권 규칙. "저자는 자신의 기사만 편집할 수 있다"는 규칙은 역할뿐만 아니라 기사 자체에 의존합니다. 핸들러에서 기사를 로드하고 ABAC 모델로 확인하세요.
  • 멀티 테넌트 애플리케이션. 도메인 기반 RBAC를 사용하면 사용자가 다른 테넌트에서 다른 역할을 가질 수 있으며, enforce의 네 번째 인수로 테넌트를 추가합니다.
  • 기성품 모듈. 미들웨어 목록에는 nest-authz와 같은 커뮤니티 NestJS 모듈 링크가 포함되어 있습니다.

Comments are powered by giscus and GitHub Discussions. They load from giscus.app and GitHub only after you click the button below.