JwtStrategy, JwtAuthGuard, RolesGuard로 이해한 인증과 권한 검사 흐름

{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6..."
}

JwtStrategy + JwtAuthGuard
→ 로그인한 사용자인지 검사한다.

RolesDecorator + RolesGuard
→ 로그인한 사용자 중 특정 권한을 가진 사용자인지 검사한다.

1차 방어막: 너 로그인했어?
2차 방어막: 너 이 API를 사용할 권한이 있어?

@Post()
@UseGuards(JwtAuthGuard, RolesGuard)
@Roles(Role.ADMIN)
async createNotice(@Body() dto: CreateNoticeDto) {
  return this.noticesService.create(dto);
}

POST /notices 요청
  ↓
JwtAuthGuard 실행
  ↓
JWT 토큰이 유효한지 검사
  ↓
유효하면 req.user 생성
  ↓
RolesGuard 실행
  ↓
@Roles(Role.ADMIN)에 적힌 권한 확인
  ↓
req.user.role이 ADMIN인지 확인
  ↓
ADMIN이면 Controller 실행
  ↓
아니면 요청 차단

JwtAuthGuard
→ 인증 검사
→ 이 사용자가 로그인한 사용자인지 확인

RolesGuard
→ 권한 검사
→ 로그인한 사용자가 필요한 role을 가지고 있는지 확인

@Injectable()
export class JwtStrategy extends PassportStrategy(Strategy) {
  constructor(private configService: ConfigService) {
    super({
      jwtFromRequest: ExtractJwt.fromAuthHeaderAsBearerToken(),
      ignoreExpiration: false,
      secretOrKey: configService.getOrThrow<string>('JWT_SECRET'),
    });
  }

  async validate(payload: any) {
    return {
      userId: payload.sub,
      email: payload.email,
      role: payload.role,
    };
  }
}

Authorization: Bearer access_token

1. Authorization 헤더에서 Bearer 토큰을 꺼낸다.
2. JWT_SECRET으로 토큰이 유효한지 검증한다.
3. 토큰 만료 시간이 지나지 않았는지 확인한다.
4. 검증에 성공하면 payload를 validate()로 넘긴다.
5. validate()가 반환한 값을 req.user에 넣는다.

jwtFromRequest: ExtractJwt.fromAuthHeaderAsBearerToken()

Authorization: Bearer <토큰>

fetch('/api/protected', {
  headers: {
    Authorization: `Bearer ${accessToken}`,
  },
});

요청 헤더의 Authorization 값에서 Bearer 토큰을 꺼내라.

ignoreExpiration: false

토큰 만료 시간을 무시하지 않는다.
만료된 토큰은 거부한다.

JWT_EXPIRES_IN=1h

JWT_EXPIRES_IN=5s

secretOrKey: configService.getOrThrow<string>('JWT_SECRET')

this.jwtService.sign(payload)

토큰 발급
→ JWT_SECRET으로 서명

토큰 검증
→ 같은 JWT_SECRET으로 검증

configService.getOrThrow<string>('JWT_SECRET')

async validate(payload: any) {
  return {
    userId: payload.sub,
    email: payload.email,
    role: payload.role,
  };
}

const payload = {
  email: user.email,
  sub: user.id,
  role: user.role,
};

{
  userId: payload.sub,
  email: payload.email,
  role: payload.role,
}

@Get('me')
@UseGuards(JwtAuthGuard)
getMe(@Request() req) {
  return req.user;
}

{
  userId: 'user-id',
  email: 'test@example.com',
  role: 'USER',
}

JWT payload
  ↓
JwtStrategy.validate()
  ↓
req.user

@Injectable()
export class JwtAuthGuard extends AuthGuard('jwt') {
  handleRequest(err: unknown, user: any, info: any) {
    if (info?.name === 'TokenExpiredError') {
      throw new UnauthorizedException({
        code: 'TOKEN_EXPIRED',
        message: '로그인이 만료되었습니다. 다시 로그인해 주세요.',
      });
    }

    if (err || !user) {
      throw err || new UnauthorizedException({
        code: 'UNAUTHORIZED',
        message: '인증이 필요합니다.',
      });
    }

    return user;
  }
}

요청 들어옴
  ↓
Guard 검사
  ↓
통과하면 Controller 실행
  ↓
실패하면 Controller 실행 안 됨

@Get('me')
@UseGuards(JwtAuthGuard)
getMe(@Request() req) {
  return req.user;
}

export class JwtAuthGuard extends AuthGuard('jwt') {}

JwtAuthGuard 실행
  ↓
