Node.js API를 활용한 JWT Authentication 시스템 구현 가이드

현대의 웹 애플리케이션 및 모바일 API에서 사용자 인증은 필수적인 요소입니다. 그중에서도 JWT(JSON Web Token)는 Stateless하고 확장성이 뛰어나다는 장점 덕분에 널리 사용되는 인증 방식으로 자리매김했습니다. 이 글에서는 Node.js 환경에서 Express.js 프레임워크를 활용하여 JWT 기반의 강력한 인증 시스템을 구축하는 방법을 단계별로 상세하게 설명해 드립니다. 안전한 API를 개발하기 위한 핵심적인 지식과 실제 코드 예제를 통해 여러분의 백엔드 개발 역량을 한층 더 향상시킬 수 있을 것입니다.

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

JWT는 클라이언트와 서버 간의 정보 교환을 안전하게 하기 위해 고안된 컴팩트하고 URL-safe한 토큰 형식입니다. 주로 사용자 인증 및 인가(Authorization)에 사용되며, 서버가 클라이언트에 토큰을 발행하면 클라이언트는 이 토큰을 매 요청마다 서버로 전송하여 자신이 누구인지, 어떤 권한을 가지고 있는지 증명합니다.

JWT는 세 가지 부분으로 구성됩니다. 각 부분은 .으로 구분됩니다.

1. Header (헤더): 토큰의 타입 (typ)과 서명에 사용될 알고리즘 (alg)을 명시합니다. (예: HS256, RS256)
2. Payload (페이로드): 토큰에 담을 정보를 포함합니다. 이 정보를 "클레임(Claim)"이라고 부르며, 사용자 ID, 권한, 토큰 만료 시간 등 필요한 데이터를 담을 수 있습니다.
3. Signature (서명): 인코딩된 헤더와 페이로드, 그리고 서버에만 알려진 Secret Key를 이용하여 생성됩니다. 이 서명 덕분에 토큰이 변조되지 않았음을 확인할 수 있습니다.

JWT의 장점:

• Stateless: 서버가 클라이언트의 인증 상태를 저장할 필요가 없어 서버의 확장성이 향상됩니다.
• Compact: 토큰 자체가 필요한 정보를 담고 있어 네트워크 오버헤드가 적습니다.
• Security: 서명을 통해 토큰의 무결성을 보장하여 변조를 방지합니다.

JWT의 단점:

• No Easy Revocation: 한 번 발급된 토큰은 만료되기 전까지 유효하므로, 탈취되었을 경우 즉시 무효화하기 어렵습니다.
• Payload Size: 페이로드에 너무 많은 정보를 담으면 토큰 크기가 커져 네트워크 부하를 줄 수 있습니다.
• Storage: 클라이언트 측에서 토큰을 안전하게 저장하는 방법에 대한 고려가 필요합니다.

JWT 기반 인증 시스템 아키텍처

JWT 기반 인증 시스템은 일반적으로 Access Token과 Refresh Token을 함께 사용하여 보안성과 사용자 경험을 모두 고려합니다. 다음은 기본적인 흐름을 나타내는 아키텍처 다이어그램입니다.

