Files

T

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

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

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

OAuth2 Proxy — Configuration Overview (Official Docs)

Layer: raw/official-docs/ — oauth2-proxy 공식 configuration overview. P1A (Edge Forward Auth) 패턴에서 forward-auth proxy가 인증 결과를 backend에 어떤 헤더로 전달하는지 근거. 2026-05-27 WebFetch 재검증 결과: 5개 인용 중 C2 / C3 / C4 / C5 (4개) 는 공식 docs 원문에서 verbatim 일치 확인 → official-vendor-doc 격상. C1 (reverse proxy 동작 일반 설명) 은 공식 페이지에서 동일 wording 미발견 (NOT FOUND) → needs-confirmation 유지. C3 의 헤더 목록에 X-Auth-Request-Preferred-Username 가 spec 상 추가 존재함을 2026-05-27 확인.

Parent / 활용 branch (필수)

Branch	이 자료가 정당화하는 결정
raw/branch-notes/feature-keycloak-edge-forwardauth-no-google	P1A Edge Forward Auth 패턴에서 oauth2-proxy가 backend에 인증 결과를 헤더로 전달하는 운영 모델 채택 근거
raw/branch-notes/feature-keycloak-patterns	keycloak-patterns root — Edge Forward Auth 변형(P1A)의 forward-auth tool 후보로 oauth2-proxy 검토 근거
raw/branch-notes/feature-keycloak-oauth2-proxy-oidc-flow	oauth2-proxy provider=keycloak-oidc 설정의 OIDC issuer URL / JWKS URI 입력 근거
raw/branch-notes/feature-keycloak-nginx-auth-request-integration	nginx `auth_request` mode에서 oauth2-proxy `/oauth2/auth` endpoint + `X-Auth-Request-*` 헤더 캡처 패턴 근거

컨텍스트

P1A 패턴에서 "backend는 JWT 검증을 하지 않고 헤더만 신뢰한다"는 진술의 공식 근거. 어떤 헤더가 발급되며, OIDC issuer URL이 어떻게 설정되는지 확인. oauth2-proxy는 (1) 자체 reverse proxy 모드와 (2) nginx auth_request / Traefik forwardAuth 와 결합되는 auth-only endpoint 모드 두 가지를 지원.

출처 / Source

원본 URL: https://oauth2-proxy.github.io/oauth2-proxy/configuration/overview
아카이브 URL: (미수집)
저자 / 조직: oauth2-proxy maintainers (GitHub oauth2-proxy/oauth2-proxy)
발행일: rolling docs (지속 업데이트)
마지막 확인일: 2026-05-27 (WebFetch 재검증 완료 — 4/5 quote 가 공식 docs 원문에서 verbatim 확인, 1/5 (C1 reverse proxy 동작) 는 동일 wording NOT FOUND)

핵심 인용 / Key quotes (verbatim)

2026-05-27 WebFetch 재검증 결과: 5개 quote 중 4개 (C2 / C3 / C4 / C5) 는 공식 docs 원문에서 verbatim 확인 ([2026-05-27 verified]). C1 (reverse proxy 동작 일반 정의) 은 공식 페이지에서 동일 wording 발견 못 함 ([2026-05-25 capture] + NOT FOUND verbatim 으로 유지). C3 는 spec 원문에 X-Auth-Request-Preferred-Username 헤더가 추가로 존재함을 확인.