AuthGuard('jwt') 실행
  ↓
JwtStrategy 실행
  ↓
Authorization 헤더에서 토큰 추출
  ↓
JWT_SECRET으로 토큰 검증
  ↓
validate(payload) 실행
  ↓
req.user 생성

JwtAuthGuard는 JwtStrategy를 실행해서 요청에 포함된 JWT가 유효한지 검사한다.

handleRequest(err: unknown, user: any, info: any) {

err
→ 인증 과정에서 발생한 에러

user
→ JwtStrategy.validate()가 반환한 사용자 정보

info
→ 토큰 만료 같은 추가 정보

if (info?.name === 'TokenExpiredError') {
  throw new UnauthorizedException({
    code: 'TOKEN_EXPIRED',
    message: '로그인이 만료되었습니다. 다시 로그인해 주세요.',
  });
}

{
  "statusCode": 401,
  "message": {
    "code": "TOKEN_EXPIRED",
    "message": "로그인이 만료되었습니다. 다시 로그인해 주세요."
  },
  "error": "Unauthorized"
}

저장된 access_token 제거
로그인 페이지로 이동
만료 안내 메시지 표시

if (err || !user) {
  throw err || new UnauthorizedException({
    code: 'UNAUTHORIZED',
    message: '인증이 필요합니다.',
  });
}

Authorization 헤더가 없음
Bearer 토큰이 없음
토큰 형식이 잘못됨
JWT_SECRET이 달라서 검증 실패
토큰이 변조됨

{
  "code": "UNAUTHORIZED",
  "message": "인증이 필요합니다."
}

토큰 만료
→ TOKEN_EXPIRED

그 외 인증 실패
→ UNAUTHORIZED

return user;

{
  userId: payload.sub,
  email: payload.email,
  role: payload.role,
}

@Get('me')
@UseGuards(JwtAuthGuard)
getMe(@Request() req) {
  return {
    userId: req.user.userId,
    email: req.user.email,
    role: req.user.role,
  };
}

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

@Roles(Role.ADMIN)

이 API는 ADMIN 권한이 필요하다.

@Roles(Role.ADMIN)
→ 이 API에는 ADMIN 권한이 필요하다는 정보를 붙임

RolesGuard
→ 그 정보를 읽고 실제로 통과 또는 거부를 판단함

SetMetadata(ROLES_KEY, roles)

export const ROLES_KEY = 'roles';

@Roles(Role.ADMIN)

key: 'roles'
value: [Role.ADMIN]

RolesDecorator가 'roles'라는 이름으로 저장
RolesGuard가 'roles'라는 이름으로 읽음

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

@Roles(Role.ADMIN)

@Roles(Role.ADMIN, Role.USER)

[Role.ADMIN, Role.USER]

@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) => user.role === role);
  }
}

@UseGuards(JwtAuthGuard, RolesGuard)
@Roles(Role.ADMIN)
@Post()
async createAdminNotice() {
  return '관리자 전용 공지 생성';
}

{
  userId: 'user-id',
  email: 'admin@example.com',
  role: 'ADMIN',
}

{
  userId: 'user-id',
  email: 'user@example.com',
  role: 'USER',
}

export class RolesGuard implements CanActivate

canActivate(context: ExecutionContext): boolean

true
→ 요청 통과, Controller 실행

false
→ 요청 차단

401 Unauthorized
→ 로그인 자체가 안 됨
→ 토큰 없음, 토큰 잘못됨, 토큰 만료 등

403 Forbidden
→ 로그인은 했지만 권한이 부족함

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

SetMetadata로 저장한 정보
  ↓
Reflector로 읽음

@Post()
@Roles(Role.ADMIN)
async create() {}

@Controller('admin')
export class AdminController {}

if (!requiredRoles) {
  return true;
}

@Get('me')
@UseGuards(JwtAuthGuard)
getMe(@Request() req) {
  return req.user;
}

@Post('admin-only')
@UseGuards(JwtAuthGuard, RolesGuard)
@Roles(Role.ADMIN)
createAdminOnlyData() {
  return '관리자만 가능';
}

JwtAuthGuard만 사용
→ 로그인 여부만 검사

JwtAuthGuard + RolesGuard + @Roles()
→ 로그인 여부와 권한까지 검사

return requiredRoles.some((role) => user.role === role);

@Roles(Role.ADMIN)

requiredRoles = [Role.ADMIN]

user.role = 'ADMIN'

requiredRoles 중 하나라도 user.role과 같으면 통과한다.

@Roles(Role.ADMIN, Role.USER)

ADMIN === USER → false
USER === USER  → true

