Summary#
Envoy ext_authz HTTP filter의 주요 failure mode는 단순히 “외부 인증 서버가 허용/거부한다”로 끝나지 않는다. 운영상 위험은 주로 네 가지 경계에서 발생한다:
1) 인증 요청·응답 헤더가 어느 방향으로 전파되는지,
2) ext_authz 응답이 원요청 헤더를 바꾸면서 route cache를 무효화할 수 있는지,
3) 인증 서버 timeout/error 시 failure_mode_allow가 어디까지 fail-open을 허용하는지,
4) request body buffering 한도 초과가 인증 호출 전 차단으로 이어지는지 여부다.
핵심 결론은 다음과 같다. failure_mode_allow는 인증 서버 통신 실패나 timeout에 대한 fail-open 장치이지, 명시적 DeniedHttpResponse를 무시하는 기능이 아니다. 또한 request body buffering에서 max_request_bytes 초과는 기본적으로 413 응답으로 처리되며, 이 경계는 failure_mode_allow보다 우선한다. 헤더 전파는 allowed_headers, allowed_upstream_headers, allowed_client_headers, allowed_client_headers_on_success 등 방향별 allowlist를 명확히 설계해야 한다. 마지막으로 clear_route_cache와 ext_authz의 request header mutation을 함께 사용할 때는 route 재선택으로 인한 정책 우회 가능성을 별도 threat model로 다뤄야 한다.
Key Points#
- Header propagation은 방향별로 분리해서 이해해야 한다.
- 클라이언트 요청 헤더를 외부 auth service로 보낼 때는
authorization_request.allowed_headers같은 설정이 관여한다. - auth service의 성공 응답 헤더를 upstream request에 반영하려면
allowed_upstream_headers또는 append 계열 설정을 사용한다. - auth service의 거부 응답 헤더를 downstream client에 전달하려면
allowed_client_headers가 관여한다. - 성공 케이스에서 downstream client로 헤더를 내려보내려면
allowed_client_headers_on_success를 별도로 고려해야 한다. -
따라서 “auth service가 응답 헤더를 줬다”는 사실만으로 upstream 또는 client에 자동 전파된다고 가정하면 안 된다.
-
Request header mutation과 route-cache invalidation은 위험 조합이다.
- ext_authz는 auth service의 OK 응답을 통해 원요청 헤더를 추가·수정할 수 있다.
clear_route_cache가 활성화되어 있으면, 이런 헤더 변경 후 Envoy가 route cache를 clear하여 route를 다시 계산할 수 있다.- 이때 route match에 사용되는 헤더, path, authority, metadata 정책과 ext_authz 정책의 적용 범위가 어긋나면 “인증은 A route 기준으로 받았는데 실제 upstream은 B route로 간다”는 유형의 정책 불일치가 생길 수 있다.
-
운영 권장안은 route 선택에 영향을 주는 헤더를 ext_authz가 변경하지 못하게 제한하거나, 변경이 필요한 경우
decoder_header_mutation_rules, header allowlist, route 정책을 함께 검토하는 것이다. -
failure_mode_allow는 통신 실패·timeout 경계의 fail-open이다. - 외부 auth service 호출 실패, 네트워크 오류, timeout 같은 authorization check 자체의 실패 상황에서
failure_mode_allow: true이면 요청을 계속 진행시킬 수 있다. - 이 경우
failure_mode_allow_header_add를 사용하면 fail-open으로 통과한 요청에x-envoy-auth-failure-mode-allowed: true헤더를 추가할 수 있다. - 그러나 auth service가 정상 응답으로 명시적 deny를 반환한 경우까지 허용하는 스위치로 이해하면 안 된다.
-
fail-open은 availability를 높이는 대신 authorization dependency 장애 시 보호 경계를 약화시키므로, public ingress나 권한 상승 가능 경로에는 신중히 적용해야 한다.
-
Timeout은 보수적으로 짧게 잡되, auth service SLO와 함께 설계해야 한다.
- ext_authz는 외부 서비스 왕복 호출을 request path에 삽입하므로 timeout이 너무 길면 전체 API latency와 proxy worker 자원 점유에 영향을 준다.
- timeout이 너무 짧으면 정상 요청도 auth timeout으로 fail-close 또는 fail-open 처리될 수 있다.
-
따라서 timeout, retry 여부, auth service capacity, Envoy circuit breaking, observability metric을 함께 봐야 한다.
-
Request body buffering의
max_request_bytes는 강한 차단 경계다. with_request_body.max_request_bytes는 ext_authz에 전달할 request body 최대 크기를 제한한다.- 기본적으로 body가 이 한도를 초과하면 Envoy는 authorization request를 보내지 않고 413
Payload Too Large를 반환할 수 있다. - Envoy 문서상 이
max_request_bytes초과 처리는failure_mode_allow보다 우선한다. -
즉,
failure_mode_allow: true라고 해서 body limit 초과 요청이 fail-open으로 upstream에 전달된다고 기대하면 안 된다. -
allow_partial_message는 body 초과 시 의미를 바꾼다. allow_partial_message: true를 설정하면 body가max_request_bytes를 초과해도 Envoy가 제한된 크기까지의 partial body를 auth service에 보내 authorization을 진행할 수 있다.- 이 경우 auth service는 “전체 body를 봤다”가 아니라 “prefix만 봤다”는 사실을 전제로 판단해야 한다.
-
body 기반 보안 정책, 예컨대 JSON 필드 검사, 업로드 콘텐츠 검사, GraphQL query 검사에는 partial body가 불완전한 근거가 될 수 있다.
-
pack_as_bytes는 body 인코딩 해석 문제를 줄이는 데 사용된다. - request body를 문자열로 해석하는 대신 raw bytes로 전달해야 하는 경우
pack_as_bytes를 고려할 수 있다. -
특히 binary payload, 비 UTF-8 body, signature 검증처럼 byte-level 정확성이 중요한 auth service에는 문자열 body 가정이 위험하다.
-
Per-route override는 정책 일관성의 주요 위험 지점이다.
ExtAuthzPerRoute를 통해 특정 virtual host, route, weighted cluster 수준에서 ext_authz를 disable하거나 check settings를 조정할 수 있다.disabled: true가 섞이면 일부 route가 전역 ext_authz 필터를 우회할 수 있으므로, route table diff 검토와 테스트가 필요하다.context_extensions는 auth service에 추가 context를 전달할 수 있어 유용하지만, route별 값이 실제 정책 결정에 쓰인다면 misconfiguration이 곧 권한 정책 오류가 된다.-
metadata_context_namespaces및 typed metadata 관련 설정은 Envoy metadata를 auth service 판단에 포함시키는 통로이므로, namespace 이름과 생산 주체를 신뢰할 수 있는지 검토해야 한다. -
권장 운영 체크리스트
- ext_authz가 upstream으로 전달할 수 있는 헤더를 최소 allowlist로 제한한다.
- route selection에 영향을 주는 헤더를 ext_authz가 변경하지 못하게 한다.
clear_route_cache사용 시 변경 전후 route가 달라지는 테스트 케이스를 만든다.failure_mode_allow가 켜진 route를 inventory화하고, 외부 노출·민감 작업·관리 API에는 별도 승인 절차를 둔다.- request body 기반 authorization은
max_request_bytes,allow_partial_message, content-type, compression, streaming behavior를 함께 테스트한다. - per-route
disabled및 override 설정은 배포 전 config dump나 static analysis로 검출한다. - fail-open 통과 요청을 식별할 수 있도록
failure_mode_allow_header_add, access log field, metric alert를 연계한다.
Cautions#
- 공개 문서 기준으로 확인 가능한 내용은 Envoy 공식 문서와 API reference에 기반한다. 특정 버전별 동작 차이는 Envoy 릴리스 버전에 따라 달라질 수 있으므로 실제 운영 버전의 generated API docs를 함께 확인해야 한다.
clear_route_cache의 실제 위험도는 라우팅 조건, ext_authz가 변경 가능한 헤더, RBAC/Lua/Wasm 등 다른 HTTP filter 순서에 따라 달라진다. 일반화해서 “항상 취약”하다고 단정할 수는 없다.- request body buffering은 HTTP/1.1, HTTP/2, streaming upload, gRPC, large payload API에서 체감 동작이 다를 수 있다. 특히 partial body를 auth service가 어떻게 해석하는지 별도 계약이 필요하다.
- 이 초안은 공개 URL 기반의 capsule 초안이며, 실제 프로덕션 정책으로 사용하려면 해당 Envoy 버전의 config dump, route config, ext_authz service implementation, access log를 함께 검증해야 한다.
- GitHub issue나 community discussion은 특정 시점의 버그·설계 논의를 반영할 수 있으나, 최종 근거로는 Envoy 공식 문서와 릴리스 노트를 우선해야 한다.
Sources#
- https://www.envoyproxy.io/docs/envoy/latest/configuration/http/http_filters/ext_authz_filter
- https://www.envoyproxy.io/docs/envoy/latest/api-v3/extensions/filters/http/ext_authz/v3/ext_authz.proto
- https://www.envoyproxy.io/docs/envoy/latest/api-v3/service/auth/v3/external_auth.proto
Related#
- Envoy Traffic-Management Failure Modes: Retry Budgets, Timeout Hierarchy, Circuit Breakers, and Outlier Detection Interactions
- 2 Upstreams, Trailers, Timeouts, and CORS
- Envoy xDS Rollout Failure Modes: Cluster Warming, Stale EDS State, Route Shadowing, and Hot Restart Drain Boundaries
Sagwan Revalidation 2026-07-18T03:17:07Z#
- verdict:
ok - note: 핵심 동작과 설정명은 현 Envoy ext_authz 문서와 부합한다
Sagwan Revalidation 2026-07-20T04:02:51Z#
- verdict:
ok - note: 최근 Envoy ext_authz 동작과 설정명 기준으로 핵심 주장 변동 없음