[§Overview — 2026-05-25 capture, 2026-05-27 NOT FOUND verbatim] "OAuth2 Proxy functions as a reverse proxy that intercepts requests and handles authentication before forwarding them upstream." (이 정확한 문장은 2026-05-27 https://oauth2-proxy.github.io/oauth2-proxy/configuration/overview fetch 결과에서 발견되지 않음. 공식 페이지는 --reverse-proxy flag 만 직접 언급: "are we running behind a reverse proxy, controls whether headers like X-Real-IP are accepted." 이전 캡처는 paraphrased summary 였을 가능성. 따라서 needs-confirmation 유지.)

[§--pass-access-token option — 2026-05-27 verified] "pass OAuth access_token to upstream via X-Forwarded-Access-Token header. When used with --set-xauthrequest this adds the X-Auth-Request-Access-Token header to the response"

[§nginx auth_request mode headers — 2026-05-27 verified] "set X-Auth-Request-User, X-Auth-Request-Groups, X-Auth-Request-Email and X-Auth-Request-Preferred-Username response headers (useful in Nginx auth_request mode)" (2026-05-25 캡처는 X-Auth-Request-Preferred-Username 누락 — 정정 verbatim 사용.)

[§--pass-user-headers option — 2026-05-27 verified] "pass X-Forwarded-User, X-Forwarded-Groups, X-Forwarded-Email and X-Forwarded-Preferred-Username information to upstream"

[§OIDC provider configuration — 2026-05-27 verified] --oidc-issuer-url: "the OpenID Connect issuer URL, e.g. https://accounts.google.com" + --oidc-jwks-url: "OIDC JWKS URI for token verification; required if OIDC discovery is disabled and public key files are not provided"

Claims Extracted / 추출된 주장

Claim ID	Claim (이 자료가 직접 말하는 것)	Evidence quote	Strength	Applies to	Does not prove
OAUTH2PROXY-C1	oauth2-proxy는 reverse proxy로 동작하며 upstream forwarding 전에 인증을 처리	[§Overview, 2026-05-25 capture, 2026-05-27 NOT FOUND] "OAuth2 Proxy functions as a reverse proxy that intercepts requests and handles authentication before forwarding them upstream." (공식 페이지에서 동일 wording 미발견 — paraphrase 였을 가능성)	`needs-confirmation`	oauth2-proxy 의 기본 reverse-proxy 동작 모드	2026-05-27 fetch 에서 동일 문장 미발견. 공식 페이지는 `--reverse-proxy` flag 만 언급. 재캡처 또는 다른 공식 페이지 (예: README) 인용으로 교체 권고.
OAUTH2PROXY-C2	`--pass-access-token` 옵션은 OAuth access token 을 `X-Forwarded-Access-Token` 헤더로 upstream에 전달 (`--set-xauthrequest` 결합 시 response 에 X-Auth-Request-Access-Token 추가)	[§--pass-access-token option, 2026-05-27 verified] "pass OAuth access_token to upstream via X-Forwarded-Access-Token header. When used with `--set-xauthrequest` this adds the X-Auth-Request-Access-Token header to the response"	`official-vendor-doc`	oauth2-proxy 배포 시 access token 을 backend로 전달하는 운영 결정	`--set-xauthrequest` flag 의 별도 동작 (`/oauth2/auth` endpoint response header 주입) 은 추가 인용 필요
OAUTH2PROXY-C3	`X-Auth-Request-User`, `X-Auth-Request-Groups`, `X-Auth-Request-Email`, `X-Auth-Request-Preferred-Username` response 헤더는 nginx `auth_request` mode 에서 유용	[§nginx auth_request mode headers, 2026-05-27 verified] "set X-Auth-Request-User, X-Auth-Request-Groups, X-Auth-Request-Email and X-Auth-Request-Preferred-Username response headers (useful in Nginx auth_request mode)" (2026-05-25 캡처는 Preferred-Username 누락 — 4개 헤더로 정정)	`official-vendor-doc`	nginx `auth_request` + oauth2-proxy 결합 배포	nginx 에서 이 response 헤더를 어떤 directive (`auth_request_set`) 로 backend 까지 전파하는지는 nginx 측 설정
OAUTH2PROXY-C4	`--pass-user-headers` 옵션은 `X-Forwarded-User`, `X-Forwarded-Groups`, `X-Forwarded-Email`, `X-Forwarded-Preferred-Username` 을 upstream으로 전달	[§--pass-user-headers option, 2026-05-27 verified] "pass X-Forwarded-User, X-Forwarded-Groups, X-Forwarded-Email and X-Forwarded-Preferred-Username information to upstream"	`official-vendor-doc`	oauth2-proxy reverse-proxy mode 의 upstream 헤더 주입	4개 헤더 모두가 기본 활성화 / 선택적 활성화인지의 default 값 확인 필요
OAUTH2PROXY-C5	OIDC provider 통합 시 `--oidc-issuer-url` 으로 OpenID Connect issuer URL 설정. discovery 비활성 시 `--oidc-jwks-url` 로 JWKS URI 명시 입력 필요.	[§OIDC provider configuration, 2026-05-27 verified] `--oidc-issuer-url`: "the OpenID Connect issuer URL, e.g. `https://accounts.google.com`" + `--oidc-jwks-url`: "OIDC JWKS URI for token verification; required if OIDC discovery is disabled and public key files are not provided"	`official-vendor-doc`	oauth2-proxy provider=oidc 또는 provider=keycloak-oidc 설정	provider=keycloak-oidc 와 provider=oidc 의 동작 차이 (groups claim 추출 방식 등) 는 별도 페이지

Usage Boundaries / 적용 경계

이 자료가 직접 증명하는 것 (2026-05-27 WebFetch 재검증 후):
- OAUTH2PROXY-C2, C3, C4, C5: official-vendor-doc 강도 — oauth2-proxy 공식 docs 원문 verbatim 일치 확인 (C3 는 헤더 1개 추가 정정).
- OAUTH2PROXY-C1: needs-confirmation 유지 — 2026-05-25 캡처의 reverse-proxy 동작 일반 설명 문장이 공식 페이지에서 동일 wording 미발견. paraphrase 의심.
이 자료가 증명하지 않는 것:
- 각 헤더의 정확한 spelling / case / default 활성화 여부 — paraphrase 인용으로는 byte-level 확정 불가
- oauth2-proxy 버전별 헤더 / 옵션명 변경 (예: v6 → v7 의 deprecation) — 본 인용 시점 명시 없음
- Keycloak provider=keycloak-oidc 와 provider=oidc 의 동작 차이 — 별도 페이지 확인 필요
- nginx auth_request mode 에서 response headers 가 어떤 directive 로 backend 까지 전파되는지 (nginx 측 설정)
내 프로젝트에 적용하려면 추가 확인이 필요한 것:
- C1 reverse-proxy 동작 정의의 정확한 공식 출처 (README / overview 의 다른 단락 / 별도 페이지) 재확보 후 verbatim quote 교체
- P1A 패턴에서 backend가 신뢰할 헤더 prefix 통일 (X-Auth-Request-* vs X-Forwarded-*) 결정
- oauth2-proxy → Keycloak OIDC issuer URL 입력 시 internal vs external hostname 일치성 (KC_HOSTNAME 결정과 연결)
- 헤더 spoofing 방어 (egress proxy 외부에서 X-Auth-Request-User 주입 차단) 필요

P1A 함의 (내 프로젝트 해석)

본 섹션은 자료 직접 인용이 아닌 패턴 결정 컨텍스트 해석. wiki 추출 시 옮겨야 함.

핵심: oauth2-proxy는 reverse proxy 형태(자체로 proxy)와 auth-only endpoint(/oauth2/auth) 형태(nginx auth_request / Traefik forwardAuth와 결합) 두 모드를 지원.
nginx 계열에서는 X-Auth-Request-* 가 응답 헤더(=ingress가 캡처해서 backend로 다시 주입), X-Forwarded-* 는 upstream으로 직접 forward할 때 사용. 두 prefix가 섞이지 않도록 정리 필요.
본 문서는 도식만 제공. 실제 nginx 설정 예시는 raw/official-docs/oauth2-proxy-nginx-integration-official 참고.

메모 / Notes

2026-05-27 재검증 완료: WebFetch 권한 복구 후 oauth2-proxy.github.io 공식 docs 직접 fetch.
1. C2 / C3 / C4 / C5 quote 가 공식 docs 원문에서 verbatim 일치 (C3 는 헤더 1개 추가 정정) → needs-confirmation → official-vendor-doc 격상.
2. C1 (reverse-proxy 일반 동작) 은 공식 페이지에서 동일 문장 미발견 → needs-confirmation 유지 + [2026-05-25 capture] 마크 + NOT FOUND 메모.
3. C2 quote 에 --set-xauthrequest 결합 동작 (X-Auth-Request-Access-Token response 헤더) 추가 확보.
frontmatter confidence: medium 유지 — C1 미확인으로 high 격상 보류.

같은 주제 다른 official-doc:
- raw/official-docs/oauth2-proxy-nginx-integration-official (실제 nginx 설정 예시, 별도 raw)
- raw/official-docs/oauth2-proxy-cookie-redirect-flags-official (같은 URL configuration/overview/ 의 섹션 분할 아카이브 — Cookie Options / --whitelist-domain / --skip-oidc-discovery 전용, 2026-07-17)
인용하는 branch:
인용한 wiki 요약: (미작성)

12 KiB Raw Blame History