1. システム要件

Keycloak 26.xをインストールする前に、システムが次の要件を満たしていることを確認してください。

• ジャワ：JDK 17または21（OpenJDK 21推奨）

• データベース: PostgreSQL 13-16 (推奨)、MySQL 8.0 以降、MariaDB 10.6 以降

• ラム: 最小 512MB (本番環境には 2GB 以上を推奨)

• CPU: 最小 1 コア (本番環境では 2 コア以上を推奨)

• OS：Linux（Ubuntu 22.04/24.04、CentOS 9、RHEL 9）、macOS、Windows

2. ベアメタル (Ubuntu) にインストールする

2.1. Java 21 をインストールする

sudo apt update
sudo apt install -y openjdk-21-jdk
java -version

2.2. PostgreSQLのインストール

sudo apt install -y postgresql postgresql-contrib
sudo systemctl enable postgresql
sudo systemctl start postgresql
Tạo database và user cho Keycloak
sudo -u postgres psql -c "CREATE USER keycloak WITH PASSWORD 'keycloak_password';"
sudo -u postgres psql -c "CREATE DATABASE keycloak OWNER keycloak;"

2.3. Keycloakをダウンロードしてインストールします

# Tải Keycloak 26.5.x
cd /opt
wget https://github.com/keycloak/keycloak/releases/download/26.5.6/keycloak-26.5.6.tar.gz
tar -xzf keycloak-26.5.6.tar.gz
ln -s keycloak-26.5.6 keycloak
Cấu hình database
cat > /opt/keycloak/conf/keycloak.conf << 'EOF'
Database
db=postgres
db-url-host=localhost
db-url-port=5432
db-url-database=keycloak
db-username=keycloak
db-password=keycloak_password
Hostname
hostname=keycloak.example.com
HTTP
http-enabled=true
http-port=8080
EOF
Chạy development mode
/opt/keycloak/bin/kc.sh start-dev

2.4.管理者ユーザーの作成

# Tạo admin user khi start
KEYCLOAK_ADMIN=admin KEYCLOAK_ADMIN_PASSWORD=admin \
  /opt/keycloak/bin/kc.sh start-dev
Hoặc dùng lệnh bootstrap
/opt/keycloak/bin/kc.sh bootstrap-admin user 

--username admin --password admin

3. Docker と Docker Compose を使用してインストールする

3.1.シンプルな Docker (開発)

docker run -d --name keycloak \
  -p 8080:8080 \
  -e KEYCLOAK_ADMIN=admin \
  -e KEYCLOAK_ADMIN_PASSWORD=admin \
  quay.io/keycloak/keycloak:26.5.6 \
  start-dev

3.2. Docker Compose (実稼働対応)

# docker-compose.yml
services:
  postgres:
    image: postgres:16-alpine
    environment:
      POSTGRES_DB: keycloak
      POSTGRES_USER: keycloak
      POSTGRES_PASSWORD: keycloak_password
    volumes:
      - postgres_data:/var/lib/postgresql/data
    networks:
      - keycloak-network
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U keycloak"]
      interval: 10s
      timeout: 5s
      retries: 5
keycloak:
image: quay.io/keycloak/keycloak:26.5.6
command: start
environment:
KC_DB: postgres
KC_DB_URL_HOST: postgres
KC_DB_URL_PORT: "5432"
KC_DB_URL_DATABASE: keycloak
KC_DB_USERNAME: keycloak
KC_DB_PASSWORD: keycloak_password
KC_HOSTNAME: keycloak.example.com
KC_PROXY_HEADERS: xforwarded
KC_HTTP_ENABLED: "true"
KEYCLOAK_ADMIN: admin
KEYCLOAK_ADMIN_PASSWORD: admin
ports:
- "8080:8080"
depends_on:
postgres:
condition: service_healthy
networks:
- keycloak-network
volumes:
postgres_data:
networks:
keycloak-network:

4. Kubernetes オペレーターのデプロイメント

4.1. Keycloakオペレーターをインストールする

# Cài đặt Operator qua OperatorHub hoặc manifests
kubectl apply -f https://raw.githubusercontent.com/keycloak/keycloak-k8s-resources/26.5.6/kubernetes/keycloaks.k8s.keycloak.org-v1.yml
kubectl apply -f https://raw.githubusercontent.com/keycloak/keycloak-k8s-resources/26.5.6/kubernetes/keycloakrealmimports.k8s.keycloak.org-v1.yml
kubectl apply -f https://raw.githubusercontent.com/keycloak/keycloak-k8s-resources/26.5.6/kubernetes/kubernetes.yml

4.2. Keycloakカスタムリソース

apiVersion: k8s.keycloak.org/v2alpha1
kind: Keycloak
metadata:
  name: keycloak
spec:
  instances: 2
  db:
    vendor: postgres
    host: postgres-service
    usernameSecret:
      name: keycloak-db-secret
      key: username
    passwordSecret:
      name: keycloak-db-secret
      key: password
  hostname:
    hostname: keycloak.example.com
  http:
    httpEnabled: true
  proxy:
    headers: xforwarded
  truststores:
    my-truststore:
      secret:
        name: my-truststore-secret

5. 開発モードと本番モード

基準	開発 (開始-開発)	生産（開始）
データベース	H2 埋め込み (デフォルト)	PostgreSQL/MySQL (必須)
HTTPS	オプション	必須 (または代理)
ホスト名	ローカルホスト (自動)	ホスト名を設定する必要があります
キャッシュ	ローカルキャッシュ	分散キャッシュ (Infinispan)
テーマキャッシュ	無効 (ホットリロード)	有効
建てる	最初に構築する必要はありません	最初に kc.sh ビルドを実行する必要があります

6. HTTPS/TLS の構成

# Tạo keystore với self-signed certificate
keytool -genkeypair -storepass password -storetype PKCS12 \
  -keyalg RSA -keysize 2048 -dname "CN=keycloak.example.com" \
  -alias server -ext "SAN:c=DNS:keycloak.example.com" \
  -keystore /opt/keycloak/conf/server.keystore
Cấu hình trong keycloak.conf
https-certificate-file=/path/to/cert.pem
https-certificate-key-file=/path/to/key.pem
Hoặc
https-key-store-file=/opt/keycloak/conf/server.keystore
https-key-store-password=password

7. リバースプロキシの構成 (Nginx)

upstream keycloak {
    server 127.0.0.1:8080;
}
server {
listen 443 ssl http2;
server_name keycloak.example.com;
ssl_certificate /etc/nginx/ssl/cert.pem;
ssl_certificate_key /etc/nginx/ssl/key.pem;

location / {
    proxy_pass http://keycloak;
    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;
    proxy_set_header X-Forwarded-Host $host;
    proxy_set_header X-Forwarded-Port $server_port;
    proxy_buffer_size 128k;
    proxy_buffers 4 256k;
    proxy_busy_buffers_size 256k;
}

}

8. Systemd サービスの作成

# /etc/systemd/system/keycloak.service
[Unit]
Description=Keycloak Server
After=network.target postgresql.service
[Service]
Type=exec
User=keycloak
Group=keycloak
ExecStart=/opt/keycloak/bin/kc.sh start --optimized
ExecStop=/bin/kill -TERM $MAINPID
Restart=on-failure
RestartSec=10
LimitNOFILE=65536
[Install]
WantedBy=multi-user.target

sudo systemctl daemon-reload
sudo systemctl enable keycloak
sudo systemctl start keycloak