차세대 디지털 아이덴티티와 SSO, 그리고 Keycloak 실무 완벽 가이드

Keycloak Instance
  └── Realm (논리적 격리 단위, 테넌트)
        ├── Clients (인증을 요청하는 어플리케이션)
        ├── Users (사용자)
        ├── Groups (사용자 그룹)
        ├── Roles (Realm Roles + Client Roles)
        ├── Identity Providers (외부 IdP 연동)
        ├── Authentication Flows (인증 흐름 정의)
        └── Authorization Services (세밀한 인가 정책)

docker run --name keycloak -p 8080:8080 \
  -e KC_BOOTSTRAP_ADMIN_USERNAME=admin \
  -e KC_BOOTSTRAP_ADMIN_PASSWORD=change_me \
  quay.io/keycloak/keycloak:latest \
  start-dev

docker run --name keycloak -p 8443:8443 -p 9000:9000 -m 2g \
  -e KC_BOOTSTRAP_ADMIN_USERNAME=admin \
  -e KC_BOOTSTRAP_ADMIN_PASSWORD=change_me \
  quay.io/keycloak/keycloak:latest start \
  --hostname=https://auth.example.com \
  --https-certificate-file=/opt/keycloak/conf/cert.pem \
  --https-certificate-key-file=/opt/keycloak/conf/key.pem \
  --db=postgres \
  --db-url=jdbc:postgresql://db-host:5432/keycloak \
  --db-username=keycloak \
  --db-password=change_me \
  --health-enabled=true \
  --metrics-enabled=true

# CRD 및 Operator 설치
kubectl apply -f https://raw.githubusercontent.com/keycloak/keycloak-k8s-resources/26.5.4/kubernetes/keycloaks.k8s.keycloak.org-v1.yml
kubectl apply -f https://raw.githubusercontent.com/keycloak/keycloak-k8s-resources/26.5.4/kubernetes/keycloakrealmimports.k8s.keycloak.org-v1.yml
kubectl create namespace keycloak
kubectl -n keycloak apply -f https://raw.githubusercontent.com/keycloak/keycloak-k8s-resources/26.5.4/kubernetes/kubernetes.yml

apiVersion: k8s.keycloak.org/v2alpha1
kind: Keycloak
metadata:
  name: production-kc
  namespace: keycloak
spec:
  instances: 3
  db:
    vendor: postgres
    host: postgres-db
    usernameSecret:
      name: keycloak-db-secret
      key: username
    passwordSecret:
      name: keycloak-db-secret
      key: password
  http:
    tlsSecret: keycloak-tls-secret
  hostname:
    hostname: auth.example.com
  proxy:
    headers: xforwarded

# Hostname
hostname=https://auth.example.com
hostname-admin=https://admin.auth.example.com

# Database
db=postgres
db-url=jdbc:postgresql://db:5432/keycloak
db-username=keycloak
db-password=${vault.db-password}
db-pool-max-size=100

# TLS
http-enabled=false
https-port=8443
https-certificate-file=/etc/certs/tls.crt
https-certificate-key-file=/etc/certs/tls.key

# Proxy
proxy-headers=xforwarded

# Cache / Clustering
cache=ispn

# Health & Metrics (port 9000)
health-enabled=true
metrics-enabled=true

# Logging
log=console,file
log-console-output=json

GET /realms/{realm}/.well-known/openid-configuration

GET /realms/myrealm/protocol/openid-connect/auth?
  response_type=code&
  client_id=my-app&
  redirect_uri=https://myapp.example.com/callback&
  scope=openid profile email&
  state=random-state-value&
  code_challenge=BASE64URL(SHA256(code_verifier))&
  code_challenge_method=S256

curl -X POST \
  https://auth.example.com/realms/myrealm/protocol/openid-connect/token \
  -d "grant_type=authorization_code" \
  -d "code=AUTHORIZATION_CODE" \
  -d "redirect_uri=https://myapp.example.com/callback" \
  -d "client_id=my-app" \
  -d "client_secret=my-secret" \
  -d "code_verifier=ORIGINAL_CODE_VERIFIER"

curl -X POST \
  https://auth.example.com/realms/myrealm/protocol/openid-connect/token \
  -d "grant_type=client_credentials" \
  -d "client_id=my-service" \
  -d "client_secret=my-service-secret" \
  -d "scope=openid"

# RPT(Requesting Party Token) 요청으로 권한 확인
curl -X POST \
  https://auth.example.com/realms/myrealm/protocol/openid-connect/token \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -d "grant_type=urn:ietf:params:oauth:grant-type:uma-ticket" \
  -d "audience=my-resource-server"

spring:
  security:
    oauth2:
      resourceserver:
        jwt:
          issuer-uri: https://auth.example.com/realms/myrealm
          jwk-set-uri: https://auth.example.com/realms/myrealm/protocol/openid-connect/certs

@Configuration
@EnableMethodSecurity
public class SecurityConfig {

    @Bean
    public SecurityFilterChain securityFilterChain(HttpSecurity http) throws Exception {
        http
            .authorizeHttpRequests(auth -> auth
                .requestMatchers("/api/public/**").permitAll()
                .requestMatchers("/api/admin/**").hasRole("ADMIN")
                .anyRequest().authenticated()
            )
            .oauth2ResourceServer(oauth2 -> oauth2
                .jwt(jwt -> jwt
                    .jwtAuthenticationConverter(jwtAuthenticationConverter())
                )
            );
        return http.build();
    }

