이 문서를 통해 아래 질문들에 답할 수 있게 됩니다.
- API Gateway와 WAF가 앱 앞에서 어떤 정책을 실행하고 어떤 장애를 만들 수 있는가?
- WAF 403, gateway 429, body limit 413, auth 401을 앱 장애와 어떻게 구분하는가?
- gateway/WAF 정책을 인프라·보안 팀과 협업할 때 무엇을 문서화해야 하는가?
개요
API Gateway는 API 경계 정책을 중앙화하는 계층이고, WAF는 웹 공격 패턴과 악성 트래픽을 차단하는 계층이다. 둘 다 백엔드 보호에 유용하지만, 정상 요청을 차단하거나 요청을 변환해 앱이 예상하지 못한 형태로 받게 할 수 있다.
- Gateway는 auth, routing, rate limit, quota, transformation, schema validation, API key 검증을 수행할 수 있다.
- WAF는 SQLi/XSS/path traversal/bot/DDoS 패턴을 탐지하고 차단할 수 있다.
- 차단 응답은 앱 로그 없이 401/403/413/429/5xx로 보일 수 있다.
- managed rule update나 gateway policy 변경은 코드 배포 없이도 API 동작을 바꾼다.
원리
Gateway/WAF는 보통 앱보다 앞에서 결정을 내린다.
Client
-> WAF: allow/block/challenge
-> Gateway: auth/rate limit/route/transform
-> App이 계층이 응답을 만들면 앱은 요청을 모른다. 그래서 “권한이 없다고 나와요”가 앱 권한 로직 문제가 아니라 WAF rule, API key policy, rate limit일 수 있다.
장애 유형별 판단
| 증상 | 가능 원인 | 확인 증거 |
|---|---|---|
| 401 | gateway auth 실패 | gateway auth log, token issuer/audience |
| 403 | WAF/ACL/geoblock | WAF rule id, client IP, payload |
| 413 | gateway body limit | request size, gateway limit |
| 429 | rate limit/quota | limit key, window, Retry-After |
| 502/503 | upstream unavailable | route target, health, connection |
| 504 | gateway timeout | integration timeout, app duration |
Rate Limit 설계
rate limit key를 무엇으로 잡는지가 중요하다.
- IP 기준: 단순하지만 NAT, VPN, 사내망 사용자 전체가 함께 막힐 수 있다.
- user id 기준: 인증 이후에 가능하고 사용자별 공정성이 좋다.
- API key 기준: B2B/파트너 API에 적합하다.
- route 기준: 비싼 endpoint만 더 엄격하게 제어할 수 있다.
응답에는 가능하면 429와 Retry-After를 제공한다. client가 재시도 폭주를 줄일 수 있기 때문이다.
코드와 명령으로 확인하기
gateway/WAF 응답 header를 확인한다.
curl -i https://api.example.com/orders \
-H 'X-Request-ID: debug-001'payload 오탐을 의심할 때는 최소 재현 body를 만든다.
curl -i https://api.example.com/search \
-H 'Content-Type: application/json' \
-H 'X-Request-ID: waf-test-001' \
--data '{"query":"select * from product"}'WAF가 SQLi처럼 오탐할 수 있으므로 앱 로그 도달 여부와 WAF deny log의 rule id를 비교한다.
정책 문서화
Gateway/WAF 정책은 API 문서와 함께 있어야 한다.
- endpoint별 auth 요구사항
- body/header size limit
- timeout
- rate limit key와 window
- WAF 예외 신청 절차
- 차단 응답 형식
- request id 전달 방식
정책이 문서화되지 않으면 주니어는 403을 앱 권한 문제로, 인프라 팀은 정상 차단으로, 사용자 지원팀은 일시 오류로 각각 다르게 해석한다.
인프라 협업 포인트
- WAF 오탐은 payload 전체를 공유하기 어려울 수 있다. 민감정보를 마스킹한 최소 재현과 rule id를 공유한다.
- managed rule은 자동 업데이트될 수 있으므로 변경 시각을 장애 타임라인에 포함한다.
- gateway timeout과 app timeout을 맞춘다. gateway가 먼저 끊으면 app은 성공 처리했는데 client는 실패할 수 있다.
- 보안 팀은 차단 우선, 앱 팀은 정상 사용성 우선으로 볼 수 있다. endpoint 위험도와 사용자 영향 범위로 조율한다.
실전 팁
- WAF 예외는 path 전체 해제가 아니라 rule/path/method/payload 조건을 좁혀 적용한다.
- rate limit은 429만 내는 것이 아니라 client guide와 retry policy까지 포함해야 한다.
- API Gateway가 인증을 끝내고 user header를 앱에 넘기면, 앱은 그 header가 gateway에서만 올 수 있도록 network boundary를 확인해야 한다.
- GraphQL이나 검색 API는 WAF 오탐이 잦을 수 있어 관찰 모드로 먼저 튜닝하는 것이 안전하다.
- 개인 프로젝트에서도 Cloudflare/WAF를 켰다면 403 발생 시 앱 로그만 보지 말고 provider event log를 본다.
위험 신호!
- WAF rule id 없이 403 장애를 분석한다.
- rate limit key가 IP 하나라 사내 NAT 사용자가 모두 막힌다.
- gateway body limit이 앱 upload limit보다 작지만 문서화되어 있지 않다.
- gateway가 만든 user header를 외부 client도 직접 보낼 수 있다.
확인 질문
확인 질문
- WAF 403과 앱 권한 403을 구분하려면 무엇을 봐야 하는가?
- 앱 로그 도달 여부, WAF rule id, gateway/WAF request id, 응답 header를 함께 봐야 한다.
- IP 기반 rate limit의 대표적인 함정은 무엇인가?
- NAT나 VPN 뒤의 많은 정상 사용자가 같은 IP로 묶여 함께 차단될 수 있다는 점이다.
- Gateway 인증 후 user header를 앱이 신뢰하려면 무엇이 필요한가?
- 외부에서 앱으로 직접 들어올 수 없고, gateway가 header를 덮어쓰거나 서명하며, 앱이 trusted boundary를 알고 있어야 한다.