llm-wiki/raw/official-docs/oauth2-proxy-session-storage-official.md

---
title: official-doc / OAuth2 Proxy — Session Storage (Cookie vs Redis backend)
source_type: official-doc
url: https://oauth2-proxy.github.io/oauth2-proxy/configuration/session_storage/
archive_url:
related_branches: [feature-keycloak-oauth2-proxy-oidc-flow]
related_projects: [keycloak-patterns]
tags: [official-doc, keycloak-patterns, auth, oauth2-proxy, redis]
created: 2026-07-17
---

# OAuth2 Proxy — Session Storage (Cookie vs Redis backend)

> Layer: `raw/official-docs/` — oauth2-proxy 의 `--session-store-type` 공식 문서 (`cookie` vs `redis`). P1A sub-sub-branch D5 (`cookie 설정 표준화`) 의 `UNSUPPORTED_DECISION` 을 세션 저장 백엔드 선택 메커니즘 근거로 해소하기 위한 자료.
> [[raw/official-docs/oauth2-proxy-overview-config-official]] 는 헤더 전달(auth-request 응답 헤더) 섹션만 다루므로 중복 아님 — 본 문서는 세션 저장소 백엔드 자체를 다룬다.

## Parent / 활용 branch (필수)

| Branch | 이 자료가 정당화하는 결정 |
|---|---|
| [[raw/branch-notes/feature-keycloak-oauth2-proxy-oidc-flow]] | D5 — oauth2-proxy session storage 모드 선택: cookie session store(기본, stateless, 클라이언트 저장) vs Redis session store(ticket 만 클라이언트 전달, 서버측 암호화 저장) 의 공식 메커니즘 근거 |

## 출처 / Source

- 원본 URL: https://oauth2-proxy.github.io/oauth2-proxy/configuration/session_storage/
- 아카이브 URL: (미수집)
- 저자 / 조직: oauth2-proxy maintainers
- 발행일: rolling docs (Docusaurus, Version 7.15.x 표기)
- 마지막 확인일: 2026-07-17

## 왜 저장했는지 / Why archived

P1A sub-sub-branch(`feature-keycloak-oauth2-proxy-oidc-flow`)의 D5 결정("cookie 설정 표준화")이 지금까지 `UNSUPPORTED_DECISION` 이었던 이유는 기존 raw 자료 2개(overview-config, keycloak-oidc-provider) 어디에도 세션 저장소 메커니즘 자체의 verbatim 인용이 없었기 때문. 본 문서는 `--session-store-type` 의 두 백엔드(cookie 기본값 / redis) 각각의 저장 위치, 동시성 제약, Redis ticket 포맷, CLI 플래그를 공식 문서에서 직접 발췌해 그 공백을 메운다.

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

> [§Cookie Storage] "With the Cookie storage backend, all session information is stored in client side cookies and transferred with each and every request."

> [§Cookie Storage] "Since all state is stored client side, this storage backend means that the OAuth2 Proxy is completely stateless"

> [§Cookie Storage] "Since multiple requests can be made concurrently to the OAuth2 Proxy, this session implementation cannot lock sessions and while updating and refreshing sessions, there can be conflicts which force users to re-authenticate"

> [§Redis Storage] "{CookieName}-{ticketID}.{secret}"

> [§Redis Storage] "The pair of {CookieName}-{ticketID} comprises a ticket handle, and thus, the redis key to which the session is stored. The encoded session is encrypted with the secret and stored in redis via the SETEX command."

> [§Usage] "When using the redis store, specify --session-store-type=redis as well as the Redis connection URL, via --redis-connection-url=redis://host[:port][/db-number] ."

> [§Usage] "You may also configure the store for Redis Sentinel. In this case, you will want to use the --redis-use-sentinel=true flag, as well as configure the flags --redis-sentinel-master-name and --redis-sentinel-connection-urls appropriately."

> [§Usage] "Redis Cluster is available to be the backend store as well. To leverage it, you will need to set the --redis-use-cluster=true flag, and configure the flags --redis-cluster-connection-urls appropriately."

> [§Usage] "Note that flags --redis-use-sentinel=true and --redis-use-cluster=true are mutually exclusive."

> **참고**: 위 페이지 전체에서 "4k", "4096", "split", "kb " 문자열은 검색되지 않음 — 즉 4kb 초과 시 쿠키 분할(split) 로직이나 최대 쿠키 길이 수치는 **이 URL 에 없다**. 사용자가 요청한 6개 논점 중 #2 는 이 자료로 충족 불가 — 별도 raw source(예: oauth2-proxy `overview` 페이지의 cookie 섹션, 또는 nginx `large_client_header_buffers` 관련 자료)가 추가로 필요하다.

## Claims Extracted / 추출된 주장

