JWT Authentication System 구현 가이드: Node.js 백엔드 개발 중심

현대 웹 애플리케이션에서 사용자 인증은 보안과 직결되는 핵심 기능입니다. 특히 RESTful API 기반의 서비스에서는 Stateless한 인증 방식이 선호되며, JWT(JSON Web Token)는 이러한 요구사항을 충족시키는 강력한 솔루션으로 자리매김했습니다. 이 글에서는 Node.js 환경에서 JWT 기반의 인증 시스템을 설계하고 구현하는 과정을 백엔드 개발 관점에서 심층적으로 다루고자 합니다.

JWT(JSON Web Token)란 무엇인가요?

JWT는 클라이언트와 서버 간에 정보를 안전하게 교환하기 위한 간결하고 자체 포함(self-contained)된 표준입니다. 이 토큰은 JSON 객체 형태로 정보를 담고 있으며, 디지털 서명을 통해 정보의 무결성과 신뢰성을 보장합니다. JWT는 주로 인증(Authentication) 및 정보 교환(Information Exchange)에 사용됩니다.

JWT의 구조

JWT는 .으로 구분된 세 부분으로 구성됩니다: Header.Payload.Signature.

1. Header (헤더)
   • 토큰의 타입(typ)과 서명에 사용될 알고리즘(alg)을 정의하는 JSON 객체입니다.
   • 예시: {"alg": "HS256", "typ": "JWT"}
   • 이 JSON 객체는 Base64Url로 인코딩되어 JWT의 첫 번째 부분이 됩니다.

1. Payload (페이로드)
   • 클레임(Claim)이라고 불리는 실제 정보가 담기는 부분입니다. 클레임은 사용자 ID, 권한, 토큰 만료 시간 등 필요한 데이터를 포함합니다.
   • 등록 클레임 (Registered Claims): iss (발급자), exp (만료 시간), sub (주제), aud (대상) 등 미리 정의된 클레임입니다.
   • 공개 클레임 (Public Claims): 충돌 방지를 위해 IANA JWT Registry에 등록되거나 URI 형태의 이름을 갖는 클레임입니다.
   • 비공개 클레임 (Private Claims): 클라이언트와 서버 간에 협의된 비공개 정보로, 충돌 가능성이 있어 주의해야 합니다.
   • 예시: {"sub": "1234567890", "name": "John Doe", "iat": 1516239022}
   • 이 JSON 객체도 Base64Url로 인코딩되어 JWT의 두 번째 부분이 됩니다.

1. Signature (서명)
   • 인코딩된 헤더, 인코딩된 페이로드, 그리고 서버의 비밀 키(Secret Key)를 사용하여 생성됩니다.
   • 서명은 토큰이 변조되지 않았음을 확인하는 데 사용됩니다. 서버는 토큰을 받을 때 이 서명을 다시 계산하여 일치하는지 확인합니다.
   • 생성 방식: HMACSHA256(base64UrlEncode(header) + "." + base64UrlEncode(payload), secret)

JWT의 장점과 단점

장점:

• Stateless: 서버가 클라이언트의 상태를 유지할 필요가 없어 서버 확장에 용이합니다.
• 확장성: 여러 서비스 간에 동일한 토큰을 사용하여 SSO(Single Sign-On)를 구현할 수 있습니다.
• 모바일 친화적: 모바일 환경에서 쿠키를 사용하기 어려운 경우에도 쉽게 적용할 수 있습니다.
• 보안: 디지털 서명을 통해 토큰의 위변조를 방지합니다.

단점:

• 토큰 탈취 시 위험: 한 번 발급된 토큰은 만료되기 전까지 유효하므로 탈취될 경우 보안에 취약합니다.
• 토큰 만료 관리: 토큰의 유효 기간을 짧게 가져가야 하지만, 너무 짧으면 사용자 경험이 저하됩니다. 만료된 토큰을 갱신하는 메커니즘이 필요합니다.
• 오버헤드: 쿠키나 세션 ID에 비해 토큰 자체의 크기가 커질 수 있어, 매 요청마다 전송되는 데이터 양이 증가할 수 있습니다.

JWT 인증 시스템 아키텍처 설계

안전하고 효율적인 JWT 인증 시스템을 구축하기 위해서는 Access Token과 Refresh Token을 함께 사용하는 전략이 일반적입니다.

Access Token과 Refresh Token 전략

1. Access Token:
   • 실제 API에 접근할 때 사용하는 토큰입니다.
   • 유효 기간을 짧게(예: 15분 ~ 30분) 설정하여 토큰 탈취 시 피해를 최소화합니다.
   • 클라이언트가 API 요청 시 HTTP Header의 Authorization 필드에 Bearer 타입으로 포함하여 전송합니다.

