llm-wiki/raw/official-docs/oauth2-proxy-behaviour-cookie-vs-bearer-official.md

---
title: OAuth2 Proxy — Behaviour (Official Docs, cookie session vs JWT bearer 검증 분기)
source_type: official-doc
url: https://oauth2-proxy.github.io/oauth2-proxy/behaviour/
archive_url:
status: raw
confidence: medium
tags: [official-doc, keycloak-patterns, auth, oauth2-proxy, oidc]
related_projects: [keycloak-patterns]
related_branches: [feature-keycloak-oauth2-proxy-oidc-flow]
created: 2026-07-17
last_reviewed: 2026-07-17
---

# OAuth2 Proxy — Behaviour (Official Docs, cookie session vs JWT bearer 검증 분기)

> Layer: `raw/official-docs/` — oauth2-proxy 공식 "Behaviour" 페이지. 요청이 인증/인가를 통과하는 전체 흐름(스킵 라우트 opportunistic 검증 → 미인증 시 redirect/401 분기 → invalid JWT fallback → post-auth 세션 저장 → forwarding)을 단계별로 서술.

## Parent / 활용 branch

| Branch | 이 자료가 정당화하는 결정 |
|---|---|
| [[raw/branch-notes/feature-keycloak-oauth2-proxy-oidc-flow]] | oauth2-proxy 의 요청 검증 분기 — cookie session 경로 vs `--skip-jwt-bearer-tokens` 를 통한 JWT bearer 검증 경로가 어떤 조건으로 갈리는지, 그리고 branch-note 가 이 모드를 "token introspection 모드"로 지칭한 **명칭의 정확성**을 검증하는 근거 |

## 출처 / Source

- 원본 URL: https://oauth2-proxy.github.io/oauth2-proxy/behaviour/
- 아카이브 URL: (미수집)
- 저자 / 조직: oauth2-proxy maintainers (GitHub `oauth2-proxy/oauth2-proxy`, CNCF Slack 소속 문서), Docusaurus 버전 배지 `7.15.x`
- 발행일: rolling docs (지속 업데이트, 버전 `7.15.x` 기준 캡처)
- 마지막 확인일: 2026-07-17 (curl 직접 fetch, HTML 원문 저장 후 self-grep 검증 완료)

## 왜 저장했는지 / Why archived

P1A sub-sub-branch(`feature-keycloak-oauth2-proxy-oidc-flow`)가 "token introspection 모드"라고 불러온 `--skip-jwt-bearer-tokens` 옵션의 **정확한 동작**(opportunistic validation 조건, invalid JWT 시 fallback, 응답 코드 401 vs 403 vs redirect 분기)을 공식 문서로 고정하기 위함. branch-note D4의 Open Risk("인가 실패 시 401 vs 403 인용 범위 밖")에 직접 답하는 페이지.

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

> [§1 Authentication Requirement — skipped route exception] "Authentication is not enforced, but the proxy will opportunistically attempt to validate a session cookie (`--cookie-name`) or JWT (`--skip-jwt-bearer-tokens`) if present in the request."

> [§2 Unauthenticated Requests — Ajax] "Ajax Requests: If the request has `Accept: application/json` header:" → "Returns `401 Unauthorized`."

> [§2 Unauthenticated Requests — Invalid JWT Tokens 조건] "Invalid JWT Tokens: If `--skip-jwt-bearer-tokens` is set and the request includes an invalid JWT:"

> [§2 Unauthenticated Requests — Invalid JWT Tokens 기본 결과] "Redirects to the login page by default."

> [§2 Unauthenticated Requests — Invalid JWT Tokens fallback=false 결과] "Returns `403 Forbidden` if `--bearer-token-login-fallback` is set to `false`."

## Claims Extracted / 추출된 주장

