Devops
Keycloak
Keycloak 설치 및 구성

Keycloak 설치 및 구성

1️⃣ Standalone 모드 설치

1. 기본 설치 환경

Keycloak은 Java 기반이며, 기본적으로 Standalone 모드로 동작할 수 있습니다. 개발, 테스트, POC 환경에서는 가장 빠르고 간단한 방식입니다.

  • 운영체제: Linux, macOS, Windows
  • 요구사항: JDK 17+, Docker(optional)

2. Docker를 활용한 설치 (가장 간단) 

docker run -d \
  --name keycloak \
  -p 8080:8080 \
  -e KEYCLOAK_ADMIN=admin \
  -e KEYCLOAK_ADMIN_PASSWORD=admin \
  quay.io/keycloak/keycloak:24.0.1 \
  start-dev
  • 접속 주소: http://localhost:8080
  • 관리자 ID: admin / 비밀번호: admin

🖼️ 설치 플로우:

[사용자]
   ↓
[Keycloak (Docker)]
   └── 포트 8080 노출
       └── Admin Console + Account Console 사용 가능

3. 바이너리 설치 (JAR 파일) 

wget https://github.com/keycloak/keycloak/releases/download/24.0.1/keycloak-24.0.1.tar.gz
tar -xvf keycloak-24.0.1.tar.gz
cd keycloak-24.0.1/bin

./kc.sh start-dev \
  --http-port=8080 \
  --hostname=localhost \
  --hostname-strict=false \
  --hostname-strict-https=false \
  --admin=admin \
  --admin-password=admin

2️⃣ Kubernetes 환경에서 Helm 차트를 이용한 설치

1. Helm 차트 설치 준비

Keycloak은 Bitnami Helm Chart를 통해 Kubernetes에 쉽게 배포할 수 있습니다.

helm repo add bitnami https://charts.bitnami.com/bitnami
helm repo update

2. 설치 명령어 

helm install keycloak bitnami/keycloak \
  --set auth.adminUser=admin \
  --set auth.adminPassword=adminpassword \
  --set service.type=ClusterIP

👉 설치 후 접근:

  • Admin Console: http://<CLUSTER_IP>:8080
  • 기본 로그인: admin / adminpassword

3. 설치 구조 예시 (Kubernetes 내) 

+--------------------+
|  Ingress (TLS)     |
+--------------------+
          ↓
+--------------------+
|  Keycloak Service  |
+--------------------+
          ↓
+--------------------+
|  Keycloak Pod      |
+--------------------+
          ↓
+--------------------+
|  PostgreSQL Pod     |
+--------------------+

3️⃣ 외부 DB(MySQL, PostgreSQL) 연동

1. PostgreSQL 연동 예시 (가장 권장) 

./kc.sh start \
  --db=postgres \
  --db-username=keycloak \
  --db-password=secret123 \
  --db-url-host=postgres.local \
  --db-url-database=keycloak

🗃️ PostgreSQL 컨테이너 예시:

docker run -d \
  --name postgres \
  -e POSTGRES_USER=keycloak \
  -e POSTGRES_PASSWORD=secret123 \
  -e POSTGRES_DB=keycloak \
  -p 5432:5432 \
  postgres:15

2. MySQL 연동 예시 

./kc.sh start \
  --db=mysql \
  --db-url-host=mysql.local \
  --db-url-database=keycloak \
  --db-username=root \
  --db-password=secret

⚠️ 운영 환경에서는 PostgreSQL을 사용하는 것이 권장됩니다.

4️⃣ TLS 및 프록시 구성

1. TLS 종료 구조

Keycloak은 자체 TLS 설정도 가능하지만 일반적으로 **Reverse Proxy (Nginx, Traefik 등)**를 앞단에 배치합니다.

[ 사용자 ]
     ↓
[ Reverse Proxy (TLS 종료) ]
     ↓
[ Keycloak HTTP (8080) ]

2. 예시: Nginx 리버스 프록시 + TLS 

server {
    listen 443 ssl;
    server_name keycloak.example.com;

    ssl_certificate     /etc/ssl/keycloak.crt;
    ssl_certificate_key /etc/ssl/keycloak.key;

    location / {
        proxy_pass         http://localhost:8080;
        proxy_set_header   Host $host;
        proxy_set_header   X-Real-IP $remote_addr;
        proxy_set_header   X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header   X-Forwarded-Proto $scheme;
    }
}

Keycloak 설정에서 --hostname, --proxy 설정도 함께 지정해 줘야 합니다.

3. Keycloak 프록시 모드 설정 

./kc.sh start \
  --hostname=keycloak.example.com \
  --proxy=edge \
  --https-port=8443

5️⃣ Initial Admin 계정 설정

1. CLI 옵션을 통한 설정 (start-dev 모드) 

./kc.sh start-dev \
  --admin=admin \
  --admin-password=admin123

2. 환경 변수로 설정 (Docker) 

-e KEYCLOAK_ADMIN=admin \
-e KEYCLOAK_ADMIN_PASSWORD=admin123

3. Helm 설치 시 값 설정 

--set auth.adminUser=admin \
--set auth.adminPassword=adminpassword

🧠 정리 요약

환경 설치 방식 DB 연동 TLS 구성 관리자 계정 설정
Standalone JAR or Docker PostgreSQL/MySQL Nginx/Traefik CLI 옵션 or env
Kubernetes Helm 외부 DB 가능 Ingress TLS Helm values 설정
RSS Feed
마지막 수정일자
Keycloak 아키텍처 이해Realm, Client, Role, User 구조