+-------------------+                                               +-------------------+
|     클라이언트      |                                               |      백엔드 서버    |
| (웹/모바일 앱)     |                                               | (Node.js API)     |
+-------------------+                                               +-------------------+
        |                                                                     |
        | 1. 사용자 로그인 요청 (ID/PW)                                       |
        +-------------------------------------------------------------------->|
        |                                                                     |
        |                                             +-------------------+   |
        |                                             |   사용자 DB       |   |
        |                                             +-------------------+   |
        |                                                       ^             |
        |                                                       | 2. 사용자 정보 검증 |
        |                                                                     |
        |<--------------------------------------------------------------------+
        | 3. Access Token & Refresh Token 발급 (JWT)                          |
        |                                                                     |
        | (Access Token: 단기 유효, Refresh Token: 장기 유효)                 |
        |                                                                     |
        |                                                                     |
        | 4. 보호된 API 요청 (Access Token 포함)                              |
        +-------------------------------------------------------------------->|
        | (HTTP Header: Authorization: Bearer <Access Token>)                 |
        |                                                                     |
        |                                             +-------------------+   |
        |                                             |   토큰 검증 미들웨어  |   |
        |                                             +-------------------+   |
        |                                                       ^             |
        |                                                       | 5. Access Token 유효성 검증 |
        |                                                                     |
        | 6. 유효한 경우, API 로직 수행 및 응답                                |
        |<--------------------------------------------------------------------+
        |                                                                     |
        |                                                                     |
        | (Access Token 만료 시)                                              |
        | 7. Access Token 재발급 요청 (Refresh Token 포함)                    |
        +-------------------------------------------------------------------->|
        |                                                                     |
        |                                             +-------------------+   |
        |                                             |   Refresh Token   |   |
        |                                             |   DB (선택 사항)  |   |
        |                                             +-------------------+   |
        |                                                       ^             |
        |                                                       | 8. Refresh Token 유효성 검증 및 재사용 방지 |
        |                                                                     |
        |<--------------------------------------------------------------------+
        | 9. 새로운 Access Token 발급                                         |
        |                                                                     |

• Access Token: 짧은 만료 시간을 가지며, 실제 리소스에 접근할 때 사용됩니다. 탈취되더라도 짧은 시간 내에 만료되므로 보안 위험을 줄일 수 있습니다.
• Refresh Token: 긴 만료 시간을 가지며, Access Token이 만료되었을 때 새로운 Access Token을 발급받기 위해 사용됩니다. Refresh Token 자체는 서버에 저장하여 재사용 방지 및 강제 로그아웃 등의 관리가 필요할 수 있습니다.

Node.js 환경에서 JWT 구현 시작하기

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

• express: 웹 애플리케이션 프레임워크
• jsonwebtoken: JWT를 생성하고 검증하는 라이브러리
• bcrypt: 비밀번호를 안전하게 해싱하는 라이브러리
• dotenv: 환경 변수를 관리하는 라이브러리

먼저, 새로운 Node.js 프로젝트를 생성하고 필요한 패키지를 설치합니다.

mkdir jwt-auth-api
cd jwt-auth-api
npm init -y
npm install express jsonwebtoken bcrypt dotenv

프로젝트 루트에 .env 파일을 생성하여 JWT 서명에 사용될 Secret Key와 토큰 만료 시간을 설정합니다. 이 값들은 민감하므로 절대로 Git 저장소에 포함되어서는 안 됩니다.

# .env
JWT_ACCESS_SECRET=your_access_token_secret_key_here
JWT_REFRESH_SECRET=your_refresh_token_secret_key_here
ACCESS_TOKEN_EXPIRATION=1h
REFRESH_TOKEN_EXPIRATION=7d

server.js (또는 app.js) 파일을 생성하여 Express 서버의 기본 설정을 시작합니다.

// server.js
require('dotenv').config(); // .env 파일 로드
const express = require('express');
const app = express();
const PORT = process.env.PORT || 3000;

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

app.get('/', (req, res) => {
    res.send('JWT Auth API Server is running!');
});

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

사용자 인증 API 구현 (Login & Register)

사용자 등록(회원가입) 및 로그인 기능을 구현해보겠습니다. 여기서는 간단한 사용자 모델을 가정하며, 실제 프로덕션 환경에서는 MongoDB(Mongoose)나 PostgreSQL 등의 데이터베이스를 사용하게 됩니다.

먼저, 가상의 사용자 데이터를 저장할 배열과 JWT를 생성하는 유틸리티 함수를 만듭니다.

// utils/jwt.js
const jwt = require('jsonwebtoken');

const generateAccessToken = (user) => {
    return jwt.sign({ id: user.id, username: user.username }, process.env.JWT_ACCESS_SECRET, {
        expiresIn: process.env.ACCESS_TOKEN_EXPIRATION,
    });
};

const generateRefreshToken = (user) => {
    return jwt.sign({ id: user.id, username: user.username }, process.env.JWT_REFRESH_SECRET, {
        expiresIn: process.env.REFRESH_TOKEN_EXPIRATION,
    });
};