| Claim ID | Claim (이 자료가 직접 말하는 것) | Evidence quote | Strength | Applies to | Does not prove |
|---|---|---|---|---|---|
| O2PSESS-C1 | Cookie storage backend(기본값)은 모든 세션 정보를 클라이언트 측 쿠키에 저장하고 매 요청마다 전송하며, 이 때문에 oauth2-proxy 자체는 완전히 stateless 하다 | [§Cookie Storage] "With the Cookie storage backend, all session information is stored in client side cookies and transferred with each and every request." + "Since all state is stored client side, this storage backend means that the OAuth2 Proxy is completely stateless" | `official-vendor-doc` | `--session-store-type=cookie` (기본값) 채택 시 저장 위치와 전송 방식 | 쿠키 하나의 실제 바이트 크기 한도, 4kb 초과 시 분할(split) 동작, 또는 Azure AD/Google federation 시나리오에서 흔히 언급되는 큰 ID 토큰 크기 문제는 이 문서가 다루지 않는다 — Keycloak native(비-federation) 환경의 토큰 크기를 그 사례로 일반화할 근거가 이 문서엔 없다 |
| O2PSESS-C2 | Cookie storage backend 는 세션 lock 이 없어서, 동시 요청이 세션을 갱신/refresh 할 때 충돌이 발생할 수 있고 이 충돌이 사용자의 재인증을 강제할 수 있다 | [§Cookie Storage] "Since multiple requests can be made concurrently to the OAuth2 Proxy, this session implementation cannot lock sessions and while updating and refreshing sessions, there can be conflicts which force users to re-authenticate" | `official-vendor-doc` | `--session-store-type=cookie` 모드에서의 동시 refresh 경쟁 조건 | 이 충돌이 발생하는 정확한 조건(예: 동일 브라우저 tab 병렬 요청 수), 실제 발생 빈도, 또는 oauth2-proxy 로그에 남는 구체적 에러 메시지는 본 인용 범위 밖 |
| O2PSESS-C3 | Redis storage backend 는 세션 데이터 전체 대신 ticket(`{CookieName}-{ticketID}.{secret}`)만 클라이언트에 전달한다. `{CookieName}-{ticketID}` 쌍이 Redis key 이며, 암호화된 세션은 `SETEX` 명령으로 Redis 에 저장된다 | [§Redis Storage] "{CookieName}-{ticketID}.{secret}" + "The pair of {CookieName}-{ticketID} comprises a ticket handle, and thus, the redis key to which the session is stored. The encoded session is encrypted with the secret and stored in redis via the SETEX command." | `official-vendor-doc` | `--session-store-type=redis` 채택 시 ticket 구조와 저장 메커니즘 | ticketID/secret 이 128-bit 난수라는 서술(원문에 있으나 본 표엔 별도 quote 미포함)의 실제 난수 생성기 구현(CSPRNG 여부)까지는 증명하지 않음 — Redis 서버 자체의 가용성/영속성(AOF/RDB) 보장은 이 문서 범위 밖 |
| O2PSESS-C4 | Redis 백엔드는 `--session-store-type=redis` 플래그로 활성화하며, 연결은 `--redis-connection-url=redis://host[:port][/db-number]` 형식으로 지정한다 | [§Usage] "When using the redis store, specify --session-store-type=redis as well as the Redis connection URL, via --redis-connection-url=redis://host[:port][/db-number] ." | `official-vendor-doc` | Redis 단일 인스턴스 연결 설정 | 커넥션 풀 크기, TLS 연결(`rediss://`) 지원 여부는 이 인용에 명시 없음 |
| O2PSESS-C5 | Redis Sentinel 구성 시 `--redis-use-sentinel=true` 플래그와 함께 `--redis-sentinel-master-name`, `--redis-sentinel-connection-urls` 플래그를 설정해야 한다 | [§Usage] "You may also configure the store for Redis Sentinel. In this case, you will want to use the --redis-use-sentinel=true flag, as well as configure the flags --redis-sentinel-master-name and --redis-sentinel-connection-urls appropriately." | `official-vendor-doc` | 고가용성 Redis(Sentinel) 구성 | P1A(단일 EC2) 규모에서 Sentinel 도입이 필요한지 여부는 이 문서가 판단하지 않음 — 순수 플래그 존재 사실만 증명 |
| O2PSESS-C6 | Redis Cluster 구성 시 `--redis-use-cluster=true` 플래그와 `--redis-cluster-connection-urls` 플래그가 필요하며, `--redis-use-sentinel=true` 와 `--redis-use-cluster=true` 는 상호 배타적(mutually exclusive)이다 | [§Usage] "Redis Cluster is available to be the backend store as well. To leverage it, you will need to set the --redis-use-cluster=true flag, and configure the flags --redis-cluster-connection-urls appropriately." + "Note that flags --redis-use-sentinel=true and --redis-use-cluster=true are mutually exclusive." | `official-vendor-doc` | 고가용성 Redis(Cluster) 구성 및 Sentinel/Cluster 동시 사용 불가 제약 | Cluster 모드에서의 세션 데이터 샤딩/재분배 동작 세부는 이 인용 범위 밖 |

