05. JWT와 유저 기능

유저 인증 기능을 구현하는 방식에는 여러 가지가 있지만, 그중에서도 나는 JWT 토큰을 발급해 쿠키로 내려주는 방식을 선호한다. 이유는 여럿 있겠지만, 가장 큰 이유는 클라이언트 측에서 별도의 처리를 거의 하지 않아도 된다는 점이다. 토큰 저장 방식이나 갱신 전략에 대해 프론트엔드가 신경 쓸 필요가 없고, 인증과 관련된 모든 흐름을 백엔드에서 일관되게 통제할 수 있다.

물론 이 방식에도 단점은 존재한다. 하지만 백엔드가 인증과 토큰 관리에 대한 전권을 가지는 구조에서는, 그러한 단점들이 충분히 상쇄된다고 생각한다. 특히 보안과 유지보수 측면에서는 이점이 더 분명하다.

Nest.js에서는 @nestjs/jwt 패키지를 사용해 JWT를 발급하고 검증한다. 이 패키지는 JwtModule과 JwtService를 제공하며, 이를 통해 토큰 생성과 검증 로직을 비교적 간단하게 구성할 수 있다. JwtModule은 동적 모듈이기 때문에 register 메서드를 호출해 생성한다. 다양한 옵션을 전달할 수 있지만, 나는 토큰의 secret과 만료 시간 등을 직접 제어하기 위해 별도의 옵션 없이 모듈을 등록하는 편이다.

import { JwtModule } from '@nestjs/jwt';

@Module({
  controllers: [AuthController],
  providers: [AuthService, AuthRepository],
  imports: [JwtModule.register({})],
})
export class AuthModule {}

JwtService는 일반적으로 서비스 레이어에서 주입받아 사용한다.

import { JwtService } from '@nestjs/jwt';
import { jwtConfig } from 'src/config/jwt.config';
import { ConfigType } from '@nestjs/config';

@Injectable()
export class AuthService {
  constructor(
    @Inject(jwtConfig.KEY) private jwt: ConfigType<typeof jwtConfig>,
    private authRepository: AuthRepository,
    private jwtService: JwtService,
  ) {}
}

JwtService는 크게 두 가지 핵심 메서드를 제공한다. 하나는 payload를 JWT로 생성하는 sign, 다른 하나는 토큰의 유효성을 검증하는 verify이다.

Express.js에서 흔히 사용하는 jsonwebtoken 패키지와 마찬가지로, verify는 토큰이 유효하면 payload를 반환하고, 문제가 있을 경우 예외를 발생시킨다. Nest.js의 JwtService 역시 이 흐름을 따르며, 토큰이 만료된 경우에는 TokenExpiredError, 토큰 자체가 잘못된 경우에는 JsonWebTokenError를 던진다. 이 예외 기반 흐름은 가드나 인터셉터와 결합하기에도 적합하다

나는 AuthService 내부에 토큰 생성, 검증, 재발급을 담당하는 메서드를 명시적으로 분리해 사용하고 있다.

generateToken(
  payload: { email: string; nickname: string },
  type: 'access' | 'refresh',
) {
  const secret =
    type === 'access'
      ? this.jwt.accessSecret
      : this.jwt.refreshSecret;

  const expiresIn = type === 'access' ? '1h' : '30d';

  return this.jwtService.sign(payload, {
    secret,
    expiresIn,
  });
}

verify(token: string, type: 'access' | 'refresh') {
  const secret =
    type === 'access'
      ? this.jwt.accessSecret
      : this.jwt.refreshSecret;

  const { email, nickname } = this.jwtService.verify(token, {
    secret,
  });

  return { email, nickname };
}

refresh(refresh: string) {
  const { email, nickname } = this.jwtService.verify(refresh, {
    secret: this.jwt.refreshSecret,
  });

  const accessToken = this.generateToken(
    { email, nickname },
    'access',
  );
  const refreshToken = this.generateToken(
    { email, nickname },
    'refresh',
  );

  return { accessToken, refreshToken };
}

물론 AuthModule에서 JwtModule을 export하면, 이를 import한 다른 모듈에서도 JwtService를 직접 사용할 수 있다. 혹은 JWT 로직이 필요한 모든 모듈에서 JwtModule을 각각 import하는 방식도 가능하다(이미지 왼쪽).

하지만 나는 유지보수 관점에서 JwtService를 오직 AuthService 내부에서만 사용하도록 제한하는 편이다. 다른 모듈에서는 JwtService 대신 AuthService를 통해서만 토큰 관련 로직에 접근하도록 한다. 이렇게 하면 JWT와 관련된 환경 변수, 토큰 생성 방식, 예외 처리 로직이 모두 AuthService에 응집된다. 결과적으로 인증 로직의 변경 범위가 명확해지고, 여러 모듈에서 JWT를 사용하는 방식도 자연스럽게 통일된다(이미지 오른쪽).

앞서 언급했듯이, 나는 토큰 관리에 대한 권한을 전적으로 백엔드가 가지는 구조를 선호한다. 이를 위해 쿠키에 토큰을 저장할 때는 반드시 httpOnly, secure, sameSite 옵션을 설정해 클라이언트가 토큰에 직접 접근하지 못하도록 해야 한다.

Nest.js에서는 컨트롤러 메서드가 값을 반환하는 방식이 일반적이지만, 쿠키를 설정해야 하는 경우에는 @Res 데코레이터를 사용해 응답 객체를 직접 다루게 된다.

@Post('signup')
async signUp(
  @Body() signUpDto: SignUpDto,
  @Res() res: Response,
) {
  const { accessToken, refreshToken } =
    await this.authService.signup(signUpDto);

  res
    .cookie('accessToken', accessToken, {
      httpOnly: true,
      secure: true,
      sameSite: 'lax',
    })
    .cookie('refreshToken', refreshToken, {
      httpOnly: true,
      secure: true,
      sameSite: 'lax',
    })
    .status(201)
    .send({ message: '회원가입 성공' });
}

이렇게 구성하면 클라이언트는 토큰의 존재조차 인식하지 못한 채 인증된 상태를 유지하게 되고, 인증 흐름 전반을 서버 중심으로 안정적으로 관리할 수 있다.

05. JWT와 유저 기능

더 읽어보기

14. Redis를 사용한 세션 관리 및 캐싱

비즈니스 로직은 어디에 있어야 할까

라이브러리를 죽여버릴 수야 없겠지만

13. Jest 테스트 구성

React Server Components를 위한 컴포넌트 아키텍처

차트는 멈췄는데 윈도우가 움직인다

피자가게로 이해하는 디자인 패턴

7. Decorator — 토핑 추가할 때마다 클래스를 새로 만들 수 없다

댓글