llm-wiki/raw/official-docs/nginx-core-module-location-internal-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
official-doc / nginx Core Module — `internal` Directive & `location` Matching Priority (exact vs prefix)	official-doc	https://nginx.org/en/docs/http/ngx_http_core_module.html		feature-keycloak-nginx-auth-request-integration	keycloak-patterns	official-doc keycloak-patterns networking nginx auth-request	2026-07-17	2026-07-17

nginx Core Module — internal Directive & location Matching Priority (exact vs prefix)

Layer: raw/ — 외부 자료(공식 문서)의 원문 발췌·출처 기록. 이 문서는 nginx ngx_http_core_module 전체를 요약하지 않는다. internal directive 정의와 location 매칭 우선순위(exact > prefix) 2개 항목에만 초점을 맞춘 발췌다.

source_type 허용값

• official-doc — nginx (F5) 공식 module reference.

Parent / 활용 branch (필수, 최소 1개+)

Branch	이 자료가 정당화하는 결정
raw/branch-notes/feature-keycloak-nginx-auth-request-integration	D7 — internal directive 가 외부 요청을 404 로 차단하는 동작 + location 매칭에서 exact match(=)가 prefix match 를 이긴다는 규칙. 이 두 메커니즘이 결합돼야 "location /oauth2/ (public prefix) 와 location = /oauth2/auth (subrequest 전용 exact) 가 같은 /oauth2 prefix 아래 공존 가능하다"는 D7 핵심 메커니즘이 성립한다.

출처 / Source

• 원본 URL: https://nginx.org/en/docs/http/ngx_http_core_module.html
• 아카이브 URL: (미수집)
• 저자 / 조직: nginx, Inc. (F5)
• 발행일: (버전 관리 문서, 최초 발행일 명시 없음 — 문서는 지속 갱신됨)
• 마지막 확인일: 2026-07-17

왜 저장했는지 / Why archived

D7 (location /oauth2/ 와 location = /oauth2/auth 공존 설계)의 메커니즘 근거가 되는 nginx 공식 2가지 사실 — (1) internal directive 가 외부 요청에 정확히 무엇을 하는지, (2) location 매칭에서 exact match 가 prefix match 를 이긴다는 규칙 — 을 verbatim 으로 고정 보존하기 위함. 이 두 사실은 D7 의 "왜 안전하게 공존 가능한가"를 설명하는 재료이며, oauth2-proxy 가 실제로 그렇게 권고한다는 뜻은 아니다(아래 Usage Boundaries 참조).

핵심 인용 / Key quotes (verbatim, 5문장)

[§internal] "Specifies that a given location can only be used for internal requests. For external requests, the client error 404 (Not Found) is returned. Internal requests are the following:"

[§internal] "subrequests formed by the “include virtual” command of the ngx_http_ssi_module module, by the ngx_http_addition_module module directives, and by auth_request and mirror directives;"

[§internal] "requests redirected by the error_page, index, internal_redirect, random_index, and try_files directives;"

[§location] "nginx first checks locations defined using the prefix strings (prefix locations)." [...] "Among them, the location with the longest matching prefix is selected and remembered."

[§location] "using the “=” modifier it is possible to define an exact match of URI and location." [...] "If an exact match is found, the search terminates."

Claims Extracted / 추출된 주장

Claim ID	Claim (이 자료가 직접 말하는 것)	Evidence quote	Strength	Applies to	Does not prove
NGCM-C1	internal; directive 가 붙은 location 은 외부(client) 요청에 대해 404 를 반환하며, "internal request" 로 간주되는 요청 종류는 nginx 가 명시적으로 열거한 닫힌 목록(error_page/index/internal_redirect/random_index/try_files 리다이렉트, X-Accel-Redirect, SSI include virtual, ngx_http_addition_module, auth_request, mirror, rewrite)이다. auth_request 서브리퀘스트는 이 목록에 명시적으로 포함되어 있다.	[§internal] "Specifies that a given location can only be used for internal requests. For external requests, the client error 404 (Not Found) is returned." + "subrequests formed by the “include virtual” command of the ngx_http_ssi_module module, by the ngx_http_addition_module module directives, and by auth_request and mirror directives;"	official-vendor-doc	nginx internal directive 의 일반 정의 — 어떤 nginx 배포·버전에도 적용되는 core module 표준 동작	(1) oauth2-proxy 의 /oauth2/auth location 에 internal; 을 실제로 붙이는 것이 안전하거나 권장된다는 것 — 그건 이 branch 사용자의 별도 추론(INFERENCE)이며 oauth2-proxy 공식 예제는 internal; 을 붙이지 않는 것으로 별도 확인됨(negative finding). (2) internal 이 네트워크 계층 접근 통제라는 것 — 이건 client 의 직접 HTTP 요청 경로만 막을 뿐, 네트워크 격리는 형제 branch feature-keycloak-header-spoofing-defense 의 별도 관심사.
NGCM-C2	location 매칭 시 nginx 는 먼저 prefix string location 들 중 **최장 일치(longest matching prefix)**를 선택해 기억해 두고, 그 다음 정규식을 검사한다. 단 "=" modifier 로 정의된 exact match 가 발견되면 그 즉시 검색이 종료된다(정규식 검사도 건너뜀).	[§location] "nginx first checks locations defined using the prefix strings (prefix locations). Among them, the location with the longest matching prefix is selected and remembered." + "using the “=” modifier it is possible to define an exact match of URI and location. If an exact match is found, the search terminates."	official-vendor-doc	location block 매칭 우선순위의 일반 규칙 — = exact match 가 있으면 그 URI 요청에 대해서는 prefix match 후보들과 정규식 후보들을 모두 무시하고 즉시 그 config 가 채택됨을 보장	이 규칙만으로는 location /oauth2/ (prefix) 와 location = /oauth2/auth (exact) 를 같은 config 파일에 함께 두는 것이 oauth2-proxy 의 권장 패턴이라는 것을 증명하지 않는다. 단지 nginx 엔진이 그 둘을 충돌 없이 공존시킬 수 있다는 매칭 메커니즘만 증명한다.

