API Gateway

단일 진입점으로 인증·인가·프록시 중앙 처리

API Gateway는 모든 클라이언트 요청을 한 곳에서 받아 인증/인가/라우팅을 처리하고 백엔드 서비스로 프록시한다. BFF 패턴과 결합하면 브라우저에 토큰을 노출하지 않고 세션 쿠키만으로 인증을 단순화할 수 있다.

Gateway
아키텍처인증인가프록시bff

개념

API Gateway는 여러 백엔드 서비스 앞에 단일 진입점을 두는 패턴이다. 클라이언트는 게이트웨이 한 곳만 호출하고, 게이트웨이가 인증·인가·라우팅·프록시·관측성을 중앙에서 처리한다.

클라이언트 → Nginx(TLS) → API Gateway → 서비스 A, B, C ...

왜 필요한가

마이크로서비스를 클라이언트가 직접 호출하게 두면 여러 문제가 생긴다.

  • 클라이언트가 서비스마다 주소를 알아야 함
  • 인증·인가 로직이 각 서비스에 복제됨 (일관성 깨짐)
  • CORS, Rate Limit, 로깅 같은 공통 관심사가 중복 구현됨
  • 백엔드 서비스가 외부에 직접 노출됨

게이트웨이는 이 공통 관심사를 한 곳에 모아 서비스를 얇게 유지한다.

요청 흐름

일반적인 처리 순서:

  1. TLS 종료 — Nginx나 로드밸런서에서 HTTPS 처리
  2. 공통 미들웨어 — Trace ID 부여, IP Rate Limit
  3. 인증(Authentication) — API Key 또는 세션 쿠키 검증
  4. 인가(Authorization) — CSRF 검증, 권한 확인, Token Exchange
  5. 프록시 — 해당 백엔드 서비스로 요청 전달

BFF Gateway

BFF 패턴과 결합한 형태. 브라우저 전용 게이트웨이로 토큰 관리를 서버에서 한다.

브라우저 ←(세션 쿠키만)→ API Gateway ←(access token)→ 백엔드 서비스
  • 로그인: 게이트웨이가 OIDC Authorization Code Flow 처리
  • 세션: Redis에 access/refresh token 저장, 브라우저엔 세션 ID 쿠키만 발급
  • 쿠키 설정: HttpOnly, Secure, SameSite=Lax → XSS로 토큰 탈취 불가

Token Exchange

게이트웨이가 서비스별로 별도 토큰을 발급받는 방식. 권한 최소화 원칙을 구현하는 수단.

사용자 토큰 (전체 권한)
  → Gateway가 Keycloak에 Token Exchange 요청
  → 서비스 A 전용 토큰 (제한된 권한) 발급
  → 서비스 A로 전달
  • 경로 prefix로 어떤 서비스인지 판별 (예: /api/hr/* → HR 서비스)
  • 발급받은 토큰은 세션에 캐시해서 매번 Keycloak 호출 안 함

세션 보안

Redis 기반 세션 관리에서 신경 쓸 것들:

  • idle timeout — 일정 시간 미사용 시 세션 만료
  • absolute timeout — 최대 유지 시간 제한
  • refresh token rotation — 갱신 시 이전 토큰 무효화
  • reuse detection — 이미 사용된 refresh token 재사용 감지 시 전체 세션 폐기
  • CSRF 검증 — 상태 변경 요청(POST/PUT/DELETE)에 Origin 검증

API Gateway vs Reverse Proxy

Reverse Proxy API Gateway
역할 요청 전달, 로드밸런싱 인증/인가 + 요청 전달
로직 거의 없음 비즈니스 로직 포함 가능
조합 보통 앞단에 Nginx 둠 Nginx 뒤에 위치

실무에서는 Nginx(TLS + 로드밸런싱) → API Gateway(인증/인가/라우팅) → 서비스 구조로 같이 쓴다.

관측성

게이트웨이가 단일 진입점이니까 여기서 관측성을 확보하면 효과적.

  • Trace ID — 요청마다 고유 ID 부여, 백엔드까지 전파
  • 감사 로그 — 인증 실패, 권한 거부 등 보안 이벤트 기록
  • 표준 에러 응답 — {trace_id, error_code, message} 형태로 통일

더 보기

  • BFF — 프론트엔드 전용 게이트웨이로 토큰 보호
  • Nginx — 게이트웨이 앞단에서 TLS·로드밸런싱 담당
  • OAuth-OIDC-SAML — 게이트웨이에서 처리하는 인증 프로토콜
  • XSS-CSRF — 쿠키 기반 세션의 보안 이슈

Related

sunshinemoon · 2026