Kurs NestJS · Moduł 4: Uwierzytelnianie

Role-based Authorization - hierarchia w Imperium

5 min czytania ·
W tej lekcji5

Legionista pokazał przepustkę i wszedł do obozu. Wiemy już, kim jest - to uwierzytelnienie, którym zajmowaliśmy się dotąd. Ale czy wolno mu wejść do skarbca? Rozwiązać kohortę? Wypłacić żołd?

To już inne pytanie: nie "kto to jest", tylko "co mu wolno". Nazywamy je autoryzacją i w Imperium odpowiada na nie ranga. Rekrut i legat mają tę samą przepustkę, ale nie te same prawa. Ta lekcja jest o tym, jak zapisać rzymską hierarchię w kodzie.

Role jako drabina

Zacznijmy od wyliczenia rang - od rekruta po dowódcę legionu:

export enum Role {
  TIRO = 'TIRO',           // rekrut
  MILES = 'MILES',         // żołnierz
  CENTURION = 'CENTURION', // dowódca centurii
  LEGATUS = 'LEGATUS',     // dowódca legionu
}

Sam enum wystarczyłby, gdyby role były rozłączne. Ale w wojsku tak nie jest: centurion może wszystko to, co żołnierz, i jeszcze więcej. Ranga to nie etykieta, tylko szczebel drabiny - a drabinę zapisujemy liczbami:

export const ROLE_HIERARCHY = {
  [Role.LEGATUS]: 90,
  [Role.CENTURION]: 80,
  [Role.MILES]: 50,
  [Role.TIRO]: 40,
};

export function hasRequiredRole(userRole: Role, requiredRole: Role): boolean {
  return ROLE_HIERARCHY[userRole] >= ROLE_HIERARCHY[requiredRole];
}

Cała hierarchia sprowadza się do jednego porównania: >=. Legat (90) przejdzie tam, gdzie wymagany jest centurion (80), bo stoi wyżej na drabinie. Rekrut (40) nie przejdzie nigdzie poza własnym szczeblem.

Zwróć uwagę na odstępy między liczbami - 40, 50, 80, 90, a nie 1, 2, 3, 4. To celowe: gdy za rok dojdzie ranga między żołnierzem a centurionem, wpiszesz jej 60 i nie ruszasz reszty. Numerowanie co dziesięć to drobiazg, który oszczędza przepisywania.

Dekorator - zapisanie wymagania przy metodzie

Skoro wiemy, jak porównywać rangi, trzeba jeszcze przy każdym endpointie zapisać, jakiej rangi wymaga. Służy do tego własny dekorator:

import { SetMetadata } from '@nestjs/common';

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

To trzy linijki, ale dzieje się w nich rzecz, którą warto nazwać. SetMetadata nie sprawdza niczego - przypina tylko notatkę do metody kontrolera, pod kluczem ROLES_KEY. Notatka leży sobie i czeka; ktoś inny będzie musiał ją przeczytać i wyciągnąć wnioski.

Zapis (...roles: Role[]) to parametr resztowy - pozwala wywołać @Roles(Role.CENTURION) albo @Roles(Role.CENTURION, Role.LEGATUS), a role trafią do tablicy.

Guard - odczytanie notatki i decyzja

Notatkę czyta guard. To on jest w tym układzie wartownikiem, który porównuje rangę przybysza z rangą wymaganą przy drzwiach:

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

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

    if (!requiredRoles) {
      return true;
    }

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

    return requiredRoles.some((role) => hasRequiredRole(user.role, role));
  }
}

Prześledźmy to po kolei, bo tu spina się cała lekcja. Reflector to narzędzie NestJS do odczytywania metadanych - tych samych, które przypiął SetMetadata. Metoda getAllAndOverride szuka notatki w dwóch miejscach: najpierw przy metodzie (getHandler()), potem przy klasie kontrolera (getClass()), i wygrywa to, co bliżej metody. Dzięki temu możesz ustawić wymóg dla całego kontrolera, a przy jednym endpointie go nadpisać.

Brak notatki znaczy, że endpoint nie stawia wymagań - wtedy return true wpuszcza każdego zalogowanego. To ważne zachowanie: guard, który przy braku metadanych blokowałby dostęp, zamknąłby całą aplikację.

context.switchToHttp().getRequest() sięga po żądanie, a z niego po user - obiekt, który wcześniej zostawiła tam strategia JWT. I tu widać, dlaczego kolejność ma znaczenie: RolesGuard działa tylko wtedy, gdy przed nim zadziałał guard uwierzytelniający. Bez tego user byłby pusty. Autoryzacja zawsze następuje po uwierzytelnieniu - najpierw wiemy, kim jest przybysz, dopiero potem sprawdzamy jego rangę.

Ostatnia linia zwraca true lub false, a to jedyna rzecz, jakiej NestJS od guarda oczekuje: false zatrzymuje żądanie z odpowiedzią 403, a metoda kontrolera nie wykona się w ogóle. Metoda some wystarcza, bo lista ról to alternatywa - dość spełnić jedno z wymagań.

Użycie w kontrolerze

Oba klocki spinamy przy endpointach:

@Controller('treasury')
@UseGuards(JwtAuthGuard, RolesGuard)
export class TreasuryController {
  @Get()
  findAll() {
    return this.treasuryService.findAll();
  }

