---
title: nginx — ngx_http_auth_request_module (Official Docs)
source_type: official-doc
url: https://nginx.org/en/docs/http/ngx_http_auth_request_module.html
archive_url:
status: raw
confidence: high
tags: [keycloak-patterns, p1a-edge-forward-auth, nginx, auth_request, subrequest, official-vendor-doc]
related_projects: [keycloak-patterns]
related_branches: [feature-keycloak-patterns, feature-keycloak-edge-forwardauth-no-google, feature-keycloak-nginx-auth-request-integration, feature-keycloak-header-spoofing-defense]
created: 2026-05-25
last_reviewed: 2026-07-17
---

# nginx — ngx_http_auth_request_module (Official Docs)

> Layer: `raw/official-docs/` — nginx 공식 문서. `auth_request` 디렉티브의 응답코드 규약 (2xx=allow, 401/403=deny, 그 외=error) 의 1차 vendor-neutral 출처. oauth2-proxy ForwardAuth 결합의 토대.

## Parent / 활용 branch (필수)

| Branch | 이 자료가 정당화하는 결정 |
|---|---|
| [[raw/branch-notes/feature-keycloak-patterns]] | keycloak-patterns root — edge 패턴에서 nginx `auth_request` 가 vendor-neutral subrequest 메커니즘이라는 사실 |
| [[raw/branch-notes/feature-keycloak-edge-forwardauth-no-google]] | P1A — `/oauth2/auth` 가 202 반환 시 nginx 가 access 허용하는 동작의 1차 근거 |
| [[raw/branch-notes/feature-keycloak-nginx-auth-request-integration]] | `auth_request_set` + `$upstream_http_*` 변수 노출 메커니즘이 nginx 일반 기능임을 확정 (oauth2-proxy 전용 아님) + D6 — "Example Configuration" 이 `/auth` subrequest 목적지 location 에서 `proxy_pass_request_body off;` / `Content-Length ""` 를 예제로 제시하는 근거 (`NGAR-C8`) |
| [[raw/branch-notes/feature-keycloak-header-spoofing-defense]] | WWW-Authenticate 헤더 forwarding 동작 + 401 응답 흐름을 통한 미인증 브라우저 처리 패턴 |

## 컨텍스트 / 왜 저장했는지

P1A 토큰 sequence 2단계(`auth_request` subrequest)의 코드 규약을 vendor-neutral 1차 문서에서 확정하기 위함. oauth2-proxy의 `/oauth2/auth` 가 202/401만 돌려주는 동작이 어떻게 nginx에서 해석되는지를 이 문서가 정의.

## 출처 / Source

- 원본 URL: https://nginx.org/en/docs/http/ngx_http_auth_request_module.html
- 아카이브 URL: (미수집)
- 저자 / 조직: F5 / nginx
- 발행일: 모듈 도입 1.5.4+, 지속 업데이트
- 마지막 확인일: 2026-05-27

## 핵심 인용 / Key quotes (verbatim)

> [§Module intro] "The `ngx_http_auth_request_module` module (1.5.4+) implements client authorization based on the result of a subrequest."

> [§Response codes] "If the subrequest returns a 2xx response code, the access is allowed. If it returns 401 or 403, the access is denied with the corresponding error code."

> [§Response codes] "Any other response code returned by the subrequest is considered an error."

> [§auth_request directive] Syntax: "**auth_request** `_uri_` | `off`;``" — Description: "Enables authorization based on the result of a subrequest and sets the URI to which the subrequest will be sent."

> [§auth_request_set directive] Syntax: "**auth_request_set** `_$variable_` `_value_`;``" — Description: "Sets the request `_variable_` to the given `_value_` after the authorization request completes. The value may contain variables from the authorization request, such as `$upstream_http_*`."

> [§401 header forwarding] "For the 401 error, the client also receives the \"WWW-Authenticate\" header from the subrequest response."

> [§Build] "This module is not built by default, it should be enabled with the `--with-http_auth_request_module` configuration parameter."

> [§Example Configuration] Example Configuration 코드 블록 (subrequest destination location):
> ```
> location = /auth {
>     proxy_pass ...
>     proxy_pass_request_body off;
>     proxy_set_header Content-Length "";
>     proxy_set_header X-Original-URI $request_uri;
> }
> ```
> (같은 Example Configuration 섹션 상단에 protected location: `location /private/ { auth_request /auth; ... }`)

## Claims Extracted / 추출된 주장

