llm-wiki/vault/20-evidence/official-docs/proxy-pass-request-body-nginx-official.md

title, source_type, url, archive_url, related_branches, related_projects, tags, created, last_reviewed

title	source_type	url	archive_url	related_branches	related_projects	tags	created	last_reviewed
nginx — proxy_pass_request_body Directive (ngx_http_proxy_module, Official Docs)	official-doc	http://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_pass_request_body		feature-keycloak-nginx-auth-request-integration	keycloak-patterns	official-doc keycloak-patterns nginx p1a-edge-forward-auth auth_request	2026-07-17	2026-07-17

nginx — proxy_pass_request_body Directive (ngx_http_proxy_module, Official Docs)

Layer: raw/official-docs/ — nginx 공식 문서 ngx_http_proxy_module 중 proxy_pass_request_body directive 단일 항목 발췌. 모듈 전체 요약이 아니라 D6(proxy_pass_request_body off + Content-Length "")의 메커니즘 근거 1건만 다룬다.

Parent / 활용 branch

Branch	이 자료가 정당화하는 결정
raw/branch-notes/feature-keycloak-nginx-auth-request-integration	D6 — proxy_pass_request_body directive 의 메커니즘 근거(L1). Default 가 on 이므로 명시적으로 off 하지 않으면 원본 request body 가 proxied server 로 전달된다는 사실.

출처 / Source

• 원본 URL: http://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_pass_request_body
• 아카이브 URL: (미수집)
• 저자 / 조직: F5 / nginx
• 발행일: 모듈 최초 도입 이후 지속 업데이트 (버전 미표시 페이지)
• 마지막 확인일: 2026-07-17

왜 저장했는지 / Why archived

feature-keycloak-nginx-auth-request-integration TODO 중 /oauth2/auth internal location 에 proxy_pass_request_body off; 를 두는 결정(D6)이 이전에는 UNSUPPORTED_DECISION 이었다. 본 자료는 directive 의 공식 Syntax/Default/Context/설명을 확정해 D6 을 L0(존재)에서 L1(메커니즘)로 끌어올리는 근거로 저장.

핵심 인용 / Key quotes (verbatim)

[Directive: proxy_pass_request_body — Syntax] "proxy_pass_request_body on | off;"

[Directive: proxy_pass_request_body — Default] "proxy_pass_request_body on;"

[Directive: proxy_pass_request_body — Context] "http, server, location"

[Directive: proxy_pass_request_body — Description] "Indicates whether the original request body is passed to the proxied server."

[Directive: proxy_pass_request_body — Example] "location /x-accel-redirect-here/ { proxy_method GET; proxy_pass_request_body off; proxy_set_header Content-Length ""; proxy_pass ... }"

Claims Extracted / 추출된 주장

Claim ID	Claim (이 자료가 직접 말하는 것)	Evidence quote	Strength	Applies to	Does not prove
NGXPM-C1	proxy_pass_request_body 의 기본값은 on 이며, 이는 "원본 request body 가 proxied server 로 전달되는지 여부"를 나타낸다. 즉 http/server/location context 에서 명시적으로 off 하지 않으면 원본 body 가 그대로 전달된다.	"proxy_pass_request_body on | off;" + "proxy_pass_request_body on;" + "http, server, location" + "Indicates whether the original request body is passed to the proxied server."	official-vendor-doc	proxy_pass directive 로 upstream 에 요청을 전달하는 location(또는 http/server) block 의 request body 전달 여부 결정	subrequest 의 목적지가 반드시 proxy_pass 기반 location 이라는 것을 증명하지 않는다 — subrequest 가 fastcgi_pass 등 다른 handler 로 라우팅되면 이 directive 자체가 적용되지 않을 수 있다. 원문은 이 경우를 다루지 않는다. auth_request 서브리퀘스트가 반드시 이 directive 의 영향을 받는 location 으로 라우팅된다는 것도 증명하지 않는다.
NGXPM-C2	공식 예제는 proxy_pass_request_body off; 를 proxy_set_header Content-Length ""; 와 짝지어 사용한다 (proxy_method GET; 도 함께 지정된 X-Accel-Redirect 스타일 location 블록 예제).	"location /x-accel-redirect-here/ { proxy_method GET; proxy_pass_request_body off; proxy_set_header Content-Length ""; proxy_pass ... }"	official-vendor-doc	body 를 전달하지 않을 때(off) 남아있는 원본 Content-Length 헤더를 비워 upstream 에 잘못된 값이 전달되지 않도록 하는 조합 패턴의 존재	이 조합이 auth_request 서브리퀘스트에 대해 "공식적으로 필수"임을 증명하지 않는다 — 이 예제는 X-Accel-Redirect 용 location 컨텍스트(별도 proxy_method GET; 지정)를 위한 것이며, auth_request 전용 권고가 아니다. auth_request 서브리퀘스트 맥락에서의 필수 여부는 별도 자료(nginx-auth-request-module-official.md, oauth2-proxy-nginx-integration-official.md)가 담당한다. 또한 이 예제가 모든 proxy_pass_request_body off; 사용에 Content-Length "" 짝짓기가 항상 필요하다는 일반 규칙을 선언한 것도 아니다 — 하나의 예시일 뿐이다.