module.exports = { generateAccessToken, generateRefreshToken };

다음으로, 사용자 모델과 인증 라우트를 구현합니다. 실제 데이터베이스를 사용한다면 users 배열 대신 데이터베이스 쿼리를 사용하게 됩니다.

// routes/auth.js
const express = require('express');
const router = express.Router();
const bcrypt = require('bcrypt');
const { generateAccessToken, generateRefreshToken } = require('../utils/jwt');

// 가상의 사용자 데이터 (실제는 DB 사용)
const users = [];
// 가상의 Refresh Token 저장소 (실제는 DB 사용)
const refreshTokens = [];

// 회원가입
router.post('/register', async (req, res) => {
    const { username, password } = req.body;

    if (!username || !password) {
        return res.status(400).json({ message: '사용자 이름과 비밀번호를 입력해주세요.' });
    }

    if (users.find(u => u.username === username)) {
        return res.status(409).json({ message: '이미 존재하는 사용자 이름입니다.' });
    }

    try {
        const hashedPassword = await bcrypt.hash(password, 10);
        const newUser = { id: users.length + 1, username, password: hashedPassword };
        users.push(newUser);
        res.status(201).json({ message: '회원가입 성공', user: { id: newUser.id, username: newUser.username } });
    } catch (error) {
        res.status(500).json({ message: '서버 오류 발생', error: error.message });
    }
});

