🔐 웹 서비스 인증/인가 이해와 JWT 로그인 구현 (ft. NestJS)

1. 로그인 기능 구현

웹 서비스를 개발할 때 로그인 기능은 가장 기본적이면서도 중요한 요소다. 단순히 아이디와 비밀번호를 확인하는 것을 넘어 특정 사용자가 우리 서비스의 유저가 맞는지 검증하고 해당 요청에 대한 접근 권한이 있는지까지 판단해야 하기 때문이다.

로그인 기능을 설계하기 전에 선행되어야 할 인증(Authentication)과 인가(Authorization)의 개념을 먼저 정리해 보자.

2. 인증 & 인가

인증(Authentication)은 사용자의 신원을 확인하는 과정이다. 공항에서 여권을 제시해 본인이 누구인지 증명하는 것에 비유할 수 있다. 사용자가 입력한 ID와 비밀번호가 데이터베이스에 저장된 정보와 일치하는지를 검증하는 단계가 이에 해당한다.

인가(Authorization)는 인증을 통과한 사용자가 어떤 권한을 가지는지 확인하는 과정이다. 여권 확인 후 발급받은 티켓에 따라 퍼스트 클래스 라운지에 입장할 수 있는지 일반 게이트로 이동해야 하는지를 판단하는 것과 같다. 예를 들어 일반 사용자가 게시물을 삭제하려 할 경우 서버는 해당 요청에 대한 삭제 권한이 있는지를 검증한 뒤 허용 또는 거부한다.

인증과 인가는 명확히 구분되는 개념이며 인증이 선행되어야만 인가가 가능하다. 사용자의 신원이 확인되지 않은 상태에서는 적절한 권한을 부여할 수 없기 때문이다.

3. 세션 vs JWT

인증과 인가를 구현할 때 흔히 고민하게 되는 선택지는 세션(Session)과 JWT(Json Web Token) 방식이다. 두 방식의 가장 큰 차이는 사용자의 로그인 상태(상태 정보)를 어디에 저장하느냐에 있다.

세션(Session) 방식
서버가 사용자 상태 정보를 직접 저장하고 관리하는 구조이다. 일반적으로 메모리 또는 Redis와 같은 저장소에 세션을 보관한다.

• 흐름
  로그인 성공 -> 서버가 세션 저장소에 사용자 정보 저장 -> Session ID 발급 -> 클라이언트는 쿠키에 Session ID 저장 -> 요청 시 쿠키 전송 -> 서버가 저장소에서 ID 조회 및 검증
• 장점
  서버가 상태를 직접 관리하므로 통제력이 높다.
  특정 기기 로그아웃, 세션 강제 만료 등의 처리가 용이하다.
• 단점
  사용자가 증가할수록 서버 메모리 부담이 커진다.
  서버가 여러 대일 경우 세션 공유를 위한 추가 구성(Session Clustering)이 필요하다.
  수평 확장(Scale-out)이 비교적 복잡하다.

JWT(Token) 방식
사용자 정보를 서명된 토큰에 담아 클라이언트에 전달하고 서버는 이를 저장하지 않는 구조이다. 즉 서버가 상태를 저장하지 않는 Stateless 구조를 가진다.

• 흐름
  로그인 성공 -> 서버가 사용자 정보를 포함한 JWT 발급 -> 클라이언트가 토큰을 저장 -> 요청 시 Authorization 헤더에 Bearer 토큰 포함 -> 서버는 토큰의 서명 및 만료 여부만 검증
• 장점
  서버가 상태를 저장하지 않아 확장에 유리하다.
  모바일 앱, 웹 등 다양한 클라이언트에서 동일한 인증 체계를 사용할 수 있다.
  마이크로 서비스 환경에서 특히 효율적이다.
• 단점
  발급된 토큰은 만료 전까지 서버가 강제로 무효화하기 어렵다.
  토큰이 커질수록 네트워크 트래픽이 증가할 수 있다.
  탈취 시 만료 전까지 사용될 위험이 있다.

어떤 방식이 절대적으로 항상 좋다고 보기는 어렵다. 서비스의 규모, 확장 계획, 인프라 구조에 따라 적절한 방식을 선택해야 한다. 이번 블로그 CMS 프로젝트에서는 확장성과 무상태 구조를 경험해 보기 위해 JWT 방식을 채택하였다.

