Доброго времени суток! Веду разработку проекта по единой аутентификации Trusted.ID и сталкиваюсь с достаточно интересными проблемами и решениями с которыми я хотел бы поделиться. Но обо всем по порядку.

Backend-разработка — это отдельное направление, которое имеет очень много нюансов. Но их все можно свести к одному золотому правилу: «В основе backend-разработки должна быть четкая логика и структура». Где порядок, там меньше багов, потерь времени на запросы и уязвимостей в безопасности.

NestJS

На нашем проекте мы используем framework NestJS для построения сервера. Этот фреймворк позволяет решить массу проблем с архитектурой сервера. Но даже при таком подходе в один прекрасный момент в проекте начался хаос. Мы стали достаточно много тратить время на какие-либо изменения, любая задача или исправления бага начинали отнимать все больше времени. Приступив к анализу этой проблемы мы обнаружили что все дело было в некорректном применении guards, а точнее в том что нами была некорректно построена архитектура NestJS на уровне guards.

Что такое Guards в NestJS

NestJS делит middlewares на несколько слоёв:

Guards — проверка прав и условий доступа;
Interceptors — перехват и модификация запроса/ответа;
Pipes — валидация и трансформация данных.

Guards — это линия обороны. Они решают, должен ли запрос попасть в контроллер на сервере или же нет.

Вот пример одного из наших старых guards который отвечал за авторизацию через логин и пароль:

import { CanActivate, ExecutionContext, mixin, Inject } from '@nestjs/common';
import { UserService } from 'src/modules/user/user.service';
import { AuthService } from '../modules/auth/auth.service';

export const CredentialsGuard = () => {
  class CredentialsGuard implements CanActivate {
    constructor(
      @Inject(AuthService) private authService: AuthService,
      @Inject(UserService) private userService: UserService,
    ) {}

    async canActivate(context: ExecutionContext): Promise<boolean> {
      try {
        const request = context.switchToHttp().getRequest();
        const { identifier, password } = request.body;

        const result = await this.authService.checkUserCredentials({ identifier, password });

        if (result) {
          const user = await this.userService.getUserByIdentifier(identifier);
          Reflect.defineMetadata('user_id', user.id, context.getHandler());
        }

        return result;
      } catch (e) {
        console.log('CredentialsGuard error: ', e);
        return false;
      }
    }
  }

  const injectableGuard = mixin(CredentialsGuard);

  return injectableGuard as new () => { [key in keyof CredentialsGuard]: CredentialsGuard[key] };
};

На первый взгляд такой guard выглядит достаточно корректно, и применение его тоже достаточно просто:

@Get('')
@UseGuards(CredentialsGuard)
async get() { return this.service.get(); }

Но именно в его простоте и кроется проблема.

В нашем проекте наблюдалось 7 таких элементов:

AccessTokenGuard
ClientCredentialsGuard
CredentialsGuard
DisableAccessTokenGuard
PersonalGuard
PublicAccessTokenGuard
RoleGuard

На каждом контроллере применялись свои комбинации из этих guards.

Именно такой подход и сделал наш проект, с точки зрения разработки, неким увальнем, который требует много сил и времени. Так как при добавлении нового контроллера нам приходилось дополнительно собирать собственный набор проверок для него, а при добавлении нового guard в проект нам приходилось перебирать абсолютно все контроллеры и добавлять вручную его.

Как использовать Guards

NestJS позволяет использовать guards гибко, вешая их на нужный уровень — один контроллер, группа контроллеров или глобально.

1. На один контроллер

@Get('')
@UseGuards(AuthGuard1, AuthGuard2)
async get() { return this.service.get(); }

2. На группу контроллеров

@Controller('settings')
@UseGuards(AuthGuard1, AuthGuard2)
export class SettingsController {}

3. Глобально

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

Особенности применения

