Files

T

DongHyeonka d71669eb59 fix: 하네스 제거 및 keycloak 문서 보강

2026-07-25 12:53:13 +09:00

9.5 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

Traefik — ForwardAuth Middleware (Official Docs)

Layer: raw/official-docs/ — Traefik 공식 문서의 forwardAuth 미들웨어. nginx auth_request 의 Traefik 대응품. P1A 패턴에서 ingress = Traefik 인 경우 + 헤더 forwarding spec 의 1차 근거.

Parent / 활용 branch (필수)

Branch	이 자료가 정당화하는 결정
raw/branch-notes/feature-keycloak-patterns	keycloak-patterns root — edge 옵션 중 Traefik 채택 시 ForwardAuth 가 nginx `auth_request` 의 1:1 대응품이라는 사실
raw/branch-notes/feature-keycloak-edge-forwardauth-no-google	P1A — Traefik ingress 선택 시 oauth2-proxy 와의 결합 메커니즘 (2XX allow, non-2XX 응답 그대로 client 에 전달) 의 근거
raw/branch-notes/feature-keycloak-traefik-forwardauth-alternative	nginx 대신 Traefik 사용 시 `authResponseHeaders` 한 줄로 user 헤더 주입이 가능하다는 비교 결정 근거
raw/branch-notes/feature-keycloak-header-spoofing-defense	auto-forwarded `X-Forwarded-*` 헤더의 정확한 spec + `trustForwardHeader` deprecated 경고 → 외부 traffic 차단 + edge 만 신뢰 정책

컨텍스트 / 왜 저장했는지

P1A의 두 가지 구현 옵션 중 Traefik 측을 정리. nginx 계열과의 차이(요청 헤더 forwarding spec, authResponseHeaders / authRequestHeaders 옵션)를 명확히 하기 위함.

출처 / Source

원본 URL: https://doc.traefik.io/traefik/reference/routing-configuration/http/middlewares/forwardauth/
아카이브 URL: (미수집)
저자 / 조직: Traefik Labs
발행일: rolling docs (구 URL /traefik/middlewares/http/forwardauth/ → 신 URL redirect)
마지막 확인일: 2026-05-27

핵심 인용 / Key quotes (verbatim)

[§Overview] "The forwardAuth middleware delegates authentication to an external service. If the service answers with a 2XX code, access is granted, and the original request is performed. Otherwise, the response from the authentication server is returned."

[§Forward-Request Headers] auto-forwarded headers: "HTTP Method" → X-Forwarded-Method, "Protocol" → X-Forwarded-Proto, "Host" → X-Forwarded-Host, "Request URI" → X-Forwarded-Uri, "Source IP-Address" → X-Forwarded-For

[§authResponseHeaders] "authResponseHeaders - List of headers to copy from the authentication server response and set on forwarded request, replacing any existing conflicting headers."

[§authRequestHeaders] "authRequestHeaders - List of the headers to copy from the request to the authentication server. It allows filtering headers that should not be passed to the authentication server. If not set or empty, then all request headers are passed."

[§TLS] available fields: "tls.ca" (CA path), "tls.cert" (public cert path), "tls.key" (private key path), "tls.insecureSkipVerify" (accepts any certificate regardless of hostname coverage)

[§trustForwardHeader] "Set the trustForwardHeader option to true to trust all X-Forwarded-* headers." (marked deprecated)

Claims Extracted / 추출된 주장

