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

---
title: nginx — proxy_pass_request_body Directive (ngx_http_proxy_module, Official Docs)
source_type: official-doc
url: http://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_pass_request_body
archive_url:
related_branches: [feature-keycloak-nginx-auth-request-integration]
related_projects: [keycloak-patterns]
tags: [official-doc, keycloak-patterns, nginx, p1a-edge-forward-auth, auth_request]
created: 2026-07-17
last_reviewed: 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: (미작성)