donghyeon.kang/llm-wiki
1
0
Fork 0
Code Issues Pull Requests Projects Releases Wiki Activity
Files
7bcb54c4647589f64c703fd0de34b9c9ea759661
llm-wiki/raw/official-docs/nginx-auth-request-module-official.md
T

12 KiB
Raw Blame History

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

핵심 인용 / 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 활성화
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 / 관련

Reference in New Issue View Git Blame Copy Permalink