DongHyeonkaandClaude Opus 5
919547a025
B-7 stopped at "could not delete the server-side session". The reason it gave was right: the ticket carries the session id, the ticket is encrypted with the cookie secret, so after a rotation the proxy cannot work out which Redis key to remove. But that is a limitation of the proxy, not of Redis. Measured across two rotations: - The orphan does expire. TTL falls one second per second and is not refreshed by requests (the startup log says refresh:disabled, and --cookie-refresh is unset), so it dies exactly one hour after creation. - An operator can delete it. `redis-cli del` returned 1, dbsize went 2 to 1, and the live session answered /oauth2/userinfo with 200 immediately after. - But nothing in Redis says which key is the orphan. Same name prefix, same type, the same 3510 bytes, and the values are encrypted. - TTL is the only signal, and because it is never refreshed it is an exact function of creation time. Anything created before the rotation is an orphan. Derived creation time 11:30:26 against the AuthSuccess log line at 11:30:27 — one second out. The rule was then run and removed the orphan while leaving the live session. - They accumulate: the session that survived the first rotation became the orphan of the second. The caveat is recorded too: turning on --cookie-refresh breaks the derivation, and at that point flushing and forcing everyone to re-authenticate is the more honest option. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Keycloak Authentication Patterns
The 39-branch implementation registry is documented in
docs/keycloak-branch-index.md.
Google brokering has a credential-free local OIDC harness and an opt-in
real-Google profile described in
docs/google-idp-brokering.md.
Keycloak을 중심으로 네 가지 브라우저 인증 통합 패턴을 같은 로컬 인프라에서 비교하는 학습 프로젝트입니다.
- AP1: Browser-based OAuth Client (SPA direct + Resource Server)
- AP2: Token-Mediating Backend
- AP3: Backend-for-Frontend (BFF)
- AP4: Edge forward-auth
세션 저장소·refresh token 경쟁·장애 복구는 네 패턴을 가로지르는 별도 축으로
develop-keycloak-session-store 브랜치에서 진행합니다. 계획과 진행 상황은
docs/session-store-lab-roadmap.md에
있습니다.
현재 develop의 공통 baseline은 Keycloak, PostgreSQL, Spring Boot API,
nginx를 Docker Compose로 실행하는 토대입니다. 패턴별 구현은 이 baseline
위에서 별도 브랜치로 진행합니다.
요구 사항
- Docker Engine
- Docker Compose
curl
로컬 Java나 Maven은 필요하지 않습니다. Spring Boot 빌드와 테스트는 Maven 컨테이너에서 수행합니다.
시작
cp .env.example .env
docker compose up --build -d
./scripts/verify-stack.sh
기본 주소는 다음과 같습니다.
| 구성 요소 | 주소 |
|---|---|
| Keycloak | http://localhost:8080 |
| Spring Boot API | http://localhost:8081 |
| nginx | http://localhost:8088 |
host의 80번 포트를 쓸 수 있는 single-EC2 환경에서는 .env의
NGINX_PORT=80으로 변경할 수 있습니다.
상태 확인
docker compose ps
docker compose logs -f keycloak
curl http://localhost:8088/api/public
curl -i http://localhost:8088/api/me
/api/public은 200, 인증 정보가 없는 /api/me는 401이 정상입니다.
환경 초기화
PostgreSQL과 Keycloak data volume을 제거하고 realm import부터 다시 검증하려면 다음 한 줄을 사용합니다.
docker compose down -v && docker compose up --build -d
start-dev와 로컬 HTTP 설정은 학습 전용입니다. 운영 환경에서는
optimized Keycloak image, HTTPS, 엄격한 hostname 및 외부 secret store를
사용해야 합니다.
Realm baseline
keycloak/import/keycloak-patterns-realm.json은 시작 시 자동 import됩니다.
하나의 keycloak-patterns realm 안에서 패턴마다 client를 분리합니다.
| Client | 유형 | 패턴 |
|---|---|---|
spa-public |
public + PKCE S256 | AP1 |
token-mediating-confidential |
confidential | AP2 |
bff-confidential |
confidential | AP3 |
edge-proxy |
confidential | AP4 |
confidential client secret과 테스트 사용자 password는 JSON에 평문으로
저장하지 않습니다. JSON에는 ${ENVIRONMENT_VARIABLE} placeholder만
커밋하고, Keycloak 26.7.0이 import 시 .env 값을 주입합니다.
python3 scripts/validate-realm.py
docker compose down -v
docker compose up -d --wait
./scripts/verify-realm.sh
실행 중인 DB에서 CLI realm export를 재현하려면 다음 명령을 사용합니다. Keycloak을 잠시 중지하고 export한 뒤 자동으로 다시 올립니다.
./scripts/export-realm.sh
runtime export에는 실제 client secret과 credential hash가 포함될 수 있어
gitignored build/keycloak-export/에 권한 0600으로만 저장됩니다.