  @Post('withdraw')
  @Roles(Role.CENTURION)
  withdraw(@Body() dto: WithdrawDto) {
    return this.treasuryService.withdraw(dto);
  }

  @Delete('cohort/:id')
  @Roles(Role.LEGATUS)
  disbandCohort(@Param('id') id: string) {
    return this.treasuryService.disbandCohort(id);
  }
}

Kolejność w @UseGuards(JwtAuthGuard, RolesGuard) nie jest przypadkowa - guardy wykonują się od lewej do prawej, więc najpierw ustalamy tożsamość, potem rangę. Odwrócenie tej pary sprawiłoby, że RolesGuard szukałby user, którego jeszcze nie ma.

Zauważ też, że findAll() nie ma dekoratora @Roles - i właśnie dlatego zobaczy go każdy zalogowany legionista. Wypłata wymaga centuriona, a rozwiązanie kohorty - legata. Ten sam skarbiec, trzy różne progi.

Podsumowanie

Hierarchia Imperium zapisana, wartownicy na miejscach:

  • uwierzytelnienie odpowiada, kim jest przybysz; autoryzacja - co mu wolno,
  • role układamy w drabinę liczb, a całe dziedziczenie uprawnień sprowadza się do porównania >=,
  • numeruj co dziesięć, żeby dało się później wcisnąć nową rangę bez przepisywania,
  • SetMetadata tylko przypina notatkę do metody - niczego nie sprawdza,
  • Reflector.getAllAndOverride czyta notatkę z metody i z klasy, a bliższa metodzie wygrywa,
  • brak metadanych musi znaczyć "wpuść", inaczej guard zamknie całą aplikację,
  • guard zwraca true albo false; false kończy żądanie odpowiedzią 403,
  • w @UseGuards() guardy działają od lewej do prawej - uwierzytelniający musi stać przed autoryzującym, bo to on zostawia user w żądaniu.

W następnej lekcji zajmiemy się odnawianiem przepustek, czyli refresh tokenami - bo przepustka centuriona też kiedyś wygasa. A na razie zapamiętaj: rola to szczebel drabiny, dekorator przypina notatkę o wymaganej wysokości, a guard porównuje jedno z drugim.

Kod do tej lekcji: src/auth/roles.guard.ts
// Role-based Authorization - Hierarchia w Imperium
import { Injectable, CanActivate, ExecutionContext, ForbiddenException } from '@nestjs/common';
import { Reflector } from '@nestjs/core';

// Enum rol w Imperium
export enum Role {
  TIRO = 'TIRO',
  MILES = 'MILES',
  DECANUS = 'DECANUS',
  OPTIO = 'OPTIO',
  CENTURION = 'CENTURION',
  LEGATUS = 'LEGATUS',
  ADMIN = 'ADMIN',
}

// Hierarchia rol
export const ROLE_HIERARCHY: Record<Role, number> = {
  [Role.ADMIN]: 100,
  [Role.LEGATUS]: 90,
  [Role.CENTURION]: 80,
  [Role.OPTIO]: 70,
  [Role.DECANUS]: 60,
  [Role.MILES]: 50,
  [Role.TIRO]: 40,
};

// TODO: Zaimplementuj funkcje sprawdzajaca uprawnienia
// Porownaj poziom roli uzytkownika z wymagana rola
export function hasPermission(userRole: Role, requiredRole: Role): boolean {
  // TODO: Zwroc true jezeli userRole >= requiredRole w hierarchii
  return false;
}

// Dekorator @Roles()
import { SetMetadata } from '@nestjs/common';
export const ROLES_KEY = 'roles';
export const Roles = (...roles: Role[]) => SetMetadata(ROLES_KEY, roles);

// TODO: Zaimplementuj RolesGuard
// 1. Uzyj Reflector do pobrania wymaganych rol
// 2. Pobierz uzytkownika z request.user
// 3. Sprawdz czy uzytkownik ma wymagana role
@Injectable()
export class RolesGuard implements CanActivate {
  constructor(private reflector: Reflector) {}

  canActivate(context: ExecutionContext): boolean {
    // TODO: Pobierz wymagane role z metadanych
    const requiredRoles = this.reflector.getAllAndOverride<Role[]>(
      ROLES_KEY,
      [context.getHandler(), context.getClass()],
    );

    if (!requiredRoles) {
      return true; // Brak ograniczen
    }

    // TODO: Pobierz uzytkownika z requestu
    const { user } = context.switchToHttp().getRequest();

    // TODO: Sprawdz czy uzytkownik ma jedna z wymaganych rol
    // Uzyj hasPermission() lub requiredRoles.some()
    return false;
  }
}

console.log('RolesGuard - kontrola dostepu oparta na rolach');
console.log('Roles: TIRO < MILES < DECANUS < OPTIO < CENTURION < LEGATUS < ADMIN');

Widzisz błąd w tej lekcji?

Sprawdź się

Odpowiedz na pytania z tej lekcji. Wybierz odpowiedź, a od razu zobaczysz, czy jest poprawna.

  1. 1. Jaki jest główny cel Role-based Authorization (RBAC)?

Zadania praktyczne w grze

  • Klikanie w kolejności

    Uszereguj role od najniższej do najwyższej:

  1. PytanieCel Role-based Authorization
  2. Kliknij w kolejnościHierarchia ról w RBAC

Przydatne artykuły