| Claim ID | Claim (이 자료가 직접 말하는 것) | Evidence quote | Strength | Applies to | Does not prove |
|---|---|---|---|---|---|
| O2PBEH-C1 | 스킵된 라우트(`--skip-auth-route`)에서도 인증은 강제되지 않지만, 프록시는 session cookie(`--cookie-name`) 또는 JWT(`--skip-jwt-bearer-tokens`)가 요청에 존재하면 **opportunistic 하게** 검증을 시도한다 | [§1] "Authentication is not enforced, but the proxy will opportunistically attempt to validate a session cookie (`--cookie-name`) or JWT (`--skip-jwt-bearer-tokens`) if present in the request." | `official-vendor-doc` | `--skip-auth-route` 로 인증을 스킵한 라우트에서의 opportunistic 검증 동작 | 스킵되지 않은(=인증 강제) 라우트에서 cookie/JWT 를 각각 어떤 순서·우선순위로 시도하는지는 본 인용 범위 밖. `--skip-jwt-bearer-tokens` 의 실제 검증 메커니즘(로컬 서명 검증 vs introspection 호출)은 본 인용에 없음 |
| O2PBEH-C2 | `Accept: application/json` 헤더를 포함한 미인증 Ajax 요청은 로그인 페이지 redirect 대신 `401 Unauthorized` 를 반환한다 | [§2] "Ajax Requests: If the request has `Accept: application/json` header:" + "Returns `401 Unauthorized`." | `official-vendor-doc` | 미인증(unauthenticated) 요청 중 Ajax 판별 조건에서의 응답 코드 | 인가(authorization) 실패(예: `--allowed-role`/`--allowed-group` 불충족) 시 응답 코드는 본 인용 범위 밖 — 이 claim 은 authentication 실패 케이스만 다룸 |
| O2PBEH-C3 | `--skip-jwt-bearer-tokens` 가 설정된 상태에서 요청에 invalid JWT 가 포함되면, **기본값은 로그인 페이지로 redirect** 이다 | [§2] "Invalid JWT Tokens: If `--skip-jwt-bearer-tokens` is set and the request includes an invalid JWT:" + "Redirects to the login page by default." | `official-vendor-doc` | `--skip-jwt-bearer-tokens` 활성화 상태에서 invalid JWT(예: 만료/서명 불일치)가 도착했을 때의 기본 동작 | "invalid" 의 정의(만료/malformed/audience 불일치 등 구체 사유)는 본 페이지(behaviour)에 명시되지 않음 — 별도 페이지(configuration/overview) 확인 필요(아래 메모 참고) |
| O2PBEH-C4 | `--bearer-token-login-fallback` 이 `false` 로 설정되면, invalid JWT 요청은 redirect 대신 `403 Forbidden` 을 반환한다 | [§2] "Returns `403 Forbidden` if `--bearer-token-login-fallback` is set to `false`." | `official-vendor-doc` | `--bearer-token-login-fallback=false` 조합에서의 invalid JWT 응답 코드 | 이 403 이 "인증 실패"인지 "인가 실패"인지의 개념적 구분은 본 인용에 명시되지 않음 — 문맥상 JWT **검증 실패**(authentication 단계)에 대한 응답이며, role/group 기반 인가 실패의 응답 코드와는 별개 주제 |

### Strength 근거

전부 `official-vendor-doc` — oauth2-proxy 공식 문서(oauth2-proxy.github.io, 버전 `7.15.x`) 원문에서 curl 직접 fetch 후 self-grep 검증(아래 리포트 참고). paraphrase 없음, 원문 byte 그대로.

## Usage Boundaries / 적용 경계

- **이 자료가 직접 증명하는 것**:
  - `O2PBEH-C1`: 스킵 라우트에서 cookie/JWT 존재 시 opportunistic 검증 시도한다는 사실.
  - `O2PBEH-C2`: Ajax(`Accept: application/json`) 미인증 요청은 401을 반환한다는 사실.
  - `O2PBEH-C3`, `O2PBEH-C4`: invalid JWT 상황에서 기본값은 redirect, `--bearer-token-login-fallback=false` 조합에서만 403 이라는 사실.