4. JWT의 구조

JWT(Json Web Token)는 점(.)으로 구분된 세 부분으로 구성된다.

Header.Payload.Signature

각 부분이 어떤 역할을 하는지 살펴보자.

Header (헤더)
토큰에 대한 메타데이터를 담고 있는 영역이다. 주로 서명에 사용된 알고리즘과 토큰 타입 정보가 포함된다.

{
  "alg": "HS256", // 서명을 생성할 때 사용한 암호화 알고리즘
  "typ": "JWT" // 토큰의 타입
}

Payload (페이로드)
토큰의 핵심 영역으로 사용자에 대한 정보(Claims)를 담는다. 여기에 포함되는 각각의 정보 단위를 클레임(Claim)이라고 부른다.

[Claim의 종류]
Registered Claims
JWT 표준에서 미리 정의된 키 (iss, sub, exp, iat 등)

Public/Private Claims
개발자가 자유롭게 정의하는 데이터 (userId, role 등)

{
  "sub": "1234567890",
  "name": "BlueCool",
  "admin": true,
  "iat": 1516239022
}

중요한 점은 Payload는 암호화된 것이 아니라 Base64Url로 인코딩된 것이라는 점이다. 즉 누구나 쉽게 디코딩 하여 내용을 확인할 수 있다. 따라서 비밀번호, 주민등록번호, 이메일과 같은 민감 정보는 절대 포함해서는 안 된다.

Signature (서명)
JWT의 무결성을 보장하는 가장 중요한 부분이다. Header와 Payload를 결합한 뒤 서버만 알고 있는 비밀 키를 이용해 서명을 생성한다.

서명 생성 과정은 다음과 같다.

HMACSHA256(
  base64UrlEncode(Header) + "." +
  base64UrlEncode(Payload),
  secretKey
)​

이 서명 덕분에 서버는 별도의 DB 조회 없이도 토큰의 유효성을 검증할 수 있다. 클라이언트로부터 받은 토큰의 Header와 Payload를 가져와 자신의 Secret Key로 다시 서명을 계산해 보고 계산된 서명이 토큰에 붙어온 Signature와 일치하는지 확인한다.

만약 중간에 해커가 Payload의 role을 USER에서 ADMIN으로 바꿨다면 서버에서 다시 계산한 서명과 일치하지 않게 되어 서버는 이 토큰이 변경되었다고 판단하여 요청을 거절한다.

5. NestJS 기반 로그인 및 JWT 인증/인가 구현

1. 로그인 기능 구현
로그인 API는 사용자의 ID와 비밀번호를 검증하고 JWT Access Token과 Refresh Token을 발급하는 역할을 한다.

전역으로 JwtAuthGuard를 적용했기 때문에 로그인 API는 예외적으로 인증이 필요 없는 공개 엔드포인트로 처리해야 했다. 이를 위해 커스텀 @Public() 데코레이터를 사용하였다.

@Public() // JWT Guard 예외 처리
@Post('login')
async login(
  @Body() req: LoginRequest, 
  @Res({ passthrough: true }) res: Response,
): Promise<LoginResponse> {
  // ID/PW 검증 및 토큰 발급
  const result = await this.authService.login(req.loginId, req.password);
  
  // Refresh Token을 HttpOnly 쿠키에 저장
  this.setRefreshTokenCookie(res, result.refreshToken);
  
  // Access Token과 사용자 정보 반환
  return LoginResponse.fromResult(result);
}

private setRefreshTokenCookie(res: Response, token: string) {
  res.cookie('rt', token, {
    httpOnly: true, // 자바스크립트에서 쿠키 접근 불가 (XSS 공격 방지)
    secure: true, // HTTPS 환경에서만 전송 (네트워크 탈취 방지)
    sameSite: 'none', // 크로스 사이트 요청 시에도 쿠키 전송 (CORS 대응)
    path: '/',
    signed: true, // 쿠키 변조 방지용 서명 추가
    maxAge: 7 * 24 * 60 * 60 * 1000, // 7일 동안 유효
  })
}

Access Token은 짧은 만료 시간을 가지며 API 요청 시 Authorization 헤더에 포함되어 사용된다.

Refresh Token의 경우 장기 보관이 필요하고 탈취 위험이 더 크므로 JS 접근을 차단하기 위해 httpOnly + secure 옵션으로 보안을 강화하였다.