Claim ID	Claim (이 자료가 직접 말하는 것)	Evidence quote	Strength	Applies to	Does not prove
TFA-C1	`forwardAuth` 미들웨어는 외부 인증 서비스에 위임하며, 2XX 응답 시 access 허용 + 원본 요청 진행, 비 2XX 응답은 그대로 client 에 반환	[§Overview] "The `forwardAuth` middleware delegates authentication to an external service. If the service answers with a 2XX code, access is granted, and the original request is performed. Otherwise, the response from the authentication server is returned."	`official-vendor-doc`	Traefik ingress + 외부 ForwardAuth (oauth2-proxy 등) 결합	nginx 의 "401/403 만 deny, 그 외는 error" 와 정확히 동일한 contract 라는 뜻 아님 — Traefik 은 모든 non-2XX 를 client 에 그대로 전달 (302 redirect 포함)
TFA-C2	Traefik 은 인증 서버로 5개 헤더를 자동 forward: `X-Forwarded-Method`, `X-Forwarded-Proto`, `X-Forwarded-Host`, `X-Forwarded-Uri`, `X-Forwarded-For`	[§Forward-Request Headers] "HTTP Method" → `X-Forwarded-Method`, "Protocol" → `X-Forwarded-Proto`, "Host" → `X-Forwarded-Host`, "Request URI" → `X-Forwarded-Uri`, "Source IP-Address" → `X-Forwarded-For`	`official-vendor-doc`	Traefik forwardAuth 미들웨어의 default 동작	인증 서버가 이 헤더를 모두 사용해야 한다는 뜻 아님 — 단지 자동 송신 spec
TFA-C3	`authResponseHeaders` 는 인증 서버 응답에서 복사해 forwarded request 에 설정할 헤더 목록 (기존 충돌 헤더는 대체됨)	[§authResponseHeaders] "List of headers to copy from the authentication server response and set on forwarded request, replacing any existing conflicting headers."	`official-vendor-doc`	edge → backend 사용자 식별 헤더 주입	client 가 동일 헤더로 spoof 한 요청을 강제로 deny 한다는 뜻 아님 — replacing 은 이미 forward 단계의 동작
TFA-C4	`authRequestHeaders` 는 인증 서버로 전달할 request 헤더 목록을 필터링하며, 비어 있으면 모든 request 헤더가 전달된다	[§authRequestHeaders] "List of the headers to copy from the request to the authentication server. It allows filtering headers that should not be passed to the authentication server. If not set or empty, then all request headers are passed."	`official-vendor-doc`	인증 서버 측 트래픽 양 / sensitive header 노출 제어	default (empty) 가 production 에서 안전하다는 뜻 아님 — Authorization 등 sensitive header 전달됨
TFA-C5	TLS 옵션으로 `tls.ca`, `tls.cert`, `tls.key`, `tls.insecureSkipVerify` 제공 (마지막은 hostname 검증 건너뜀)	[§TLS] "`tls.ca`" / "`tls.cert`" / "`tls.key`" / "`tls.insecureSkipVerify`" (accepts any certificate regardless of hostname coverage)	`official-vendor-doc`	인증 서버가 self-signed cert 사용하는 dev 환경	`tls.insecureSkipVerify=true` 가 production 에서 안전하다는 뜻 아님 — vendor 가 명시적으로 risk
TFA-C6	`trustForwardHeader=true` 는 모든 `X-Forwarded-` 헤더를 신뢰하도록 설정하며, deprecated* 표시됨	[§trustForwardHeader] "Set the `trustForwardHeader` option to `true` to trust all `X-Forwarded-*` headers." (marked deprecated)	`official-vendor-doc`	기존 deployment 의 마이그레이션 경고	동일 기능을 대체하는 정확한 신규 옵션명은 본 인용에 명시 없음 — 별도 deprecated 경고 페이지 확인 필요

Usage Boundaries / 적용 경계

이 자료가 직접 증명하는 것:
- TFA-C1 ~ C6: Traefik forwardAuth 미들웨어의 vendor-neutral spec (2XX contract, 자동 forwarded 헤더 5종, response/request header filtering, TLS 옵션, deprecated trustForwardHeader)
이 자료가 증명하지 않는 것:
- oauth2-proxy 가 Traefik forwardAuth 와 nginx auth_request 모두에서 동일한 endpoint (/oauth2/auth) 를 노출한다는 사실 (별도 oauth2-proxy 문서)
- 비 2XX 응답이 그대로 client 에 전달되는 동작이 oauth2-proxy 의 302 sign_in redirect 와 완벽 호환된다는 보장 (실제 동작 검증 필요)
- authResponseHeaders 의 replace 동작이 case-insensitive 인지 (HTTP spec 은 그렇지만 vendor 별 상이 가능)
내 프로젝트에 적용하려면 추가 확인이 필요한 것:
- P1A 에서 ingress 가 nginx 인지 Traefik 인지 (선택 결정 → 후속 config 분기)
- oauth2-proxy --reverse-proxy=true 옵션 활성화 여부 (X-Forwarded-For chain 인식)
- authRequestHeaders 에 Cookie 포함 여부 (oauth2-proxy 가 session cookie 를 읽어야 인증 가능)
- Traefik 의 trustForwardHeader deprecated 대체 옵션 (별도 vendor doc 확인)

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

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

nginx와의 큰 차이: nginx는 auth_request_set 으로 변수 캡처 후 다시 proxy_set_header로 명시 주입해야 함. Traefik은 authResponseHeaders 한 줄로 동일 동작.
인증 서버가 응답 본문 자체를 클라이언트에 전달(non-2XX 시) → oauth2-proxy를 Traefik 뒤에 둘 때 302 redirect 응답이 그대로 브라우저에 전달되어 자연스럽게 Keycloak 로그인 페이지로 이동.
X-Forwarded-For 가 자동 전달되므로 oauth2-proxy 측에서 reverse proxy chain을 인식할 수 있음 — 단, --reverse-proxy=true 옵션 명시 필요(보안상 기본 off).

같은 주제 다른 official-doc:
- raw/official-docs/nginx-auth-request-module-official (nginx 측 1:1 대응품)
- raw/official-docs/oauth2-proxy-nginx-integration-official (nginx 통합)
- raw/official-docs/oauth2-proxy-overview-config-official
인용하는 branch:
- raw/branch-notes/feature-keycloak-edge-forwardauth-no-google (P1A)
- raw/branch-notes/feature-keycloak-traefik-forwardauth-alternative
인용하는 wiki: (미작성)

9.5 KiB Raw Blame History