### Strength 근거

모든 Claim 은 `official-vendor-doc` — oauth2-proxy 공식 문서(`oauth2-proxy.github.io`)의 Configuration 레퍼런스 페이지이며 RFC/표준 사양은 아니므로 `official-standard` 아님. 벤더 공식 reference 문서이므로 `official-reference`/`official-vendor-doc` 경계에서 `official-vendor-doc` 채택(도구 자체 벤더가 발행).

## Usage Boundaries / 적용 경계

- **이 자료가 직접 증명하는 것**:
  - `O2PSESS-C1`: cookie 백엔드(기본값)의 클라이언트측 저장 + stateless 특성
  - `O2PSESS-C2`: cookie 백엔드의 세션 lock 부재 → 동시 refresh 충돌 → 재인증 강제 가능성
  - `O2PSESS-C3`: redis 백엔드의 ticket 포맷과 `SETEX` 저장 메커니즘
  - `O2PSESS-C4`: `--session-store-type=redis` + `--redis-connection-url` 플래그 형식
  - `O2PSESS-C5`/`O2PSESS-C6`: Sentinel/Cluster 플래그 및 상호 배타 제약
- **이 자료가 증명하지 않는 것**:
  - 쿠키가 4kb 를 초과할 때의 분할(split) 로직, 최대 쿠키 길이 수치 — 이 페이지에 해당 서술이 **없음** (grep 결과 0건, 위 핵심 인용 참고 노트 참조)
  - Azure AD/Google federation 시나리오의 큰 ID 토큰 크기 문제를 Keycloak native(non-federation) 환경에 그대로 일반화할 수 있다는 근거 — 이 문서는 어떤 IdP 도 특정하지 않으며, Keycloak 토큰 크기가 실제로 cookie 한도에 근접하는지도 언급하지 않는다
  - cookie 모드 vs redis 모드의 실측 성능/latency/운영 부담 비교
  - P1A(단일 EC2, Keycloak 26.x, Google federation 없음) 규모에서 어느 모드가 "충분"한지에 대한 권고 — 이 문서는 메커니즘만 서술, 규모별 권고 없음
- **내 프로젝트(P1A)에 적용하려면 추가 확인이 필요한 것**:
  - P1A 의 oauth2-proxy 가 보유할 세션 크기(id_token + access_token + role/group claim 총량)가 단일 쿠키 한도에 근접하는지 실측 필요 — 단, 정확한 한도 수치는 이 문서에 없으므로 별도 raw source 확보 후 실측
  - Redis 도입 시 `--redis-connection-idle-timeout` 을 `redis.conf` 의 `timeout` 값보다 작게 설정해야 한다는 제약(§Usage 마지막 문단, 본 표에는 별도 Claim ID 미부여 — session storage 모드 선택 자체와 직접 관련 없어 D5 범위에서 제외) 확인 필요

## 메모 / Notes

> 검증되지 않은 내 추론은 여기 한정.

- D5 의 "cookie 설정 표준화" 결정 자체(`--cookie-secret`/`--cookie-domain`/`--cookie-secure`/`--cookie-samesite`/`--cookie-expire`)는 여전히 이 문서만으로는 완전히 해소되지 않는다 — 이 문서는 **세션 저장 백엔드 선택**(cookie vs redis)의 메커니즘 근거이지, cookie 속성 값(secure/samesite/domain) 자체의 권고 근거는 아니다. `--cookie-expire`/`--cookie-refresh` 권장값(Access-Token/Refresh-Token lifespan 정렬)은 이 페이지에 있으나 본 raw 문서의 Claims 범위(세션 저장소 선택)에서는 제외했다 — 필요 시 별도 Claim 으로 분리 고려.
- P1A 는 단일 EC2 + 학습 노트(`documented-only`) 단계이므로, redis 도입 여부는 이 자료로 "가능하다"는 사실만 확정하고 "필요하다"는 결론까지는 내리지 않는다.
- 4kb 쿠키 분할 논점(사용자 요청 #2)은 별도 raw source 필요 — 다음 후보: oauth2-proxy 공식 `configuration/overview` 페이지의 Cookie 섹션.

## Related / 관련

- 같은 주제 다른 official-doc:
  - [[raw/official-docs/oauth2-proxy-overview-config-official]] — 헤더 전달 섹션 (본 문서와 역할 분리)
  - [[raw/official-docs/oauth2-proxy-keycloak-oidc-provider-official]] — `provider=keycloak-oidc` 연결/인가 설정
  - [[raw/official-docs/oauth2-proxy-nginx-integration-official]]
- 인용하는 branch:
  - [[raw/branch-notes/feature-keycloak-oauth2-proxy-oidc-flow]]
- 인용하는 wiki: (미작성)