Перейти к основному содержимому

Учебник по RBAC в NestJS: Управление доступом на основе ролей с использованием Guards

В этом руководстве добавляется управление доступом на основе ролей (RBAC) к API на NestJS с помощью node-casbin. Каждый маршрут объявляет необходимое разрешение с помощью декоратора, глобальный guard спрашивает у Casbin, есть ли оно у текущего пользователя, а роли наследуются друг от друга, так что admin автоматически получает все права, которые есть у editor.

Разрешения названы по ресурсам и действиям (articles, delete) вместо путей URL, что хорошо подходит для контроллеров 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) истинно, когда пользователь имеет роль, указанную в правиле политики, либо напрямую, либо через унаследованные роли.

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. Последний блок назначает пользователей ролям. В результате:

ПользовательРольreadcreateupdatedelete
aliceadminдададада
bobeditorдададанет
carolviewerданетнетнет
dave(нет)нетнетнетнет

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​

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 отвечает только за авторизацию. В реальном приложении сначала выполняется guard аутентификации, например на основе @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 и guard​

Enforcer создается один раз factory provider'ом и внедряется в guard. Регистрация guard с помощью 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. Управляйте ролями во время выполнения​

Внедрите enforcer везде, где он нужен, например в административный сервис, с помощью @Inject(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.
  • Многопользовательские (multi-tenant) приложения. RBAC с доменами предоставляет пользователю разные роли в разных тенантах; добавьте тенант в качестве четвертого аргумента в enforce.
  • Готовые модули. Список middleware содержит ссылки на сообщественные модули NestJS, такие как nest-authz.

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