1. Refresh Token:
   • Access Token이 만료되었을 때, 새로운 Access Token을 발급받기 위한 용도로 사용됩니다.
   • 유효 기간을 길게(예: 7일 ~ 30일) 설정합니다.
   • 탈취 위험을 줄이기 위해 Access Token보다 더 안전한 방식으로 저장하고 관리해야 합니다. (예: HttpOnly Secure 쿠키, 서버 측 DB/Redis 저장)

클라이언트-서버 간 JWT 인증 흐름

다음은 일반적인 JWT 인증 시스템의 아키텍처 다이어그램(텍스트)과 흐름입니다.

+----------+           +-------------------+           +--------------+
| Client   |           | Backend Server    |           | Database     |
| (Browser/ |           | (Node.js/Express) |           | (User/Token) |
| Mobile)  |           |                   |           |              |
+----------+           +-------------------+           +--------------+
     |                         |                               |
     | 1. 로그인 요청 (ID/PW)  |                               |
     |------------------------>|                               |
     |                         | 2. 사용자 인증 및 토큰 생성   |
     |                         |<------------------------------| (DB에서 사용자 조회 및 비밀번호 검증)
     |                         | 3. Access Token, Refresh Token 발급 |
     |<------------------------|  (Access Token은 응답 본문에, Refresh Token은 쿠키/DB)
     |                         |                               |
     | 4. API 요청 (Access Token) |                               |
     |------------------------>| 5. 토큰 검증 미들웨어          |
     |                         |   (Access Token 유효성 검사)    |
     |                         | 6. 요청 처리                  |
     |<------------------------|                               |
     |                         |                               |
     | 7. Access Token 만료 시 |                               |
     |    Refresh Token으로    |                               |
     |    Access Token 재발급 요청 |                             |
     |------------------------>| 8. Refresh Token 검증 및     |
     |                         |    새 Access Token 발급       |
     |<------------------------|                               |

Node.js 환경 설정 및 필수 라이브러리

Node.js 환경에서 JWT 인증 시스템을 구축하기 위해 필요한 핵심 라이브러리들을 소개합니다.

# 프로젝트 초기화
npm init -y

# 필요한 라이브러리 설치
npm install express jsonwebtoken bcrypt dotenv mongoose

• express: Node.js 웹 애플리케이션 프레임워크입니다.
• jsonwebtoken: JWT를 생성하고 검증하는 데 사용됩니다.
• bcrypt: 비밀번호를 안전하게 해싱하고 검증하는 데 사용됩니다.
• dotenv: .env 파일에 정의된 환경 변수를 로드하는 데 사용됩니다.
• mongoose: (선택 사항) MongoDB와 연동할 때 사용하는 ODM(Object Data Modeling) 라이브러리입니다. 이 가이드에서는 MongoDB를 사용하는 것으로 가정합니다.

사용자 등록 (회원가입) API 구현

가장 먼저 사용자가 서비스에 가입할 수 있는 API를 구현합니다. 이때 비밀번호는 반드시 해싱하여 저장해야 합니다.

// server.js 또는 app.js (메인 파일)
require('dotenv').config(); // .env 파일 로드
const express = require('express');
const mongoose = require('mongoose');
const bcrypt = require('bcrypt');
const jwt = require('jsonwebtoken');

const app = express();
app.use(express.json()); // JSON 요청 본문 파싱

// MongoDB 연결
mongoose.connect(process.env.MONGODB_URI, {
    useNewUrlParser: true,
    useUnifiedTopology: true,
})
.then(() => console.log('MongoDB connected'))
.catch(err => console.error('MongoDB connection error:', err));

// 가상의 User 모델 (실제 프로젝트에서는 별도 파일로 분리)
const UserSchema = new mongoose.Schema({
    username: { type: String, required: true, unique: true },
    password: { type: String, required: true },
});

UserSchema.pre('save', async function(next) {
    if (this.isModified('password')) {
        this.password = await bcrypt.hash(this.password, 10); // 비밀번호 해싱
    }
    next();
});

const User = mongoose.model('User', UserSchema);

// 가상의 Refresh Token 모델
const TokenSchema = new mongoose.Schema({
    userId: { type: mongoose.Schema.Types.ObjectId, ref: 'User', required: true },
    token: { type: String, required: true },
    createdAt: { type: Date, default: Date.now, expires: '7d' } // 7일 후 자동 삭제
});
const Token = mongoose.model('Token', TokenSchema);


// --- API 라우트 시작 ---

// 회원가입 API
app.post('/api/register', async (req, res) => {
    try {
        const { username, password } = req.body;
        const user = new User({ username, password });
        await user.save();
        res.status(201).json({ message: '회원가입 성공!' });
    } catch (error) {
        if (error.code === 11000) { // 중복 사용자 에러
            return res.status(409).json({ message: '이미 존재하는 사용자 이름입니다.' });
        }
        res.status(500).json({ message: '서버 에러 발생', error: error.message });
    }
});

