llm-wiki/vault/20-evidence/official-docs/oauth2-proxy-overview-config-official.md

---
title: OAuth2 Proxy — Configuration Overview (Official Docs)
source_type: official-doc
url: https://oauth2-proxy.github.io/oauth2-proxy/configuration/overview
archive_url:
status: raw
confidence: medium
tags: [keycloak-patterns, p1a-edge-forward-auth, oauth2-proxy, forward-auth, headers]
related_projects: [keycloak-patterns]
related_branches: [feature-keycloak-edge-forwardauth-no-google, feature-keycloak-patterns, feature-keycloak-oauth2-proxy-oidc-flow, feature-keycloak-nginx-auth-request-integration]
created: 2026-05-25
last_reviewed: 2026-05-27
---

# 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 격상 보류.

## Related / 관련

- 같은 주제 다른 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:
  - [[raw/branch-notes/feature-keycloak-edge-forwardauth-no-google]]
  - [[raw/branch-notes/feature-keycloak-patterns]]
  - [[raw/branch-notes/feature-keycloak-oauth2-proxy-oidc-flow]]
  - [[raw/branch-notes/feature-keycloak-nginx-auth-request-integration]]
- 인용한 wiki 요약: (미작성)