@UseGuards(JwtAuthGuard, RolesGuard)
@Roles(Role.ADMIN)

JwtAuthGuard 실행
  ↓
JwtStrategy.validate() 실행
  ↓
req.user 생성
  ↓
RolesGuard 실행
  ↓
req.user.role 검사

@UseGuards(JwtAuthGuard, RolesGuard)
@Roles(Role.ADMIN)

@Controller('notices')
export class NoticesController {
  @Get('me')
  @UseGuards(JwtAuthGuard)
  getMyAuthInfo(@Request() req) {
    return req.user;
  }

  @Post()
  @UseGuards(JwtAuthGuard, RolesGuard)
  @Roles(Role.ADMIN)
  createNotice(@Body() dto: CreateNoticeDto) {
    return {
      message: '관리자만 공지를 생성할 수 있습니다.',
      data: dto,
    };
  }
}

@Get('me')
@UseGuards(JwtAuthGuard)

access_token 있음
토큰 유효함
→ req.user 반환

@Post()
@UseGuards(JwtAuthGuard, RolesGuard)
@Roles(Role.ADMIN)

access_token 있음
토큰 유효함
req.user.role이 ADMIN
→ 공지 생성 가능

const payload = {
  email: user.email,
  sub: user.id,
  role: user.role,
};

return {
  userId: payload.sub,
  email: payload.email,
  role: payload.role,
};

return requiredRoles.some((role) => user.role === role);

DB의 user.role
  ↓
로그인 성공 시 JWT payload에 role 저장
  ↓
프론트가 access_token 저장
  ↓
보호 API 요청 시 Authorization 헤더로 토큰 전달
  ↓
JwtStrategy가 payload.role 추출
  ↓
req.user.role 생성
  ↓
RolesGuard가 req.user.role 검사

인증
→ 너 누구야?
→ access_token이 유효한지 확인

인가
→ 너 이 기능 써도 돼?
→ role이 필요한 권한과 일치하는지 확인

토큰 안에 role이 있음
→ 권한 검사 때 DB 조회를 하지 않아도 됨
→ 빠름

토큰 payload.role = USER

1. JWT payload의 role을 그대로 신뢰한다.
   → 빠르다.
   → 매 요청마다 DB 조회가 없다.
   → 단, role 변경이 즉시 반영되지 않을 수 있다.

2. 토큰의 userId로 매번 DB에서 최신 role을 조회한다.
   → 더 정확하다.
   → role 변경이 즉시 반영된다.
   → 단, 요청마다 DB 조회 비용이 생긴다.

1. 사용자가 로그인한다.

2. 서버가 access_token을 발급한다.
   payload = {
     email,
     sub: user.id,
     role
   }

3. 프론트가 access_token을 저장한다.

4. 보호 API 요청 시 Authorization 헤더에 토큰을 담는다.
   Authorization: Bearer access_token

5. JwtAuthGuard가 실행된다.

6. JwtStrategy가 토큰을 꺼내고 검증한다.

7. 토큰이 유효하면 validate(payload)가 실행된다.

8. validate() 반환값이 req.user가 된다.
   req.user = {
     userId,
     email,
     role
   }

9. RolesGuard가 실행된다.

10. RolesGuard가 @Roles() 메타데이터를 읽는다.

11. req.user.role과 필요한 role을 비교한다.

12. 권한이 맞으면 Controller 실행,
    권한이 부족하면 요청 차단

JwtStrategy
→ Authorization 헤더에서 JWT를 꺼내고 검증한다.
→ 성공하면 payload를 req.user로 바꿔준다.

JwtAuthGuard
→ JwtStrategy를 실행해서 인증 여부를 검사한다.
→ 토큰 만료와 일반 인증 실패 응답을 구분한다.

RolesDecorator
→ @Roles(Role.ADMIN)처럼 API에 필요한 권한 정보를 붙인다.

RolesGuard
→ @Roles()에 적힌 권한과 req.user.role을 비교해서 통과 또는 차단한다.

인증
→ 이 사용자가 로그인한 사용자인가?
→ JwtAuthGuard가 담당

인가
→ 이 사용자가 이 기능을 사용할 권한이 있는가?
→ RolesGuard가 담당

main.ts
  ↓
AppModule
  ↓
기능 모듈 등록
  ↓
Controller
  ↓
Service
  ↓
PrismaService
  ↓
DB

로그인 이후에는

AuthService
  ↓
JWT 발급
  ↓
JwtAuthGuard
  ↓
JwtStrategy
  ↓
req.user 생성
  ↓
RolesGuard
  ↓
권한 검사