2. Service 계층 로그인 처리 로직

async login(loginId: string, password: string) {
  // 유저 존재 확인
  const credential = await this.userRepository.findByLoginId(loginId);
  if (!credential) throw new UnauthorizedException('아이디 또는 비밀번호가 일치하지 않습니다.');
  
  // 비밀번호 검증
  await credential.authenticate(password, async (raw, hashed) => bcrypt.compare(raw, hashed));
  
  // 로그인 상태 기록
  const snapshot = credential.getSnapshot();
  await this.userRepository.saveAuthStatus(snapshot);
  
  // Access / Refresh Token 발급
  const [accessToken, refreshToken] = await Promise.all([
    this.signAccessToken({ id: snapshot.id, role: snapshot.role }),
    this.signRefreshToken({ id: snapshot.id }),
  ]);
  
  return {
    accessToken,
    refreshToken,
    user: {
      id: snapshot.id,
      loginId: snapshot.loginId,
      role: snapshot.role,
    },
  };
}

// Access Token 발급
private async signAccessToken(user: { id: string; role: UserRole }) {
  const secret = this.configService.getOrThrow<string>('JWT_ACCESS_SECRET');
  const expiresIn = this.configService.get<string>('JWT_ACCESS_TTL') ?? '15m';
  
  return this.jwtService.signAsync(
    { sub: String(user.id), role: user.role },
    { secret, expiresIn: expiresIn as JwtSignOptions['expiresIn'] },
  );
}

// Refresh Token 발급
private async signRefreshToken(user: { id: string }) {
  const secret = this.configService.getOrThrow<string>('JWT_REFRESH_SECRET');
  const expiresIn = this.configService.get<string>('JWT_REFRESH_TTL') ?? '7d';
  
  return this.jwtService.signAsync(
    { sub: String(user.id) },
    { secret, expiresIn: expiresIn as JwtSignOptions['expiresIn'] },
  );
}

서비스에서는 ID와 PW를 검증한다. 유저가 존재하지 않는 경우와 비밀번호가 일치하지 않는 경우 둘 다 같은 에러 메시지로 처리하여 계정 정보가 노출되지 않도록 방지하였다. 이후 로그인 상태를 기록하고 토큰을 발급한다.

Access Token의 경우 짧은 TTL(Time To Live)을 가지며 Refresh Token은 상대적으로 긴 TTL을 가진다. Access Token은 모든 API 요청에 포함되므로 노출 가능성이 높기 때문이다.

또한 Access Token과 Refresh Token은 서로 다른 Secret Key로 서명하도록 분리하였다. 이를 통해 한쪽 Secret이 유출되더라도 다른 토큰까지 위조되는 상황을 방지할 수 있으며 보안 사고 발생 시 영향 범위를 최소화할 수 있다.

토큰 발급에 사용되는 jwtService는 NestJS에서 제공하는 공식 JWT 모듈인 @nestjs/jwt의 서비스이다. 해당 모듈은 내부적으로 jsonwebtoken 라이브러리를 감싸고 있으며 JWT 생성, 검증과 같은 기능을 제공한다.

3. JWT 인증 Guard 구현
로그인 이후 발급된 Access Token을 검증하고 요청자의 인증 여부를 판단하는 JwtAuthGuard를 구현하였다.

@Injectable()
export class JwtAuthGuard extends AuthGuard('jwt') {
  constructor(private readonly reflector: Reflector) {
    super();
  }
  
  canActivate(context: ExecutionContext) {
    const isPublic = this.reflector.getAllAndOverride<boolean>(IS_PUBLIC_KEY, [
      context.getHandler(),
      context.getClass(),
    ]);
    
    // @Public()이 적용된 경우 JWT 검증 생략
    if (isPublic) return true;
    
    return super.canActivate(context);
  }
  
  handleRequest<TUser = CurrentUserPayload>(err: unknown, user:TUser): TUser {
    if (err) {
      if (err instanceof Error) throw err;
      throw new UnauthorizedException(err);
    }
    
    if (!user) throw new UnauthorizedException();
    
    return user;
  }
}

AuthGuard('jwt')를 상속받아서 Passport JWT 전략을 그대로 활용하였다. Passport란 Node.js에서 인증 전략을 쉽게 구현하도록 도와주는 라이브러리이다. Local, JWT, OAuth 등 다양한 전략을 지원한다.

