API Gateway 패턴 — 단일 진입점으로 인증/인가/프록시 중앙 처리

개념

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

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

왜 쓰는가

클라이언트가 서비스마다 주소를 알 필요 없음
인증/인가 로직이 각 서비스에 흩어지지 않음
CORS, Rate Limit, 로깅 같은 공통 관심사를 한 곳에서 처리
백엔드 서비스는 게이트웨이 뒤에 숨겨서 직접 노출 안 함

요청 흐름

일반적인 처리 순서:

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

BFF Gateway

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

브라우저 ←(세션 쿠키만)→ API Gateway ←(access token)→ 백엔드 서비스

로그인: 게이트웨이가 [[OAuth-OIDC-SAML|OIDC]] PKCE 흐름 처리
세션: Redis에 access/refresh token 저장, 브라우저엔 세션 ID 쿠키만 발급
쿠키 설정: HttpOnly, Secure, SameSite=Lax → [[XSS-CSRF|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 재사용 감지 시 전체 세션 폐기
[[XSS-CSRF|CSRF]] 검증 — 상태 변경 요청(POST/PUT/DELETE)에 Origin 검증

API Gateway vs Reverse Proxy

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

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

관측성

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

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