Strength 허용값 참고

• 두 claim 모두 official-vendor-doc — nginx(F5) 공식 reference 문서의 directive 항목 및 공식 예제이며, 표준 사양(RFC)이 아니므로 official-standard 아님.

Usage Boundaries / 적용 경계

• 이 자료가 직접 증명하는 것:
  • NGXPM-C1: proxy_pass_request_body 의 기본값이 on 이고, 이 directive 가 원본 request body 전달 여부를 제어한다는 사실 (syntax / default / context / description 4종 세트).
  • NGXPM-C2: 공식 문서가 off + Content-Length "" 조합을 예제로 제시한다는 사실 (X-Accel-Redirect 스타일 location 한정).
• 이 자료가 증명하지 않는 것:
  • auth_request subrequest 가 반드시 proxy_pass 기반 location 으로 라우팅된다는 것 (subrequest 목적지가 다른 handler 일 경우 이 directive 자체가 무관할 수 있음).
  • off + Content-Length "" 조합이 auth_request 서브리퀘스트에 대해 공식적으로 "필수"라는 것 — 그 전용 권고는 이 raw 의 역할이 아니며 nginx-auth-request-module-official.md / oauth2-proxy-nginx-integration-official.md 가 담당.
  • off 하지 않을 때(default on) auth_request subrequest 로 실제 POST body 가 전달되어 어떤 부작용(oauth2-proxy CPU 증가, 의도치 않은 endpoint 트리거 등)이 발생하는지 — 이는 본 문서 범위 밖의 추론이며 D6 Open Risk 로 별도 관리.
• 내 프로젝트에 적용하려면 추가 확인이 필요한 것:
  • /oauth2/auth internal location 이 실제로 proxy_pass 로 oauth2-proxy upstream 에 연결되는지 (본 branch TODO 기준으로는 그렇다고 가정되어 있음).
  • off 설정 후 실제 nginx 로그에서 body 가 upstream 으로 전달되지 않는지 로컬 검증 (Claims To Verify 대상).

메모 / Notes

본 섹션은 자료 직접 인용 아님. D6 결정 컨텍스트 해석.

• 이 raw 는 D6 을 UNSUPPORTED_DECISION → official-vendor-doc 근거 있는 결정으로 승급시키는 메커니즘 근거일 뿐, "auth_request 에 필수"라는 전용 권고 근거는 별도 자료 몫이다. branch-note 의 Decision Evidence Map D6 행 갱신 시 Supporting Claims 를 NGXPM-C1, NGXPM-C2 로 채우되 Open Risk 에 "auth_request 필수 여부는 별도 raw 필요" 를 남겨야 한다.
• 추가로 봐야 할 동일 출처 페이지: ngx_http_proxy_module.html#proxy_pass_request_headers (같은 페이지, sibling directive — 헤더 전달 여부를 별도로 제어하며 동일 예제 패턴에서 함께 등장).

Related / 관련

• 같은 주제 다른 official-doc:
  • raw/official-docs/nginx-auth-request-module-official — auth_request directive 자체의 응답코드 규약 (subrequest 가 어디로 라우팅되는지는 이 문서가 다루지 않음)
  • raw/official-docs/oauth2-proxy-nginx-integration-official — oauth2-proxy 측 /oauth2/auth nginx 통합 가이드 (auth_request 서브리퀘스트 전용 권고 담당)
• 인용하는 wiki: (미작성)