그중 AuthGuard('jwt')에서 'jwt'는 Passport에 등록한 전략 이름이며 이 이름을 통해 아래의 JwtStrategy와 연결된다.

super.canActivate(context)가 호출되면 다음 과정이 자동으로 실행된다.
1. 요청 헤더에서 Authorization: Bearer <token> 추출
2. 서버 Secret Key로 JWT 검증 (서명, 만료 시간 등 확인)
3. 검증 성공 시 validate() 호출
4. 반환값을 request.user에 주입
5. handleRequest() 실행

즉 Guard를 통해 전략을 실행하고 Strategy를 통해 JWT를 검증한다.

@Injectable()
export class JwtStrategy extends PassportStrategy(Strategy, 'jwt') {
  constructor(private readonly config: ConfigService) {
    super({
      jwtFromRequest: ExtractJwt.fromAuthHeaderAsBearerToken(),
      secretOrKey: config.getOrThrow<string>('JWT_ACCESS_SECRET'),
      ignoreExpiration: false,
    });
  }
  
  validate(payload: JwtPayload) {
    return { id: payload.sub, role: payload.role };
  }
}

NestJS에서 Passport 전략을 쉽게 등록하도록 도와주는 클래스인 PassportStrategy를 상속받고 super() 옵션을 설정한다.

jwtFromRequest는 어디서 JWT를 가져올지 지정하는 옵션이다. 여기서는 Authorization 헤더의 Bearer 토큰에 해당한다.

secretOrKey는 토큰 서명 검증용 비밀 키이다. 환경 변수를 통해 가져오도록 설정하였다. ignoreExpiration: false는 만료된 토큰은 자동으로 거부하도록 설정한다.

JWT 검증 후 Passport는 validate() 함수를 자동으로 호출하는데 검증이 완료된 payload를 가공하는 역할을 하며 이후 인가 단계에서 활용된다.

4. Role 기반 인가 구현
JWT 인증이 완료되면 request.user에는 위에서 설정한 대로 다음과 같은 정보가 담기게 된다.

{ id: payload.sub, role: payload.role }

이제 서버는 사용자의 Role(권한)을 기준으로 접근을 제어할 수 있다.

import { SetMetadata } from '@nestjs/common';
import { UserRole } from '@/user/domain/user-role.enum';

// 메타데이터를 저장할 때 사용할 고유 키 값
export const ROLES_KEY = 'roles';

// 데코레이터가 적용된 클래스 또는 메서드에 필요한 권한 배열을 메타데이터로 저장한다.
export const Roles = (...roles: UserRole[]) => SetMetadata(ROLES_KEY, roles);

@Roles() 데코레이터는 특정 API에 필요한 권한을 메타데이터로 등록하는 역할을 한다.

SetMetadata는 내부적으로 해당 핸들러(또는 클래스)에 키-값 형태의 데이터를 붙인다.

import { CanActivate, ExecutionContext, ForbiddenException, Injectable } from '@nestjs/common';
import { Reflector } from '@nestjs/core';
import { UserRole } from '@/user/domain/user-role.enum';
import { ROLES_KEY } from '@/auth/presentation/decorators/roles.decorator';​
import { RequestWithUser } from '@/auth/presentation/types/auth-request.type';

@Injectable()
export class RolesGuard implements CanActivate {
  constructor(private readonly reflector: Reflector) {}
  
  canActivate(context: ExecutionContext): boolean {
    const required = this.reflector.getAllAndOverride<UserRole[]>(ROLES_KEY, [
      context.getHandler(),
      context.getClass(),
    ]);
    
    // 권한 지정이 없는 경우 통과
    if (!required || required.length === 0) return true;
    
    const req = context.switchToHttp().getRequest<RequestWithUser>();
    
    const user = req.user;
    if (!user?.role) throw new ForbiddenException('권한 정보가 없습니다.');
    if (!required.includes(user.role)) throw new ForbiddenException('접근 권한이 없습니다.');
    
    return true;
  }
}

RolesGuard는 @Roles() 데코레이터로 선언된 권한 정보를 Reflector를 통해 조회하고 request.user에 저장된 사용자 역할과 비교하여 접근 가능 여부를 결정한다.

인증과 인가를 Guard 계층에서 분리함으로써 책임이 명확해지고 확장 가능한 구조를 만들 수 있었다.