// ... (다른 API 라우트)

const PORT = process.env.PORT || 3000;
app.listen(PORT, () => console.log(`Server running on port ${PORT}`));

.env 파일 예시:

MONGODB_URI=mongodb://localhost:27017/jwt_auth_db
ACCESS_TOKEN_SECRET=your_access_token_secret_key
REFRESH_TOKEN_SECRET=your_refresh_token_secret_key

주의: ACCESS_TOKEN_SECRET과 REFRESH_TOKEN_SECRET은 복잡하고 긴 문자열로 설정해야 합니다.

로그인 및 토큰 발급 API 구현

사용자가 로그인하면, 입력된 비밀번호를 검증하고 Access Token과 Refresh Token을 발급합니다. Refresh Token은 데이터베이스에 저장하여 재사용 및 관리합니다.

// ... (이전 코드 이어서)

// 로그인 및 토큰 발급 API
app.post('/api/login', async (req, res) => {
    try {
        const { username, password } = req.body;

        const user = await User.findOne({ username });
        if (!user) {
            return res.status(400).json({ message: '사용자를 찾을 수 없습니다.' });
        }

        const isMatch = await bcrypt.compare(password, user.password);
        if (!isMatch) {
            return res.status(400).json({ message: '비밀번호가 일치하지 않습니다.' });
        }

        // Access Token 생성 (15분 유효)
        const accessToken = jwt.sign(
            { id: user._id, username: user.username },
            process.env.ACCESS_TOKEN_SECRET,
            { expiresIn: '15m' }
        );

        // Refresh Token 생성 (7일 유효)
        const refreshToken = jwt.sign(
            { id: user._id }, // Refresh Token에는 최소한의 정보만 담는 것이 좋습니다.
            process.env.REFRESH_TOKEN_SECRET,
            { expiresIn: '7d' }
        );

        // 기존 Refresh Token이 있다면 삭제 후 새로 저장 (또는 여러 개 허용)
        await Token.deleteMany({ userId: user._id }); // 기존 토큰 무효화
        const newToken = new Token({ userId: user._id, token: refreshToken });
        await newToken.save();

        // Refresh Token을 HttpOnly Secure 쿠키로 전송 (클라이언트 JS 접근 불가)
        res.cookie('refreshToken', refreshToken, {
            httpOnly: true, // JavaScript에서 접근 불가
            secure: process.env.NODE_ENV === 'production', // HTTPS에서만 전송
            sameSite: 'strict', // CSRF 방지
            maxAge: 7 * 24 * 60 * 60 * 1000 // 7일
        });

        res.json({
            accessToken,
            message: '로그인 성공!'
        });
    } catch (error) {
        res.status(500).json({ message: '서버 에러 발생', error: error.message });
    }
});

res.cookie를 사용하여 Refresh Token을 HttpOnly 쿠키로 설정하는 것이 클라이언트 localStorage에 저장하는 것보다 보안상 더 권장됩니다.

인증 미들웨어 구현

보호된 API 라우트에 접근하기 전에 Access Token의 유효성을 검증하는 미들웨어를 구현합니다.

// ... (이전 코드 이어서)

// 인증 미들웨어
const authenticateToken = (req, res, next) => {
    const authHeader = req.headers['authorization'];
    const token = authHeader && authHeader.split(' ')[1]; // Bearer <token>

    if (token == null) {
        return res.status(401).json({ message: 'Access Token이 필요합니다.' });
    }

    jwt.verify(token, process.env.ACCESS_TOKEN_SECRET, (err, user) => {
        if (err) {
            // 토큰 만료 또는 유효하지 않은 토큰
            return res.status(403).json({ message: 'Access Token이 유효하지 않거나 만료되었습니다.' });
        }
        req.user = user; // 요청 객체에 사용자 정보 추가
        next();
    });
};

// 보호된 API 예시
app.get('/api/protected', authenticateToken, (req, res) => {
    res.json({
        message: '보호된 리소스에 접근했습니다!',
        user: req.user
    });
});

Refresh Token을 이용한 토큰 재발급

Access Token이 만료되었을 때, 클라이언트는 Refresh Token을 사용하여 새로운 Access Token을 요청할 수 있습니다.

// ... (이전 코드 이어서)

