llm-wiki/raw/official-docs/oauth2-proxy-cookie-redirect-flags-official.md

title, source_type, url, archive_url, status, confidence, tags, related_projects, related_branches, created

title	source_type	url	archive_url	status	confidence	tags	related_projects	related_branches	created
OAuth2 Proxy — Cookie, Redirect Whitelist & OIDC Discovery Flags (Official Docs)	official-doc	https://oauth2-proxy.github.io/oauth2-proxy/configuration/overview/		raw	high	official-doc keycloak-patterns auth oauth2-proxy oidc	keycloak-patterns	feature-keycloak-oauth2-proxy-oidc-flow	2026-07-17

OAuth2 Proxy — Cookie, Redirect Whitelist & OIDC Discovery Flags (Official Docs)

Layer: raw/official-docs/ — 같은 URL(configuration/overview/)의 섹션 분할 아카이브. 이 파일은 Cookie Options / Proxy Options(--whitelist-domain) / OIDC discovery bypass 섹션 전용이다. 헤더 전달 섹션(--pass-access-token, --set-xauthrequest, --pass-user-headers, X-Auth-Request-*)과 --oidc-issuer-url/--oidc-jwks-url 의 의미는 이미 raw/official-docs/oauth2-proxy-overview-config-official 에 보존돼 있으므로 여기서 재발췌하지 않는다. 원본 페이지는 WebFetch(요약 모델 경유)가 verbatim 을 보장하지 못해, curl 로 raw HTML 을 받아 태그 제거 후 self-grep 한 텍스트를 근거로 사용했다 (아래 ## 출처 참고).

Parent / 활용 branch

Branch	이 자료가 정당화하는 결정
raw/branch-notes/feature-keycloak-oauth2-proxy-oidc-flow	oauth2-proxy cookie 설정 표준화(D5: --cookie-secret/--cookie-domain/--cookie-secure/--cookie-samesite/--cookie-expire/--cookie-refresh) + open redirect 방어(--whitelist-domain) + OIDC discovery 우회(--skip-oidc-discovery) 플래그의 공식 정의·기본값 근거

출처 / Source

• 원본 URL: https://oauth2-proxy.github.io/oauth2-proxy/configuration/overview/
• 아카이브 URL: (미수집)
• 저자 / 조직: oauth2-proxy maintainers (GitHub oauth2-proxy/oauth2-proxy)
• 발행일: rolling docs (지속 업데이트, 버전 pin 없음)
• 마지막 확인일: 2026-07-17 — curl 로 raw HTML 수집(200 OK, 91374 bytes) 후 태그 제거·엔티티 디코딩한 plain text(source-fetch-20260717-173104.txt, 649줄)에 대해 self-grep 검증 완료 (WebFetch 요약 도구는 사용하지 않음 — verbatim 보장 불가로 판단)

왜 저장했는지 / Why archived

D5(cookie 설정)는 기존 sibling 자료(overview-config, keycloak-oidc-provider)에 cookie 옵션 verbatim 이 없어 UNSUPPORTED_DECISION으로 표기돼 있었다. 본 자료는 그 gap을 메우고, --whitelist-domain(open redirect 방어)과 --skip-oidc-discovery(수동 endpoint 전환)의 공식 정의를 함께 확보한다.

핵심 인용 / Key quotes (verbatim)

이 branch의 명시적 요청(8개 논점)에 맞춰 템플릿 권장치(3~5개)보다 많은 10개 quote 를 확보했다. 모두 self-grep 통과.

[§Cookie Options — flag: --cookie-samesite] "set SameSite cookie attribute ("lax", "strict", "none", or "")." — Default 컬럼: ""

[§Cookie Options — flag: --cookie-secure] "set secure (HTTPS only) cookie flag" — Default 컬럼: true

[§Cookie Options — flag: --cookie-secret] "the seed string for secure cookies (optionally base64 encoded)"

[§Cookie Options — flag: --cookie-secret-file] "File containing the cookie secret (must be raw binary, exactly 16, 24, or 32 bytes). Use dd if=/dev/urandom bs=32 count=1 > cookie.secret to generate"

[§Cookie Options — flag: --cookie-expire] "expire timeframe for cookie. If set to 0, cookie becomes a session-cookie which will expire when the browser is closed." — Default 컬럼: 168h0m0s

[§Cookie Options — flag: --cookie-refresh + Footnote 1] "refresh the cookie after this duration; 0 to disable; not supported by all providers" / "The following providers support --cookie-refresh: ADFS, Azure, GitLab, Google, Keycloak and all other Identity Providers which support the full OIDC specification"

[§Cookie Options — flag: --cookie-csrf-samesite] "set SameSite CSRF cookie attribute ("lax", "strict", "none", or ""). When using the default setting, the CSRF cookie samesite value is taken from the session cookie configuration." — Default 컬럼: ""

[§Proxy Options — flag: --whitelist-domain + Footnote 2] "allowed domains for redirection after authentication. Prefix domain with a . or a *. to allow subdomains (e.g. .example.com, *.example.com)" / "When using the whitelist-domain option, any domain prefixed with a . or a *. will allow any subdomain of the specified domain as a valid redirect URL. By default, only empty ports are allowed. This translates to allowing the default port of the URL's protocol (80 for HTTP, 443 for HTTPS, etc.) since browsers omit them. To allow only a specific port, add it to the whitelisted domain: example.com:8080. To allow any port, use : example.com:."

[§OIDC Options — flag: --skip-oidc-discovery] "bypass OIDC endpoint discovery. --login-url, --redeem-url and --oidc-jwks-url must be configured in this case" — Default 컬럼: false

[§OIDC Options — flags: --login-url / --redeem-url / --oidc-public-key-file] "Authentication endpoint" / "Token redemption endpoint" / "Path to public key file in PEM format to use for verifying JWT tokens (may be given multiple times). Required if OIDC discovery is disabled na JWKS URL isn't provided" (마지막 문구의 "na" 는 원문 그대로 — 공식 문서 자체의 오탈자로 보이며 "and" 의미로 추정되나 verbatim 보존을 위해 수정하지 않음)

Claims Extracted / 추출된 주장

Claim ID	Claim (이 자료가 직접 말하는 것)	Evidence quote	Strength	Applies to	Does not prove
O2PCOOKIE-C1	--cookie-samesite 는 "lax" / "strict" / "none" / "" (빈 문자열) 중 하나를 값으로 받으며, 기본값은 "" (빈 문자열)	"set SameSite cookie attribute ("lax", "strict", "none", or "")." (Default: "")	official-vendor-doc	oauth2-proxy 세션 쿠키의 SameSite 속성 설정	빈 문자열("")일 때 브라우저가 실제로 어떤 SameSite 로 해석하는지(브라우저 기본값 준수 여부)는 이 페이지에서 확인되지 않음
O2PCOOKIE-C2	--cookie-secure 는 쿠키에 Secure(HTTPS-only) 플래그를 설정하며, 기본값은 true	"set secure (HTTPS only) cookie flag" (Default: true)	official-vendor-doc	oauth2-proxy 배포 시 쿠키 전송 채널 제한	HTTP 로만 서비스되는 로컬 개발 환경에서 이 기본값을 끄지 않으면 어떤 오류가 나는지는 이 페이지에 명시 없음
O2PCOOKIE-C3	--cookie-secret 자체는 "seed string(선택적으로 base64 인코딩)"으로 서술되고, 파일로 제공하는 --cookie-secret-file 은 "raw binary, exactly 16, 24, or 32 bytes" 여야 한다고 명시	"the seed string for secure cookies (optionally base64 encoded)" + "File containing the cookie secret (must be raw binary, exactly 16, 24, or 32 bytes). Use dd if=/dev/urandom bs=32 count=1 > cookie.secret to generate"	official-vendor-doc	cookie secret 생성/관리 방식 결정	--cookie-secret (문자열 플래그, base64 optional) 에도 동일한 16/24/32 byte 제약이 적용되는지는 이 문장만으로는 명시되지 않음 — 이 byte 길이 서술은 -file 변형에 대한 것
O2PCOOKIE-C4	--cookie-expire 는 쿠키 만료 시간을 정하며, 0 이면 브라우저 종료 시 만료되는 세션 쿠키가 됨. 기본값은 168h0m0s (7일)	"expire timeframe for cookie. If set to 0, cookie becomes a session-cookie which will expire when the browser is closed." (Default: 168h0m0s)	official-vendor-doc	세션 만료 정책 결정	168h 가 refresh 없이도 유지되는 절대 만료인지, 활동 기반 rolling expire 인지는 이 문장만으로 불명
O2PCOOKIE-C5	--cookie-refresh 는 지정한 duration 후 쿠키를 refresh하며 0 이면 비활성화. 모든 provider 가 지원하지 않으며, 지원 provider 목록은 ADFS/Azure/GitLab/Google/Keycloak + full OIDC spec 지원 IdP 전체	"refresh the cookie after this duration; 0 to disable; not supported by all providers" + footnote: "The following providers support --cookie-refresh: ADFS, Azure, GitLab, Google, Keycloak and all other Identity Providers which support the full OIDC specification"	official-vendor-doc	Keycloak 은 --cookie-refresh 지원 provider 목록에 명시적으로 포함	이 페이지의 Default 컬럼은 해당 행에서 빈 값(테이블상 값 없음) — 명시적 기본 duration 수치는 이 표에 없음(설명 문구는 "0 to disable"만 언급)
O2PCOOKIE-C6	--cookie-csrf-samesite 는 별도로 존재하는 플래그이며, "lax"/"strict"/"none"/"" 값을 받고 기본값은 "". 기본 설정(빈 문자열)일 때 CSRF 쿠키의 SameSite 값은 세션 쿠키(--cookie-samesite) 설정값을 그대로 따른다고 명시	"set SameSite CSRF cookie attribute ("lax", "strict", "none", or ""). When using the default setting, the CSRF cookie samesite value is taken from the session cookie configuration." (Default: "")	official-vendor-doc	--cookie-csrf-samesite 를 명시적으로 설정하지 않는 한, --cookie-samesite 값이 CSRF 쿠키에도 상속됨	--cookie-csrf-samesite 를 세션 쿠키와 다르게 명시했을 때의 상호작용(예: 어느 한쪽이 none 이고 다른 쪽이 strict 인 조합)까지는 이 문장이 다루지 않음
O2PCOOKIE-C7	--whitelist-domain 은 인증 후 redirect 를 허용할 도메인 목록이며, 도메인 앞에 . 또는 *. 를 붙이면 서브도메인 전체를 허용. 기본적으로 URL 프로토콜의 default port(80/443 등, 브라우저가 생략하는 포트)만 허용하고, 특정 포트를 허용하려면 example.com:8080, 모든 포트를 허용하려면 example.com:* 형식 사용	"allowed domains for redirection after authentication. Prefix domain with a . or a *. to allow subdomains (e.g. .example.com, *.example.com)" + footnote: "When using the whitelist-domain option, any domain prefixed with a . or a *. will allow any subdomain... By default, only empty ports are allowed... To allow only a specific port, add it to the whitelisted domain: example.com:8080. To allow any port, use : example.com:."	official-vendor-doc	open redirect 방어를 위한 허용 도메인/포트 화이트리스트 문법	이 표의 Default 컬럼은 해당 행에서 빈 값 — --whitelist-domain 을 아예 설정하지 않았을 때 모든 redirect 가 차단되는지, 아니면 별도 fallback(예: 자기 자신 host 만 허용)이 있는지는 이 페이지에서 확인되지 않음
O2PCOOKIE-C8	--skip-oidc-discovery 는 OIDC endpoint discovery(.well-known/openid-configuration 자동 조회)를 우회하며, 이 경우 --login-url, --redeem-url, --oidc-jwks-url 세 플래그를 반드시 수동 설정해야 함. 기본값은 false	"bypass OIDC endpoint discovery. --login-url, --redeem-url and --oidc-jwks-url must be configured in this case" (Default: false)	official-vendor-doc	OIDC discovery 를 쓸 수 없는 환경(예: 사설 network, discovery endpoint 미노출) 에서의 수동 전환 결정	discovery 를 우회했을 때 --scope, --oidc-groups-claim 등 discovery 응답에서 얻던 다른 값들도 함께 수동 설정이 필요한지는 이 문장에 없음
O2PCOOKIE-C9	discovery 우회 시 필요한 3개 수동 endpoint 중 --login-url 은 "Authentication endpoint", --redeem-url 은 "Token redemption endpoint" 로 정의되고, --oidc-jwks-url 대신(또는 함께) --oidc-public-key-file 로 PEM 형식 공개키 파일(다회 지정 가능)을 지정할 수도 있음	"toml: login_url ... Authentication endpoint" / "toml: redeem_url ... Token redemption endpoint" / "Path to public key file in PEM format to use for verifying JWT tokens (may be given multiple times). Required if OIDC discovery is disabled na JWKS URL isn't provided"	official-vendor-doc	--skip-oidc-discovery=true 조합에서 JWKS URL 대신 로컬 공개키 파일을 쓰는 대안 경로	--oidc-jwks-url 자체의 의미·형식은 본 문서에서 재발췌하지 않음 — raw/official-docs/oauth2-proxy-overview-config-official OAUTH2PROXY-C5 참조

Usage Boundaries / 적용 경계

• 이 자료가 직접 증명하는 것:
  • O2PCOOKIE-C1~C9: 위 9개 claim 모두 공식 docs 표(Flag/Config Field 테이블)의 Description·Default 컬럼 원문에서 verbatim 확인.
  • 특히 O2PCOOKIE-C6 은 부모 branch-note 에서 "현재 INFERENCE 상태" 로 표기됐던 --cookie-csrf-samesite ↔ --cookie-samesite 상호작용을 공식 문서가 명시적으로 진술함을 확인 — 더 이상 추론이 아님.
• 이 자료가 증명하지 않는 것:
  • --whitelist-domain 을 아예 설정하지 않았을 때(미설정 시)의 기본 동작 — 표의 Default 컬럼이 빈 값이라 이 페이지만으로는 "전체 차단"인지 다른 fallback 인지 확정 불가.
  • --cookie-refresh 의 명시적 기본 duration 수치 — 표의 Default 컬럼이 빈 값(설명 문구는 "0 to disable"만 언급).
  • --cookie-secret(문자열 플래그) 자체에도 16/24/32 byte 제약이 적용되는지 — 이 byte 길이 서술은 --cookie-secret-file 행에 있음.
  • 버전별 플래그 변경/deprecation 이력 — 이 페이지는 rolling docs 로 버전 pin이 없음.
  • Keycloak 특정 세션 정책과의 실제 상호작용(예: Keycloak SSO 세션 만료와 oauth2-proxy --cookie-expire 의 정합) — 이 페이지는 oauth2-proxy 일반 옵션만 서술.
• 내 프로젝트에 적용하려면 추가 확인이 필요한 것:
  • --whitelist-domain 미설정 시 실제 동작을 소스코드 또는 별도 테스트로 확인.
  • --cookie-samesite=lax(또는 none) 선택이 P1A edge forward-auth 구성(같은 site vs cross-site redirect)에서 실제로 요구되는 값인지 결정 — 이 페이지는 옵션 존재만 증명, 값 선택은 P1A 아키텍처 결정 사항.
  • 이 branch 는 documented-only 범위(P1A, 단일 EC2, Keycloak 26.x 학습 노트) — 내 프로젝트 실 구성 검증 주장으로 승격 금지.

메모 / Notes

• WebFetch(요약 모델 경유) 1차 시도는 각 플래그 설명을 재서술(paraphrase)해 verbatim 보장이 안 됨 → curl raw HTML 수집 + Python 태그 제거/엔티티 디코딩 파이프라인으로 대체. 이 방식이 Self-Grep 원칙(원문 바이트 그대로 대조)에 더 부합한다고 판단.
• --oidc-public-key-file 설명 문구의 "na JWKS URL isn't provided" 는 공식 문서 자체 오탈자로 보임("and"의 오기로 추정). verbatim 보존을 위해 그대로 인용, 임의 정정하지 않음.
• --whitelist-domain·--cookie-refresh 의 Default 컬럼이 표에서 비어 있는 것은 HTML 원문(<td></td>)에서도 확인됨 — 페이지 자체의 서술 누락이지 추출 과정의 손실이 아님.

Related / 관련

• 같은 URL 의 다른 섹션(헤더 전달 + --oidc-issuer-url/--oidc-jwks-url): raw/official-docs/oauth2-proxy-overview-config-official
• 같은 주제 다른 official-doc: raw/official-docs/oauth2-proxy-keycloak-oidc-provider-official, raw/official-docs/oauth2-proxy-nginx-integration-official
• 인용하는 branch: raw/branch-notes/feature-keycloak-oauth2-proxy-oidc-flow
• 인용한 wiki 요약: (미작성)