На небольших проектах обычно всё просто: guard на контроллер и поехали. Именно так и начинался наш проект. Но как лучше поступить с большими проектами? Ведь чем крупнее проект, тем больше сущностей, ролей и проверок. Если не задать четкие правила, архитектура и безопасность поплывут.

Несмотря на то, что в нашем проекте присутствовало 7 guards, нам необходимо было добавить по такой схеме еще штук 5. Это явно начинало походить на проблему так как нам приходилось при добавлении нового guard проходить по всем контроллерам и добавлять его там где нужно.

С одной стороны, применение guards на отдельные контроллеры придает гибкости системе. Но эта гибкость начинает играть плохую шутку с вашим проектом при его увеличении.

Представьте себе проект с 200 контроллерами. Это увеличивает время разработки и усложняет вхождения в проект новых разработчиков, а также закладывает множество уязвимостей в безопасности по банальной человеческой забывчивости или невнимательности.

Вариант с применением для группы контроллеров упрощает и частично решает данную проблему, но все же для крупных проектов лучше использовать вариант с глобальными guards. Применив проверки безопасности для всего сервера, вы надежно покрываете все контроллеры, в том числе и будущие. Это сократит объем кода, сократит время на разработку, упростит вхождение в проект и сократит количество потенциальных дыр в безопасности, но требует несколько другого подхода к самому guard.

Как организовать Guards

NestJS позволяет применять guards последовательно, что позволяет выстроить защиту «слоями» через которые должен пройти любой запрос к серверу.

Это достаточно удобный вариант, так как он позволяет развести логику проверок на разные «слои». А также исключить необходимость при добавлении нового guard проходить по всем контроллерам в отдельности.

Давайте рассмотрим это более подробно на примере.

Мы создали для начала guards "AccessGuard", отвечающий за проверку токена в запросе.
Если в запросе присутствует токен, то мы получаем информацию о пользователе и его роли, если нет, то (внимание!) пропускаем далее.

@Injectable()
export class AccessGuard implements CanActivate {
 private oidcService: OidcService;

 async canActivate(context: ExecutionContext): Promise<boolean> {
    const request: Request = context.switchToHttp().getRequest();
    let role: UserRoles = UserRoles.NONE;
    Reflect.defineMetadata(ROLEKEY, role, context.getHandler());
    Reflect.defineMetadata(USER_ID_KEY, null, context.getHandler());

    // При отсутствии токена в запросе, определяем роль как NONE
    if (!request.headers.authorization) {
      return true;
    }

    // Получаем информацию о токене
    if (request.headers.authorization.includes('Bearer')) {
      const token = request.headers.authorization.replace('Bearer ', '');

      if (!token || token.includes('undefined')) {
        return true;
      }

      // Проверка на валидность токена и получение информации о нем
      const tokenInfo = await this.oidcService.tokenIntrospection(token);

      user_id = tokenInfo.user_id;

      // Если токен уже не активен, то выбрасываем исключение
      if (!tokenInfo.active) throw new ForbiddenException('Токен не активен');
    } else {
      throw new BadRequestException('Некорректный формат Authorization');
    }

    // Сохраняем в контексте запроса user_id, для дальнейшего использования
    Reflect.defineMetadata(USER_ID_KEY, user_id, context.getHandler());

    // Получаем роль пользователя
    const roleItem = await prisma.role.findUnique({
      where: { user_id }
    });
    if (!roleItem)
      throw new BadRequestException('Роль пользователя не найдена');
  return true;
  }
}

Тут мне мои коллеги всегда задают вопрос «зачем пропускать далее?». Именно в этом и кроется особенность построения защиты «слоями».

Если бы мы при отсутствии токена выдавали бы ошибку и не давали пройти, то нам бы пришлось бы строить отдельную цепочку всех проверок для контроллеров которые работают без токена и применять их выборочно. Здесь же мы только собираем необходимую информацию о пользователе если он использует токен. Остальные «слои» будут использовать эту информацию для своих проверок.