// 로그인
router.post('/login', async (req, res) => {
    const { username, password } = req.body;

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

    try {
        const isMatch = await bcrypt.compare(password, user.password);
        if (!isMatch) {
            return res.status(401).json({ message: '잘못된 비밀번호입니다.' });
        }

        const accessToken = generateAccessToken(user);
        const refreshToken = generateRefreshToken(user);

        // Refresh Token을 저장 (보안을 위해 DB에 저장하는 것이 일반적)
        refreshTokens.push(refreshToken);

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

module.exports = router;

server.js에 인증 라우트를 추가합니다.

// server.js (일부)
// ...
const authRoutes = require('./routes/auth');
app.use('/api/auth', authRoutes);
// ...

JWT 미들웨어 구현 및 보호된 라우트

발급된 Access Token을 검증하여 보호된 API 엔드포인트에 접근할 수 있도록 미들웨어를 구현해야 합니다. 또한, Access Token이 만료되었을 때 Refresh Token을 사용하여 새로운 Access Token을 발급받는 로직도 필요합니다.

// middleware/auth.js
const jwt = require('jsonwebtoken');

const verifyToken = (req, res, next) => {
    const authHeader = req.headers['authorization'];
    if (!authHeader) {
        return res.status(401).json({ message: '인증 토큰이 필요합니다.' });
    }

    const token = authHeader.split(' ')[1]; // "Bearer <token>"
    if (!token) {
        return res.status(401).json({ message: '인증 토큰 형식이 잘못되었습니다.' });
    }

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

module.exports = verifyToken;

이제 routes/auth.js에 Refresh Token을 사용하여 Access Token을 재발급하는 라우트를 추가합니다.

// routes/auth.js (일부)
// ...
const jwt = require('jsonwebtoken'); // 추가

// Access Token 재발급
router.post('/token/refresh', (req, res) => {
    const { refreshToken } = req.body;

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

    if (!refreshTokens.includes(refreshToken)) { // 가상의 저장소 확인
        return res.status(403).json({ message: '유효하지 않은 Refresh Token입니다.' });
    }

    jwt.verify(refreshToken, process.env.JWT_REFRESH_SECRET, (err, user) => {
        if (err) {
            return res.status(403).json({ message: '유효하지 않거나 만료된 Refresh Token입니다.' });
        }

        // Refresh Token이 유효하면 새로운 Access Token 발급
        const newAccessToken = generateAccessToken(user);
        res.json({ accessToken: newAccessToken });
    });
});

// 로그아웃 (Refresh Token 삭제)
router.post('/logout', (req, res) => {
    const { refreshToken } = req.body;

    // 실제 DB에서는 해당 Refresh Token을 무효화하거나 삭제
    const index = refreshTokens.indexOf(refreshToken);
    if (index > -1) {
        refreshTokens.splice(index, 1);
    }
    res.status(204).send(); // No Content
});

module.exports = router;

이제 보호된 라우트를 만들고 verifyToken 미들웨어를 적용해봅니다.

// routes/protected.js
const express = require('express');
const router = express.Router();
const verifyToken = require('../middleware/auth');

// 이 라우트는 Access Token이 있어야 접근 가능합니다.
router.get('/profile', verifyToken, (req, res) => {
    // req.user는 verifyToken 미들웨어에서 추가한 사용자 정보입니다.
    res.json({ message: `안녕하세요, ${req.user.username}님!`, user: req.user });
});

router.get('/dashboard', verifyToken, (req, res) => {
    res.json({ message: `대시보드에 오신 것을 환영합니다, ${req.user.username}님!` });
});

module.exports = router;

server.js에 보호된 라우트를 추가합니다.

// server.js (일부)
// ...
const authRoutes = require('./routes/auth');
const protectedRoutes = require('./routes/protected');

app.use('/api/auth', authRoutes);
app.use('/api/protected', protectedRoutes);
// ...

보안 고려사항

JWT 인증 시스템을 구축할 때 몇 가지 중요한 보안 고려사항이 있습니다.

1. Token 저장 위치:
   • Local Storage/Session Storage: JavaScript로 접근 가능하여 XSS(Cross-Site Scripting) 공격에 취약합니다.
   • HTTP-only Cookie: JavaScript로 접근할 수 없어 XSS 공격으로부터 비교적 안전합니다. CSRF(Cross-Site Request Forgery) 공격에 대한 추가적인 방어가 필요할 수 있습니다 (예: CSRF 토큰 사용). 일반적으로 Access Token은 HTTP-only Cookie에, Refresh Token은 DB에 저장하여 관리하는 방식이 권장됩니다.
2. Refresh Token 관리: Refresh Token은 장기적으로 유효하므로, 탈취될 경우 심각한 보안 문제가 발생할 수 있습니다.
   • 데이터베이스 저장: Refresh Token을 데이터베이스에 저장하고, 사용 시마다 유효성 검사 및 재사용 방지 로직을 추가합니다.
   • 만료 및 무효화: 사용자가 로그아웃하거나 특정 보안 이벤트 발생 시 Refresh Token을 즉시 무효화할 수 있도록 관리 시스템을 구축해야 합니다.
3. HTTPS 사용: 모든 통신은 반드시 HTTPS를 통해 이루어져야 합니다. HTTP는 토큰이 평문으로 전송되어 중간자 공격(Man-in-the-Middle Attack)에 쉽게 노출될 수 있습니다.
4. Secret Key 관리: JWT 서명에 사용되는 Secret Key는 외부에 노출되어서는 안 됩니다. .env 파일을 사용하고, 프로덕션 환경에서는 환경 변수 관리 시스템이나 키 관리 서비스(KMS)를 사용하는 것이 좋습니다.
5. 비밀번호 해싱: 사용자 비밀번호는 절대로 평문으로 저장해서는 안 됩니다. bcrypt와 같은 강력한 해싱 라이브러리를 사용하여 단방향 암호화해야 합니다.
6. 토큰 만료 시간: Access Token은 짧게, Refresh Token은 길게 설정하여 보안과 편의성을 절충합니다.

마무리

이 글을 통해 Node.js와 Express.js를 활용하여 JWT 기반의 강력한 인증 시스템을 구축하는 방법에 대해 알아보았습니다. JWT의 기본 개념부터 Access Token과 Refresh Token을 활용한 아키텍처, 그리고 실제 코드 구현까지 살펴보았습니다.

안전한 백엔드 API를 구축하기 위해서는 JWT 구현뿐만 아니라 XSS, CSRF와 같은 웹 보안 취약점에 대한 이해와 방어, 그리고 적절한 로깅 및 에러 핸들링 전략이 필수적입니다. 이 가이드를 기반으로 여러분의 서비스에 맞는 견고한 인증 시스템을 성공적으로 구현하시기를 바랍니다.