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

현재 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으로만 저장됩니다.

AP1: SPA Direct + Resource Server

develop-keycloak-pattern1은 vanilla JavaScript SPA가 spa-public client로 Authorization Code + PKCE S256 로그인을 수행하는 패턴입니다. access/refresh token은 명시적인 in-memory store에만 보관되므로 새로고침하면 사라집니다.

./scripts/verify-pattern1.sh

브라우저에서 http://localhost:8088을 열어 로그인한 뒤 보호 API를 호출할 수 있습니다. SPA는 http://localhost:8081/api/me를 직접 호출하며 Spring Resource Server가 Bearer JWT를 검증합니다.

Keycloak의 dedicated audience mapper는 spa-public access token에 keycloak-pattern-api를 추가합니다. Spring은 signature, iss, exp뿐 아니라 이 aud도 검사합니다. verify-pattern1.sh는 같은 정상 토큰을 deliberately-wrong-audience를 기대하는 진단 인스턴스에도 제출해 401을 확인합니다.

Keycloak은 KC_HOSTNAME=http://localhost:8080을 기준으로 token의 iss를 발급합니다. 정상 Resource Server는 이 외부 issuer 문자열을 검증하되 JWKS는 Docker 내부의 http://keycloak:8080에서 가져옵니다. 진단 인스턴스는 일부러 http://wrong-issuer.invalid를 기대하도록 구성되어, 서명과 audience가 정상이더라도 issuer mismatch로 401을 반환합니다.

token 저장 위치와 XSS 범위는 docs/ap1-token-storage.md에 정리했습니다. E2E는 Web Storage token이 0개임과 동시에 실행 중 fetch hook이 Bearer header를 관찰할 수 있음을 재현합니다.

refresh rotation, 소비된 refresh token 재사용, RP-Initiated Logout, revocation과 stateless JWT의 차이는 docs/ap1-refresh-logout.md에 정리했으며 같은 E2E에서 실제 Keycloak 26.7.0 동작을 검증합니다.

5.0 KiB Raw Blame History