Затем мы создали второй слой проверки "ScopeGuard". Он будет проверять, имеет ли данная роль пользователя доступ к данному контроллеру.

@Injectable()
export class ScopeGuard implements CanActivate {
  async canActivate(context: ExecutionContext): Promise<boolean> {
    const reflector = new Reflector();

    // Получаем скоупы, которые требуются для доступа к контроллеру
    const requiredScope = reflector.get<string>(SCOPE_KEY, context.getHandler());

    // Если скоупы на контроллере не указаны, то доступ открыт
    if (!requiredScope) return true;

    // Получаем роль пользователя
    const role = reflector.get<UserRoles>(ROLE_KEY, context.getHandler());

    // Если роль не указана, то доступ закрыт
    if (!role) return false;

    // Проверяем, есть ли у пользователя требуемый скоуп
    return ROLES.get(role).some((r) => r === requiredScope);
  }
}

Теперь, создавая контроллеры, мы можем индивидуально для каждого контроллера определять scope, что позволит нам четко настроить какая роль имеет доступ, а какая нет.

@common.Get('catalog')
  @swagger.ApiOperation({
    summary: 'Получение списка приложений',
  })
  @Scope(ClientActions.list)
  async getCatalog(
    @common.Query() params: ListInputDto,
    @UserId() userId: string,
    @common.Res() res: Response,
  ) {
    const { clients, totalCount } = await this.clientService.catalog(params, userId);
    return prepareListResponse(res, clients, totalCount, params);
  }

Остается только реализовать механизм перечня scopes для ролей.

export enum ClientActions {
  read = 'client:read',
  list = 'client:list',
  write = 'client:write',
  delete = 'client:delete',
}

// Задаем права для роли USER
ROLES.set(UserRoles.USER, [
  ClientActions.list,
]);

При таком подходе легко расширять проверки под свой проект и производить масштабирование:

Добавить в AccessGuard поддержку работы с Basic и JWT.
Добавить новые guards, которые будут проверять доступ к определенным сущностям. Например, к пользователям или приложениям.
Настроить статический список scopes на каждую роль или сделать его настраиваемым через интерфейс.

Архитектура Guards

Чтобы выстроить хорошую защиту сервера на базе guards, продумывайте не только набор проверок, но и способ их применения.

Необходимо сокращать до минимума индивидуальное применение guards на контроллерах и больше применять глобальные.

Каждый guard должен быть специализирован на своем и защищать только по своей специализации, но применяться ко всем контроллерам глобально. К примеру, если контроллер в своем адресе имеет userId, то применяется UserGuard, который перепроверяет доступ к данному пользователю, но если нет userId, то UserGuard пропускает далее к следующим проверкам.

Принцип «слоёв» предполагает применение guards глобально, где каждый guard имеет свою специализацию и знает когда он должен отработать, а когда пропустить запрос к следующей проверке.

Применяя архитектуру «слоёв», система приобретает четкую и понятную структуру с возможностью расширения и масштабирования.

Пример:

Запрос --> AccessGuard --> ScopeGuard --> ResourceGuard --> Сервис

В результате вы получаете архитектуру без хаоса, а значит и надежную безопасность в проекте.

Заключение

Архитектура на backend является очень важным моментом. Некорректно построенная архитектура сервера приводит к хаосу в проекте. Структура применения guards в NestJS должна быть грамотно выстроена:

отдельные guards с раздельным функционалом;
контроллеры без дублирования кода;
централизованная и многослойная защита;
легкость расширения и масштабирования.

Это фундамент любого проекта, чем он крепче, тем стабильнее сервер.

Надеюсь я смог передать саму идею организации работы с guards в NestJS. Заглядывайте в наш репозиторий Trusted.ID, мы за последнее время привнесли в проект большое количество интересных решений и идей: расширяемый профиль пользователя, загрузка модулей и многое другое.

NestJS: guards или как избежать хаоса в безопасности