Strength 허용값

• official-standard — RFC, 표준 사양, 언어/프로토콜 표준
• official-vendor-doc — Spring, Keycloak, AWS, Google, nginx(F5) 등 공식 벤더 문서
• official-reference — 공식 reference/API 문서
• company-case-study — 대기업/실무 기술 블로그의 특정 사례
• engineering-blog — 개인/팀 블로그의 엔지니어링 해설
• tutorial — 튜토리얼/가이드. 일반화 금지
• needs-confirmation — 원문만으로는 적용 판단 불가

Usage Boundaries / 적용 경계

• 이 자료가 직접 증명하는 것:
  • NGCM-C1: internal; 이 붙은 location 은 외부 요청에 404 를 반환하고, auth_request 서브리퀘스트는 nginx 가 공식적으로 열거한 "internal request" 트리거 목록에 포함된다.
  • NGCM-C2: nginx location 매칭에서 "=" exact match 가 발견되면 즉시 검색이 종료되며, 이는 일반 prefix location 매칭(최장 일치)보다 우선한다.
• 이 자료가 증명하지 않는 것:
  • oauth2-proxy 의 /oauth2/auth endpoint 에 internal; 을 붙이는 것이 공식 권장 사항이라는 것. 이는 nginx 의 일반 메커니즘일 뿐이며, oauth2-proxy 공식 nginx 통합 예제 자체는 internal; 을 붙이지 않는 것으로 별도 확인됨 (negative finding — raw/official-docs/oauth2-proxy-nginx-integration-official 참조). D7 이 "internal; 을 붙여도 안전하다"고 결론짓는다면 그것은 NGCM-C1 + NGCM-C2 + 위 negative finding 을 결합한 사용자 INFERENCE이며, 이 raw 문서 자체가 그 결론을 뒷받침하지 않는다.
  • internal directive 가 네트워크 계층(예: 방화벽·NetworkPolicy·security group)의 접근 통제 역할을 한다는 것. internal 은 오직 client 의 직접 외부 HTTP 요청을 막을 뿐이다.
• 내 프로젝트에 적용하려면 추가 확인이 필요한 것:
  • 실제 nginx 설정 파일에서 location /oauth2/ (public prefix, /oauth2/start·/oauth2/callback·/oauth2/sign_out 등)와 location = /oauth2/auth (exact, subrequest 전용)를 함께 배치했을 때 두 location 이 실제로 의도대로 매칭되는지 로컬 nginx 로 검증 필요 (Claims To Verify 대상).
  • oauth2-proxy 자체가 /oauth2/auth 에 internal; 을 붙이지 않는 이유(공식 예제 관찰)가 단순 누락인지 의도적 설계인지는 이 문서만으로 판단 불가 — oauth2-proxy 공식 자료 재확인 필요.

메모 / Notes

나중에 wiki로 옮길 때 참고할 짧은 메모. 검증되지 않은 내 추론은 여기에 두지 말 것.

• auth_request 가 "internal request" 트리거 목록에 명시적으로 포함된다는 사실은 D7 의 메커니즘 재료로 유효하지만, 그 자체가 "그러므로 /oauth2/auth 에 internal; 을 붙이는 게 맞다"는 결론까지 자동으로 정당화하지는 않는다 — branch-note 의 Decision Evidence Map 에서 이 raw 를 인용할 때는 반드시 이 경계를 함께 명시할 것.
• 추가로 봐야 할 동일 출처 페이지: error_page directive (내부 리다이렉트 트리거 중 하나), try_files directive (동일).

Related / 관련

• raw/official-docs/nginx-auth-request-module-official — ngx_http_auth_request_module (subrequest 응답 status 2xx/401/403 contract)
• raw/official-docs/oauth2-proxy-nginx-integration-official — oauth2-proxy 공식 nginx 통합 가이드 (negative finding: /oauth2/auth 예제에 internal; 미사용)
• raw/official-docs/oauth2-proxy-endpoints-official — oauth2-proxy 공식 endpoint 목록 (/oauth2/auth, /oauth2/start, /oauth2/callback, /oauth2/sign_out 등)