// Access Token 재발급 API
app.post('/api/refresh-token', async (req, res) => {
    const refreshToken = req.cookies.refreshToken; // HttpOnly 쿠키에서 Refresh Token 가져오기

    if (!refreshToken) {
        return res.status(401).json({ message: 'Refresh Token이 없습니다.' });
    }

    try {
        // 데이터베이스에 저장된 Refresh Token인지 확인
        const storedToken = await Token.findOne({ token: refreshToken });
        if (!storedToken) {
            return res.status(403).json({ message: '유효하지 않은 Refresh Token입니다.' });
        }

        // Refresh Token 검증
        jwt.verify(refreshToken, process.env.REFRESH_TOKEN_SECRET, (err, user) => {
            if (err) {
                // Refresh Token도 만료되었거나 유효하지 않음
                return res.status(403).json({ message: 'Refresh Token이 유효하지 않거나 만료되었습니다.' });
            }

            // 새로운 Access Token 발급
            const newAccessToken = jwt.sign(
                { id: user.id, username: user.username }, // Refresh Token에 사용자 이름이 없으므로 DB에서 조회 필요
                process.env.ACCESS_TOKEN_SECRET,
                { expiresIn: '15m' }
            );

            res.json({ accessToken: newAccessToken });
        });
    } catch (error) {
        res.status(500).json({ message: '서버 에러 발생', error: error.message });
    }
});

// 로그아웃 API
app.post('/api/logout', async (req, res) => {
    const refreshToken = req.cookies.refreshToken;

    if (!refreshToken) {
        return res.status(204).send(); // 이미 로그아웃된 상태
    }

    try {
        await Token.deleteOne({ token: refreshToken }); // DB에서 Refresh Token 삭제
        res.clearCookie('refreshToken', {
            httpOnly: true,
            secure: process.env.NODE_ENV === 'production',
            sameSite: 'strict'
        });
        res.status(200).json({ message: '로그아웃 성공!' });
    } catch (error) {
        res.status(500).json({ message: '서버 에러 발생', error: error.message });
    }
});

로그아웃 시에는 서버에 저장된 Refresh Token을 삭제하고, 클라이언트의 쿠키에서도 Refresh Token을 제거해야 합니다.

보안 고려사항 및 추가 팁

JWT 인증 시스템의 보안을 강화하기 위한 몇 가지 중요한 고려사항입니다.

• HTTPS 사용: 모든 통신은 반드시 HTTPS를 통해 이루어져야 합니다. HTTP 사용 시 토큰이 중간에 탈취될 위험이 있습니다.
• Refresh Token 관리:
  • 저장 위치: HttpOnly, Secure 속성을 가진 쿠키에 저장하거나, 서버 측 데이터베이스(Redis 등)에 저장하는 것이 가장 안전합니다. localStorage에 저장하는 것은 XSS 공격에 취약하므로 피해야 합니다.
  • 만료: Refresh Token도 유효 기간을 설정하고, 일정 기간 사용하지 않거나 의심스러운 활동이 감지되면 즉시 만료시켜야 합니다.
  • 재사용 방지: Refresh Token이 한 번 사용되면 즉시 폐기하고 새로운 Refresh Token을 발급하는 One-Time Use 전략을 고려할 수 있습니다.
• Access Token 관리:
  • 저장 위치: localStorage는 XSS 공격에 취약하므로, sessionStorage에 저장하거나, SPA(Single Page Application)의 경우 메모리에 저장 후 요청 시마다 주입하는 방식을 고려할 수 있습니다.
  • 짧은 유효 기간: Access Token은 유효 기간을 매우 짧게(15분~30분) 설정하여 탈취 시 피해를 최소화합니다.
• 비밀번호 해싱: bcrypt와 같이 강력한 해싱 알고리즘을 사용하여 비밀번호를 저장해야 합니다. 솔트(Salt)를 충분히 길게 사용하고, 반복 횟수를 높여 무차별 대입 공격에 대비해야 합니다.
• 환경 변수 관리: ACCESS_TOKEN_SECRET, REFRESH_TOKEN_SECRET과 같은 중요한 정보는 .env 파일을 통해 환경 변수로 관리하고, Git 저장소에 포함되지 않도록 .gitignore에 추가해야 합니다.
• Rate Limiting: 로그인 및 회원가입 API에 Rate Limiting을 적용하여 무차별 대입 공격(Brute-force attack)을 방지해야 합니다.
• 토큰 블랙리스트: 로그아웃 시 Access Token을 즉시 무효화하려면, 해당 토큰을 블랙리스트에 추가하여 더 이상 유효하지 않음을 서버에서 관리해야 합니다. Redis와 같은 인메모리 데이터베이스를 활용하면 효율적으로 구현할 수 있습니다.

마무리

JWT는 Stateless한 특성 덕분에 확장성이 뛰어난 API 서버를 구축하는 데 매우 효과적인 인증 방식입니다. 이 글에서 다룬 Node.js 기반의 JWT 인증 시스템 구현 가이드와 보안 고려사항을 바탕으로, 여러분의 백엔드 서비스에 안전하고 견고한 인증 메커니즘을 성공적으로 적용하시기를 바랍니다. Access Token과 Refresh Token 전략, 그리고 적절한 보안 조치를 통해 사용자 경험과 시스템의 안정성 모두를 확보할 수 있습니다.