93 lines
9.8 KiB
Markdown
93 lines
9.8 KiB
Markdown
---
|
|
title: official-doc / nginx Core Module — `internal` Directive & `location` Matching Priority (exact vs prefix)
|
|
source_type: official-doc
|
|
url: https://nginx.org/en/docs/http/ngx_http_core_module.html
|
|
archive_url:
|
|
related_branches: [feature-keycloak-nginx-auth-request-integration]
|
|
related_projects: [keycloak-patterns]
|
|
tags: [official-doc, keycloak-patterns, networking, nginx, auth-request]
|
|
created: 2026-07-17
|
|
last_reviewed: 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` 등)
|