125 lines
4.2 KiB
Markdown
125 lines
4.2 KiB
Markdown
# Keycloak Authentication Patterns
|
|
|
|
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
|
|
컨테이너에서 수행합니다.
|
|
|
|
## 시작
|
|
|
|
```bash
|
|
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`으로 변경할 수 있습니다.
|
|
|
|
## 상태 확인
|
|
|
|
```bash
|
|
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부터 다시
|
|
검증하려면 다음 한 줄을 사용합니다.
|
|
|
|
```bash
|
|
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` 값을 주입합니다.
|
|
|
|
```bash
|
|
python3 scripts/validate-realm.py
|
|
docker compose down -v
|
|
docker compose up -d --wait
|
|
./scripts/verify-realm.sh
|
|
```
|
|
|
|
실행 중인 DB에서 CLI realm export를 재현하려면 다음 명령을 사용합니다.
|
|
Keycloak을 잠시 중지하고 export한 뒤 자동으로 다시 올립니다.
|
|
|
|
```bash
|
|
./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에만 보관되므로 새로고침하면 사라집니다.
|
|
|
|
```bash
|
|
./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`을 반환합니다.
|