| Claim ID | Claim (이 자료가 직접 말하는 것) | Evidence quote | Strength | Applies to | Does not prove |
|---|---|---|---|---|---|
| NGAR-C1 | `ngx_http_auth_request_module` 는 nginx 1.5.4+ 에서 subrequest 결과 기반 client authorization 을 구현한다 | [§Module intro] "The `ngx_http_auth_request_module` module (1.5.4+) implements client authorization based on the result of a subrequest." | `official-vendor-doc` | nginx 1.5.4 이상 환경 | 1.5.4 미만 버전에서 동작한다는 뜻 아님 — 미만 버전에는 기능 자체가 없음 |
| NGAR-C2 | subrequest 가 2xx 반환 시 access 허용, 401/403 반환 시 동일 코드로 거부 | [§Response codes] "If the subrequest returns a 2xx response code, the access is allowed. If it returns 401 or 403, the access is denied with the corresponding error code." | `official-vendor-doc` | nginx `auth_request` 응답 처리 contract | 200 vs 202 vs 204 같은 2xx 변종의 동작이 다르다는 뜻 아님 — 모두 allow |
| NGAR-C3 | 2xx/401/403 이외의 응답 코드는 error 로 간주됨 (allow 도 deny 도 아닌 nginx 내부 오류 처리) | [§Response codes] "Any other response code returned by the subrequest is considered an error." | `official-vendor-doc` | subrequest 가 5xx 또는 비정상 응답 반환 시 | 정확한 nginx 응답 코드 (500 vs 502) 가 무엇인지는 본 인용에 명시 없음 |
| NGAR-C4 | `auth_request` 디렉티브는 subrequest 가 보내질 URI 를 설정하며, `off` 로 비활성 가능 | [§auth_request directive] "**auth_request** `_uri_` | `off`;``" + "Enables authorization based on the result of a subrequest and sets the URI to which the subrequest will be sent." | `official-vendor-doc` | nginx config 의 location 별 ForwardAuth 활성화 | 동일 location 에 여러 `auth_request` 디렉티브를 둘 수 있다는 뜻 아님 — directive 는 단일 URI |
| NGAR-C5 | `auth_request_set` 는 인증 subrequest 완료 후 변수에 값을 할당하며, value 는 `$upstream_http_*` 등 authorization request 의 변수를 포함할 수 있다 | [§auth_request_set directive] "**auth_request_set** `_$variable_` `_value_`;``" + "Sets the request `_variable_` to the given `_value_` after the authorization request completes. The value may contain variables from the authorization request, such as `$upstream_http_*`." | `official-vendor-doc` | subrequest 응답 헤더를 main request 변수로 전달 | `$upstream_http_*` 가 oauth2-proxy 전용 기능이라는 뜻 아님 — nginx 일반 기능 |
| NGAR-C6 | subrequest 가 401 반환 시 client 는 subrequest 응답의 `WWW-Authenticate` 헤더를 함께 받는다 | [§401 header forwarding] "For the 401 error, the client also receives the \"WWW-Authenticate\" header from the subrequest response." | `official-vendor-doc` | 표준 HTTP 401 challenge 흐름 | client 가 challenge 에 반드시 응답해야 한다는 뜻 아님 — 브라우저는 별도 redirect 처리 |
| NGAR-C7 | 본 모듈은 기본 빌드에 포함되지 않으며 `--with-http_auth_request_module` configure 옵션이 필요 | [§Build] "This module is not built by default, it should be enabled with the `--with-http_auth_request_module` configuration parameter." | `official-vendor-doc` | nginx 직접 빌드 시 | 모든 Linux distribution 패키지가 이 모듈을 포함한다는 뜻 아님 — 패키지별 확인 필요 |
| NGAR-C8 | nginx 공식 문서의 "Example Configuration" 섹션은 `/auth` subrequest 목적지 location 에서 `proxy_pass_request_body off;` 와 `proxy_set_header Content-Length "";` 를 예제로 명시한다 | [§Example Configuration] "location = /auth {" + "proxy_pass ..." + "proxy_pass_request_body off;" + "proxy_set_header Content-Length \"\";" + "proxy_set_header X-Original-URI $request_uri;" + "}" (연속된 코드 블록 — 전문은 위 핵심 인용 참조) | `official-vendor-doc` | auth_request subrequest 목적지 location 일반 (oauth2-proxy 전용 아님 — nginx 모듈 설계자 자신의 vendor-neutral 예제) | 이 설정을 **생략했을 때 정확히 어떤 에러/실패가 발생하는지는 증명하지 않음** — 원문은 권장 패턴을 예제로 제시할 뿐 실패 모드를 기술하지 않음. 또한 이 예제 하나만으로 모든 subrequest 시나리오(POST body 가 필요한 커스텀 auth 서버 등)에 이 설정이 그대로 적용 가능하다는 뜻도 아님 |