- **이 자료가 증명하지 않는 것 (명칭 검증 핵심)**:
  - **`--skip-jwt-bearer-tokens` 가 로컬 JWKS 서명 검증인지 authorization server 의 introspection endpoint(RFC 7662)를 호출하는 것인지, 본 페이지는 명시하지 않는다.** "opportunistically attempt to validate ... JWT" 라는 표현은 검증(validate) 행위만 서술할 뿐 메커니즘을 특정하지 않음.
  - 참고(추가 조사, 별도 dispatch 필요 — 본 raw 문서의 verbatim 범위 밖이므로 Claim 화하지 않음): 동일 사이트 `configuration/overview` 페이지(`https://oauth2-proxy.github.io/oauth2-proxy/configuration/overview`)의 `--extra-jwt-issuers` 플래그 설명에 "a list of extra JWT issuer=audience ... pairs (where the issuer URL has a `.well-known/openid-configuration` or a `.well-known/jwks.json`)"라는 서술이 존재하고, `--skip-jwt-bearer-tokens` 설명에도 "the token must have `aud` that matches this client id"라는 서술이 존재한다. 이는 **JWKS 기반 로컬 서명 검증(issuer/audience claim 대조)**을 시사하며, RFC 7662 introspection(=매 요청마다 authorization server 로 살아있는 network call)과는 다른 메커니즘으로 보인다. 다만 이 인용은 `/behaviour/` 페이지가 아닌 별도 URL의 내용이므로, **본 raw 문서에서는 Claim 근거로 사용하지 않는다** (1 dispatch = 1 URL 원칙). branch-note 의 "token introspection 모드" 명칭을 교정하려면 `configuration/overview` 페이지를 별도 `raw/official-docs/` dispatch 로 등록해 Claim ID 를 확보해야 한다.
  - 인가(authorization, role/group 기반) 실패 시 응답 코드(401 vs 403)는 본 페이지 범위 밖 — 본 페이지가 다루는 401/403/redirect 는 모두 **authentication(신원 확인) 단계**의 응답이다. branch-note D4 의 Open Risk("인가 실패 시 401 vs 403")는 본 문서로 완전히 해소되지 않음 — authorization 전용 서술은 `raw/official-docs/oauth2-proxy-keycloak-oidc-provider-official.md` 의 `O2PK-C3`(§Authorization)를 참고하되, 그 인용에도 "인가 실패 시 응답 코드"는 명시되어 있지 않음(해당 파일 Does not prove 참고).
- **내 프로젝트에 적용하려면 추가 확인이 필요한 것**:
  - `configuration/overview` 페이지를 별도 raw-source 로 등록해 `--skip-jwt-bearer-tokens`/`--extra-jwt-issuers` 의 verbatim 을 Claim 화 — "token introspection 모드"라는 branch-note 표현을 "JWT bearer 로컬 검증 모드"로 교정할 공식 근거 확보.
  - 인가 실패 시 정확한 응답 코드는 oauth2-proxy 소스 코드 또는 별도 공식 페이지에서 추가 확인 필요.

## 메모 / Notes

- **명칭 drift 발견**: branch-note `feature-keycloak-oauth2-proxy-oidc-flow` 가 `--skip-jwt-bearer-tokens` 를 "token introspection 모드"로 지칭하고 있으나, 본 페이지의 verbatim ("opportunistically attempt to validate ... JWT")과 `configuration/overview` 페이지의 `--extra-jwt-issuers`/`aud` claim 서술을 종합하면 이 옵션은 **JWT 를 로컬에서 서명·claim 검증**하는 것으로 보이며, RFC 7662 introspection endpoint(매 요청마다 authorization server 에 살아있는 네트워크 호출)와는 다른 메커니즘일 가능성이 높다. 단, 이 해석은 `configuration/overview` 페이지 내용에 의존하므로 **미검증(needs-confirmation)** — 별도 raw-source dispatch 로 확정 필요.
- 이 페이지는 401/403/redirect 3갈래 응답 코드를 **authentication** 관점에서만 서술한다. **authorization**(role/group) 실패 응답 코드는 다른 페이지를 봐야 한다.
- 추가로 봐야 할 동일 사이트 페이지: `configuration/overview`(JWT 검증 메커니즘 확인용, curl 로 확보한 컨텍스트는 위 Usage Boundaries 참고 — 별도 dispatch 필요), `configuration/providers/keycloak-oidc`(role/group 인가 실패 응답 코드 확인용).

## Related / 관련

- 같은 주제 다른 official-doc:
  - [[raw/official-docs/oauth2-proxy-overview-config-official]] — oauth2-proxy 공식 configuration overview (헤더 전달, OIDC issuer URL)
  - [[raw/official-docs/oauth2-proxy-keycloak-oidc-provider-official]] — oauth2-proxy ↔ Keycloak OIDC provider 연동 (역할/그룹 인가)
  - [[raw/official-docs/oauth2-proxy-nginx-integration-official]] — nginx auth_request 통합
- 이 자료를 인용한 wiki 요약: (미작성)