Portfolio

개념

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 패턴과 결합한 형태. 게이트웨이가 OIDC Authorization Code Flow + PKCE를 처리하고, 토큰을 서버(Redis)에만 두고 브라우저엔 세션 ID 쿠키만 발급한다.

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

쿠키 설정은 HttpOnly, Secure, SameSite=Lax가 필수다. 세션 설계 상세는 세션-보안 참조.

인가: Token Exchange

게이트웨이가 각 백엔드 서비스마다 별도 토큰을 발급받아 전달한다. 권한 최소화 원칙의 실현 수단이다. 경로 prefix로 대상 서비스를 판별한다.

/api/hr/*  → HR 서비스용 토큰
/api/dmp/* → DMP 서비스용 토큰

상세는 Token-Exchange 참조.

CSRF와 Rate Limit

쿠키 기반 세션은 CSRF에 취약하다. SameSite=Lax가 1차 방어선이지만, 상태 변경 요청(POST/PUT/DELETE)에서 Origin/Referer 헤더를 허용 목록과 대조해 이중 검증한다. 자세한 내용은 XSS-CSRF 참조.

Rate Limit은 단일 진입점인 게이트웨이에서 IP 기준과 유저 기준을 모두 적용한다. Redis 카운터로 구현하면 여러 인스턴스가 공유한다.

헤더 정책

게이트웨이가 백엔드로 포워딩할 수 있는 헤더는 허용 목록으로만 관리한다. 클라이언트가 보낸 헤더를 필터링 없이 전부 전달하면 헤더 인젝션 위험이 생긴다. 게이트웨이가 직접 붙이는 헤더(X-Forwarded-Sub 등)는 클라이언트 입력에서 제거한다.

하지 말아야 할 것들

Direct Grant(ROPC) 사용 금지

이메일+비밀번호를 게이트웨이가 직접 받아 IdP에 넘기는 방식은 OAuth 2.0 Security BCP(RFC 9700)에서 deprecated됐다. 게이트웨이가 평문 비밀번호를 중간에 처리하게 되고, MFA와 자연스럽게 연동되지 않는다. Authorization Code Flow + PKCE로 대체한다.

헤더만 신뢰하는 백엔드

일부 서비스가 토큰 검증 없이 X-User-Sub 같은 헤더만 신뢰하는 경우가 있다. 게이트웨이가 뚫리거나 내부 네트워크에서 직접 접근이 가능하면 헤더 조작으로 임의 권한 획득이 가능하다. 백엔드는 Token Exchange로 발급된 JWT를 직접 검증해야 한다. 헤더 신뢰는 mTLS + 강한 네트워크 격리가 보장될 때만 허용 가능하다.

환경별 구성

세 가지 구성은 팀 크기나 트래픽 규모가 아니라 배포 환경이 뭐냐로 구분한다. K8s와 클라우드 관리형은 겹치는 경우(EKS, GKE, AKS)도 있다.

K8s 없는 환경 (VM / Docker Compose)

브라우저 → Nginx(TLS + 로드밸런싱) → 직접 구현한 게이트웨이 → 서비스

Nginx가 TLS를 종료하고, 게이트웨이에서 PKCE·세션·Token Exchange·프록시를 직접 구현한다. 배포 단위가 VM이나 Docker Compose일 때, 또는 인증 로직을 완전히 직접 제어해야 할 때 선택한다.

클라우드 관리형 (AWS / GCP / Azure)

브라우저 → CDN → 관리형 API Gateway → 서비스
         ↗
       BFF (Lambda / Cloud Run)

AWS API Gateway, GCP Apigee, Azure API Management 같은 관리형 서비스가 Rate Limit·JWT 검증·라우팅을 처리한다. 배포 단위가 ECS, Cloud Run, Lambda 중심이고 인프라 관리를 클라우드에 위임할 때 선택한다.

BFF(PKCE + 세션 쿠키)는 관리형 API Gateway가 지원하지 않으므로 Lambda나 Cloud Run 같은 별도 서버리스 서비스로 구현한다.

서비스 간 통신은 클라우드 IAM 기반 인증으로 대체된다(AWS의 경우 IAM Role + SigV4 서명). Token Exchange 없이 IAM이 서비스 간 신뢰를 담당한다.

Kubernetes

브라우저 → Ingress Controller(Nginx / Traefik / Kong)
                    ↓
              ext-authz (인증 위임)
                    ↓
              서비스 A ←(mTLS)→ 서비스 B
              [Istio sidecar]   [Istio sidecar]

Ingress Controller

Nginx Ingress, Traefik, Kong Ingress가 TLS 종료와 L7 라우팅을 담당한다. cert-manager가 Let's Encrypt 인증서를 자동으로 발급·갱신한다.

K8s 1.28+에서는 Ingress를 대체하는 Gateway API가 표준으로 자리잡고 있다. GatewayClass, Gateway, HTTPRoute 리소스로 라우팅을 선언적으로 정의한다. Ingress보다 표현력이 높고 멀티 팀 환경에 적합하다.

ext-authz

Envoy의 external authorization 필터. Ingress Controller나 사이드카 프록시가 각 요청을 외부 인증 서비스로 위임해 검증한다. 인증 로직을 라우팅 레이어와 분리할 수 있다.

요청 → Envoy → ext-authz 서비스 (인증·인가 판단) → 허용/거부
                         ↓ 허용
                      백엔드 서비스

Service Mesh (Istio / Linkerd)

사이드카 프록시(Envoy)가 서비스 간 통신에 mTLS를 자동 처리한다. 서비스마다 SPIFFE 기반 워크로드 ID가 발급되어, 별도 Token Exchange 없이 서비스 간 신뢰가 구현된다. 인증서 발급·교체도 컨트롤 플레인이 자동 관리한다.

BFF는 여전히 별도

K8s 환경에서도 브라우저 클라이언트를 위한 PKCE + 세션 쿠키는 별도 Deployment로 운영한다. Ingress Controller나 Service Mesh는 이 역할을 대신하지 않는다.

API Gateway vs Reverse Proxy

	Reverse Proxy (Nginx 등)	API Gateway
역할	요청 전달, 로드밸런싱	인증·인가 + 요청 전달
로직	거의 없음	비즈니스 로직 포함
위치	게이트웨이 앞단	Nginx 뒤

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

관측성

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

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

개념