llm-wiki/raw/official-docs/oauth2-proxy-behaviour-cookie-vs-bearer-official.md at docs/ca-skeleton-frontend-runtime-adapter-features

Files

T

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

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

11 KiB

Raw Permalink 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

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 인가 실패 응답 코드 확인용).

같은 주제 다른 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 요약: (미작성)

11 KiB Raw Permalink Blame History

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