    private JwtAuthenticationConverter jwtAuthenticationConverter() {
        JwtGrantedAuthoritiesConverter converter = new JwtGrantedAuthoritiesConverter();
        converter.setAuthoritiesClaimName("realm_access.roles");
        converter.setAuthorityPrefix("ROLE_");
        JwtAuthenticationConverter jwtConverter = new JwtAuthenticationConverter();
        jwtConverter.setJwtGrantedAuthoritiesConverter(converter);
        return jwtConverter;
    }
}

AUTH_KEYCLOAK_ID=my-nextjs-app
AUTH_KEYCLOAK_SECRET=my-client-secret
AUTH_KEYCLOAK_ISSUER=https://auth.example.com/realms/myrealm

import NextAuth from 'next-auth'
import Keycloak from 'next-auth/providers/keycloak'

export const { handlers, auth, signIn, signOut } = NextAuth({
  providers: [Keycloak],
})

https://myapp.example.com/api/auth/callback/keycloak

import Keycloak from 'keycloak-js'

const keycloak = new Keycloak({
  url: 'https://auth.example.com',
  realm: 'myrealm',
  clientId: 'my-spa',
})

// Authorization Code Flow + PKCE로 초기화
const authenticated = await keycloak.init({
  onLoad: 'login-required',
  pkceMethod: 'S256',
  checkLoginIframe: false,
})

// API 호출 시 토큰 사용
const response = await fetch('/api/data', {
  headers: {
    Authorization: `Bearer ${keycloak.token}`,
  },
})

// 토큰 만료 전 자동 갱신
keycloak.onTokenExpired = () => {
  keycloak.updateToken(30).catch(() => keycloak.login())
}

// 역할 확인
keycloak.hasRealmRole('admin')
keycloak.hasResourceRole('editor', 'my-resource-server')

const express = require('express')
const session = require('express-session')
const Keycloak = require('keycloak-connect')

const app = express()
const memoryStore = new session.MemoryStore()

app.use(
  session({
    secret: 'my-secret',
    resave: false,
    saveUninitialized: true,
    store: memoryStore,
  })
)

const keycloak = new Keycloak(
  { store: memoryStore },
  {
    realm: 'myrealm',
    'auth-server-url': 'https://auth.example.com/',
    resource: 'my-node-app',
  }
)

app.use(keycloak.middleware())

// 인증 필수 엔드포인트
app.get('/api/protected', keycloak.protect(), (req, res) => {
  res.json({ message: 'Authenticated!' })
})

// 특정 역할 필수
app.get('/api/admin', keycloak.protect('realm:admin'), (req, res) => {
  res.json({ message: 'Admin access granted' })
})

app.listen(3000)

[Client] → [API Gateway] → [Keycloak] (토큰 획득/검증)
                ↓
         Authorization: Bearer <JWT>
                ↓
    [Service A] → [Service B] → [Service C]

# 패스워드 방식
ACCESS_TOKEN=$(curl -s -X POST \
  "https://auth.example.com/realms/master/protocol/openid-connect/token" \
  -d "grant_type=password" \
  -d "client_id=admin-cli" \
  -d "username=admin" \
  -d "password=admin-password" | jq -r '.access_token')

# Service Account 방식 (자동화 권장)
ACCESS_TOKEN=$(curl -s -X POST \
  "https://auth.example.com/realms/master/protocol/openid-connect/token" \
  -d "grant_type=client_credentials" \
  -d "client_id=my-admin-client" \
  -d "client_secret=my-admin-secret" | jq -r '.access_token')

# 사용자 생성
curl -X POST \
  "https://auth.example.com/admin/realms/myrealm/users" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "username": "newuser",
    "email": "newuser@example.com",
    "enabled": true,
    "credentials": [{
      "type": "password",
      "value": "temp-password",
      "temporary": true
    }]
  }'

# 사용자 검색
curl -X GET \
  "https://auth.example.com/admin/realms/myrealm/users?username=johndoe" \
  -H "Authorization: Bearer $ACCESS_TOKEN"

# 역할 할당
curl -X POST \
  "https://auth.example.com/admin/realms/myrealm/users/{user-id}/role-mappings/realm" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '[{"id": "ROLE_ID", "name": "admin"}]'

                    ┌─────────────┐
                    │ Load Balancer│
                    └──────┬──────┘
              ┌────────────┼────────────┐
              ▼            ▼            ▼
        ┌──────────┐ ┌──────────┐ ┌──────────┐
        │Keycloak 1│ │Keycloak 2│ │Keycloak 3│
        └────┬─────┘ └────┬─────┘ └────┬─────┘
             │  Infinispan  │  (세션 동기화) │
             └──────────────┴───────────────┘
                         │
                  ┌──────┴──────┐
                  │ PostgreSQL  │
                  │  (공유 DB)  │
                  └─────────────┘

spec:
  containers:
    - name: keycloak
      livenessProbe:
        httpGet:
          path: /health/live
          port: 9000
        initialDelaySeconds: 30
        periodSeconds: 10
      readinessProbe:
        httpGet:
          path: /health/ready
          port: 9000
        initialDelaySeconds: 30
        periodSeconds: 10
      startupProbe:
        httpGet:
          path: /health/started
          port: 9000
        failureThreshold: 30
        periodSeconds: 5

cache=ispn
cache-remote-host=infinispan.example.com
cache-remote-port=11222
cache-remote-username=keycloak
cache-remote-password=change_me
cache-remote-tls-enabled=true

# prometheus.yml
scrape_configs:
  - job_name: 'keycloak'
    metrics_path: '/metrics'
    scheme: https
    static_configs:
      - targets: ['keycloak-host:9000']

bin/kc.sh start \
  --metrics-enabled=true \
  --event-metrics-user-enabled=true \
  --event-metrics-user-tags=realm,client,idp \
  --event-metrics-user-events=LOGIN,LOGIN_ERROR,LOGOUT,TOKEN_REFRESH