Keycloak 아키텍처 이해

1️⃣ Keycloak 전체 컴포넌트 구조

1. Keycloak 구성 요소 개요

Keycloak은 인증/인가를 처리하기 위한 모듈화된 구조를 갖고 있으며, 다음과 같은 주요 컴포넌트들로 구성됩니다:

• Keycloak Server: 인증 요청을 처리하는 핵심 엔진
• Admin Console: 관리자가 사용자, Realm, Client 등을 설정할 수 있는 웹 UI
• Account Console: 일반 사용자가 자신의 계정 정보를 조회/수정할 수 있는 UI
• Database: 사용자, 세션, 설정 등 모든 데이터를 저장
• Identity Provider (IdP): 외부 인증 연동 (Google, GitHub, LDAP 등)
• Client: Keycloak에 연결되는 애플리케이션 (예: 웹앱, API)

2. Keycloak 아키텍처 다이어그램

출처: Keycloak 공식 문서

3. 주요 컴포넌트 설명

2️⃣ SPI (Service Provider Interface)와 확장성 구조

1. SPI란?

**SPI (Service Provider Interface)**는 Keycloak 내부의 플러그인 구조로, 기능을 커스터마이징하거나 확장할 수 있게 합니다.

• Java 기반으로 구현
• 다양한 영역에서 커스터마이징 가능:
  • 인증
  • 사용자 저장소
  • 이메일 발송
  • 토큰 발급 로직

2. 주요 SPI 예시

3. 확장 구조 다이어그램

 ┌───────────────────┐
 │ Keycloak Core     │
 └────────┬──────────┘
          │
 ┌────────▼────────────┐
 │  SPI 인터페이스      │
 └────────┬────────────┘
          │
  ┌───────▼────────┐     ┌─────────────┐
  │ 사용자 구현 SPI │ ◄──▶│ 사용자 저장소 │
  └────────────────┘     └─────────────┘

3️⃣ 내부 워크플로우 (Login Flow, Token Flow)

1. 로그인 흐름 (Login Flow)

[1] 사용자가 서비스 접속
[2] Keycloak으로 리디렉션
[3] 로그인 (ID/PW or OTP 등)
[4] 인증 성공 → Token 발급
[5] 클라이언트가 토큰으로 서비스 호출

🖼️ Login Flow 다이어그램

사용자 → 클라이언트 → Keycloak Login UI → Keycloak 인증 처리
         ↑                                      ↓
        Redirect <--- Token (Access, ID) <-----

2. 토큰 흐름 (Token Flow)

Keycloak은 인증 성공 시 다음 토큰을 발급합니다:

• Access Token: API 접근 허용 (short-lived)
• ID Token: 사용자 정보 포함 (OIDC에서 사용)
• Refresh Token: 새로운 Access Token 발급에 사용 (long-lived)

{
  "access_token": "eyJhbGciOiJSUzI1NiIsInR...",
  "refresh_token": "eyJhbGciOiJSUzI1NiIsImN...",
  "id_token": "eyJhbGciOiJSUzI1NiIsInR5..."
}

3. 토큰 처리 흐름 요약

[Client] → Keycloak: 로그인
→ 토큰 발급
→ API 호출 시 Access Token 포함
→ Access Token 만료 시 Refresh Token으로 갱신

4️⃣ Keycloak과 데이터베이스

1. Keycloak의 저장소 역할

Keycloak은 모든 설정과 사용자의 상태를 **관계형 DB(RDB)**에 저장합니다.

2. 지원하는 DB

• PostgreSQL ✅ (권장)
• MariaDB / MySQL
• Oracle DB
• Microsoft SQL Server
• H2 (테스트용)

3. DB 연결 설정 예시

bin/kc.sh start \
  --db=postgres \
  --db-url-host=localhost \
  --db-username=keycloak \
  --db-password=secret \
  --db-url-database=keycloak

5️⃣ 관리 인터페이스 (Admin Console, Account Console)

1. Admin Console

• 관리자 전용 UI
• 웹 기반으로 모든 설정 가능 (Realm, Client, User 등)
• 주소: http://localhost:8080/admin/

2. Account Console

• 일반 사용자가 자신의 계정을 관리할 수 있는 UI
• 비밀번호 변경, 2차 인증 설정 등 가능
• 주소: http://localhost:8080/realms/{realm-name}/account