## Usage Boundaries / 적용 경계

- **이 자료가 직접 증명하는 것**:
  - `NGAR-C1` ~ `C7`: nginx auth_request 모듈의 vendor-neutral spec (코드 규약, 디렉티브 syntax, 변수 노출 메커니즘, build 옵션)
  - `NGAR-C8`: nginx 모듈 설계자 자신이 "Example Configuration" 에서 `/auth` subrequest 목적지 location 에 `proxy_pass_request_body off;` + `proxy_set_header Content-Length "";` 를 예제로 제시한다는 사실 (oauth2-proxy 벤더 문서와 독립된 2번째 공식 출처)
- **이 자료가 증명하지 않는 것**:
  - oauth2-proxy 의 `/oauth2/auth` 가 정확히 202 를 반환한다는 사실 (별도 oauth2-proxy 문서)
  - subrequest 실패 시 nginx 가 client 에 반환하는 정확한 코드 (5xx 의 정확한 변종)
  - `auth_request_set` 의 변수가 backend `proxy_set_header` 에서 정확히 어떻게 사용되는지의 다른 예제
  - `NGAR-C8`: `proxy_pass_request_body off;` / `Content-Length ""` 를 **생략했을 때** 정확히 어떤 에러(502/400 등)가 발생하는지 — 원문은 권장 예제만 제시, 실패 모드는 기술하지 않음
- **내 프로젝트에 적용하려면 추가 확인이 필요한 것**:
  - 사용하는 nginx 패키지가 `--with-http_auth_request_module` 로 빌드되었는지 (`nginx -V 2>&1 | grep auth_request`)
  - subrequest 의 timeout 설정이 P1A 의 oauth2-proxy 응답 시간과 호환되는지
  - 401 응답 시 redirect 처리를 위한 `error_page 401 = @oauth2_signin;` 패턴 별도 적용

## 메모 / Notes (내 프로젝트 해석)

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

- `2xx = allow / 401|403 = deny` 가 핵심 contract. oauth2-proxy의 `/oauth2/auth` 는 의도적으로 이 contract에 맞춰 **202(Accepted)만 발급** (200 아님 — 의미상 "권한 확인됨, 본 응답 아님").
- `$upstream_http_x_auth_request_*` 패턴은 모든 subrequest 응답 헤더를 변수로 노출하는 nginx의 일반 기능 — oauth2-proxy 전용 기능이 아님.
- 모듈은 nginx 빌드 시 `--with-http_auth_request_module` 옵션 필요. 일반 배포(Debian/RPM)는 기본 포함.
- (2026-07-17 추가) `NGAR-C8`: Example Configuration 의 `proxy_pass_request_body off;` + `Content-Length ""` 는 nginx 모듈 설계자 자신의 예제 — oauth2-proxy 벤더 문서(`oauth2-proxy-nginx-integration-official.md`)에는 이 두 directive 가 verbatim 으로 확인되지 않았다 (해당 문서는 subrequest 응답 처리에 집중, request-side body 처리 예제 없음). 이후 같은 세션에서 `raw/official-docs/proxy-pass-request-body-nginx-official.md`(`NGXPM-C1`/`C2`, `ngx_http_proxy_module` 자체 directive reference)가 추가되어, 이제 D6 은 nginx.org 의 **독립된 2개 페이지**(`ngx_http_auth_request_module` + `ngx_http_proxy_module`)에서 교차확인된 상태다 — 단, 여전히 "이 설정이 없으면 실패한다"는 인과관계(에러 코드/실패 모드) 자체는 두 자료 모두 기술하지 않는다.

## Related / 관련

- 같은 주제 다른 official-doc:
  - [[raw/official-docs/oauth2-proxy-nginx-integration-official]] (oauth2-proxy 측 통합 가이드)
  - [[raw/official-docs/traefik-forwardauth-middleware-official]] (대안 ingress 의 ForwardAuth 등가)
- 인용하는 branch:
  - [[raw/branch-notes/feature-keycloak-edge-forwardauth-no-google]] (P1A)
  - [[raw/branch-notes/feature-keycloak-nginx-auth-request-integration]]
- 인용하는 wiki: (미작성)