[Python] FastAPI JWT 인증 미들웨어 분석 – 어떻게 동작할까?

팀원이 개발한 JWT 인증 미들웨어(jwt_auth_middleware)를 분석하면서, 미들웨어가 어떻게 동작하는지, 그리고 어떤 역할을 수행하는지 살펴보겠다.

이 미들웨어는 요청과 응답을 사전에 조작 가능하도록 설계되었으며, 보안 강화를 위해 사용되었다.
즉, 클라이언트가 서버로 요청을 보낼 때 미들웨어가 이를 가로채어 검증을 수행하고, 응답을 반환하기 전에 필요한 작업을 처리하는 방식으로 구현되었다.

 

 

미들웨어(Middleware)란?

미들웨어(Middleware)는 요청(Request)과 응답(Response) 사이에서 특정 작업을 수행하는 소프트웨어 계층이다. 클라이언트가 서버에 요청을 보낼 때와 서버가 클라이언트에 응답을 반환할 때, 미들웨어는 중간에서 데이터를 가공하거나 검증하는 역할을 한다.

FastAPI에서는 @app.middleware("http") 데코레이터를 사용하여 미들웨어를 정의할 수 있다.

 

 

미들웨어를 사용하는 이유

1. 반복되는 로직을 공통적으로 관리

미들웨어를 활용하면 인증, 로깅, 에러 처리 같은 공통적인 기능을 일괄적으로 적용할 수 있다. 모든 라우트마다 개별적으로 코드를 추가할 필요 없이, 미들웨어를 통해 일괄 적용할 수 있다.

2. 요청과 응답을 사전에 조작 가능

요청을 가로채어 데이터를 검증하거나 변환할 수 있고, 응답을 반환하기 전에 데이터를 추가로 가공할 수도 있다.

3. 보안 강화

JWT 인증이나 권한 확인 같은 작업을 미들웨어에서 처리하면, 모든 엔드포인트에 적용할 수 있어 보안성을 강화할 수 있다.

4. 성능 개선

캐싱 기능을 미들웨어에서 구현하면, 불필요한 데이터베이스 쿼리를 줄이고 응답 속도를 높일 수 있다.

 

 

장점

1. 코드 재사용성 증가

미들웨어를 활용하면 여러 개의 엔드포인트에서 중복되는 로직을 줄일 수 있다.

 

2. 보안 강화

JWT 인증과 같은 기능을 미들웨어에서 일괄 처리하면 API 보안성이 향상된다.

 

3. 유연한 데이터 처리

요청과 응답을 가로채어 필요한 데이터를 추가하거나 변경할 수 있다.

 

4. 로깅 및 모니터링 용이

요청 로그, 응답 상태 코드 등을 미들웨어에서 기록하여 서버 상태를 모니터링할 수 있다.

 

 

단점

1. 응답 속도 지연 가능성

요청이 미들웨어를 거쳐야 하므로, 너무 많은 미들웨어를 사용하면 성능이 저하될 수 있다.

 

2. 디버깅 어려움

미들웨어에서 발생하는 에러가 전체 애플리케이션의 요청을 막아버릴 수 있어 디버깅이 어려울 수 있다.

 

3. 복잡한 요청 처리 시 비효율적

특정 엔드포인트에서만 필요한 검증 로직이라면, 미들웨어보다 개별 엔드포인트에서 처리하는 것이 더 적절할 수도 있다.

 

 

FastAPI에서 미들웨어 구현

위 코드에서 사용된 jwt_auth_middleware는 JWT 인증을 위한 미들웨어로 동작한다.

요청과 응답을 사전에 조작 가능하도록 설계되었으며, 보안 강화를 위해 사용되었다.
이 미들웨어의 주요 기능은 다음과 같다:

1. 공개 경로(PUBLIC_PATHS)는 인증 없이 접근 가능

PUBLIC_PATHS에 포함된 URL은 별도의 인증 절차 없이 그대로 요청을 통과시킨다.
Swagger 문서, OAuth 인증 콜백 같은 공개적으로 접근 가능한 API가 해당된다.

# JWT 인증이 필요없는 경로들
PUBLIC_PATHS = {
    "/",  # 메인 페이지
    "/docs",  # Swagger UI
    "/openapi.json",  # OpenAPI 스키마
    "/oauths/google/callback",  # 구글 OAuth
    "/oauths/kakao/callback",  # 카카오 OAuth
    "/oauths/naver/callback",  # 네이버 OAuth
    "/test/",  # 테스트 경로
}

if path in PUBLIC_PATHS:
    return await call_next(request)

 

2. JWT 토큰 확인 및 인증 처리

요청의 쿠키(cookie)에서 access_token과 refresh_token을 가져와서 검증을 수행한다.

token = request.cookies.get("access_token")
refresh_token = request.cookies.get("refresh_token")

• access_token이 없는 경우: refresh_token이 존재하면 새로운 access_token을 발급하여 쿠키에 저장한다.
• access_token이 있지만 만료된 경우: refresh_token이 있다면 재발급 시도.
• refresh_token까지 유효하지 않으면: 로그인 요청을 다시 하도록 유도한다.

 

3. 토큰 디코딩 및 사용자 정보 저장

유효한 access_token이 존재하면 JWT 토큰을 디코딩하여 사용자 정보를 request.state.user에 저장한다.
이를 통해 이후의 API 엔드포인트에서 request.state.user를 활용하여 사용자 정보를 확인할 수 있다.

user_data = decode_jwt(token)
request.state.user = user_data

 

4. JWT 토큰 재발급 처리

access_token이 만료되었을 때, refresh_token을 이용해 새로운 access_token을 생성하여 응답의 쿠키(cookie)에 저장한다.
이는 자동 로그인 유지 기능을 구현하는 핵심적인 부분이다.

new_access_token = await refresh_access_token(refresh_token)
response.set_cookie(
    key="access_token",
    value=new_access_token,
    httponly=True,
    secure=True,
    samesite="Lax",
    max_age=3600,
)

 

미들웨어라는 개념을 처음 접했는데, 팀원이 사용한 코드를 분석하면서 어렵다는 생각이 들었다.
JWT 인증이 단순히 토큰을 주고받는 것이 아니라, 요청과 응답을 가로채어 처리하는 방식이라는 점도 이해하는 데 시간이 걸렸다.
개발을 하면 할수록 알아야 할 것들이 끝없이 나오는 것 같아, 정말 배움에는 끝이 없다는 걸 다시 느낀다.