Contents
Keycloak 26.x のインストールと初期設定
Keycloak 26 系は OpenJDK 21 以上が必須で、公式サイトからダウンロードすれば数分で管理コンソールにアクセスできます。本章では Windows と Linux の両環境 に対応した展開手順を示し、実運用で欠かせない TLS 設定・リバースプロキシ構成・外部シークレット管理ツール連携までを包括的に解説します。
必要要件
Keycloak を本番稼働させるための最低条件です。以下は OS に依存しない共通項となります（Windows の場合は「PowerShell」または「cmd.exe」を使用してください）。
- Java ランタイム：OpenJDK 21 もしくは互換性のある JDK 21
- OS：Linux (CentOS、Ubuntu 等) または Windows 10/11／Server 2019 以上
- メモリ：最低 2 GB（推奨 4 GB 以上）
- ポート：HTTP 8080, HTTPS 8443（リバースプロキシ利用時は 80/443）
重要ポイント
- JDK のバージョンが 21 未満だと「Unsupported Java version」エラーが必ず発生します。
- Windows 環境ではJAVA_HOMEが正しく設定されていることを必ず確認してください。
Windows 環境での展開手順
Windows でも Linux と同様に手動インストールと Docker のいずれかが選択できます。ここでは 手動インストール に焦点を当てます。
- JDK のインストール
powershell
# Chocolatey がインストールされている前提
choco install openjdk21 -y
$env:JAVA_HOME = "C:\Program Files\OpenJDK\openjdk-21" - Keycloak の取得と展開
powershell
Invoke-WebRequest -Uri https://github.com/keycloak/keycloak/releases/download/26.0.1/keycloak-26.0.1.zip -OutFile keycloak.zip
Expand-Archive .\keycloak.zip -DestinationPath C:\opt\keycloak
Set-Location C:\opt\keycloak\keycloak-26.0.1 - 管理者アカウントの事前設定（PowerShell）
powershell
$env:KC_BOOTSTRAP_ADMIN_USERNAME = "admin"
$env:KC_BOOTSTRAP_ADMIN_PASSWORD = "StrongPassword123!" - 開発モードで起動（テスト用）
⚠️ 注意：
start-devはデータベースをインメモリ H2 にし、TLS が無効になるため本番環境では使用しないでください。
powershell
.\bin\kc.bat start-dev
5. HTTPS 本番起動オプション（Windows でも同様に利用可能）
powershell
# 例: PKCS12 キーストアを作成
keytool -genkeypair -alias keycloak \
-keyalg RSA -keysize 2048 -storetype PKCS12 \
-keystore keystore.p12 -validity 3650
-dname "CN=keycloak.example.com, OU=IT, O=Example Corp, L=Tokyo, S=Tokyo, C=JP"
-storepass ChangeItNow
.\bin\kc.bat start --https-key-store-file=keystore.p12 --https-key-store-password=ChangeItNow
TLS 設定と HTTPS 本番起動
TLS を有効化することで通信路の暗号化が保証されます。Keycloak の組み込みサーバーで直接終端させる場合と、リバースプロキシ側で終端させる場合の両方を示します。
キーストア作成（OpenSSL + keytool）
|
1 2 3 4 5 6 7 8 |
# OpenSSL で自己署名証明書を生成 openssl req -newkey rsa:2048 -nodes -keyout tls.key -x509 -days 365 -out tls.crt \ -subj "/C=JP/ST=Tokyo/L=Tokyo/O=Example Corp/OU=IT/CN=sso.example.com" # PKCS12 キーストアに変換 openssl pkcs12 -export -in tls.crt -inkey tls.key -name keycloak \ -out keystore.p12 -password pass:ChangeItNow |
Keycloak 起動オプション（Linux / Windows 共通）
|
1 2 3 4 5 6 |
./bin/kc.sh start \ --https-key-store-file=keystore.p12 \ --https-key-store-password=ChangeItNow \ --hostname=https://sso.example.com \ --http-enabled=false |
ポイント
---hostnameで外部からアクセスする URL を明示すると、メールやリンクに正しいホストが自動挿入されます。
- 本番環境では必ず--http-enabled=falseとし、HTTP はリバースプロキシ側でリダイレクトさせてください。
リバースプロキシ構成例（NGINX / Traefik）
Keycloak の推奨デプロイパターンは「TLS 終端はリバースプロキシに任せ、Keycloak は HTTP のみで動作」することです。以下に代表的な設定を掲載します。
NGINX（Docker Compose 例）
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 |
version: "3.8" services: keycloak: image: quay.io/keycloak/keycloak:26.0.1 command: start --http-enabled=true --proxy=edge environment: KC_BOOTSTRAP_ADMIN_USERNAME: admin KC_BOOTSTRAP_ADMIN_PASSWORD: StrongPassword123! ports: - "8080:8080" nginx: image: nginx:stable-alpine depends_on: - keycloak volumes: - ./nginx.conf:/etc/nginx/conf.d/default.conf:ro ports: - "443:443" # nginx.conf server { listen 443 ssl; server_name sso.example.com; ssl_certificate /etc/ssl/certs/fullchain.pem; ssl_certificate_key /etc/ssl/private/privkey.pem; location / { proxy_pass http://keycloak:8080; proxy_set_header Host $host; proxy_set_header X-Forwarded-Proto https; proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; } } |
Traefik（Docker Compose 例）
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 |
services: keycloak: image: quay.io/keycloak/keycloak:26.0.1 command: start --http-enabled=true --proxy=edge environment: KC_BOOTSTRAP_ADMIN_USERNAME: admin KC_BOOTSTRAP_ADMIN_PASSWORD: StrongPassword123! labels: - "traefik.enable=true" - "traefik.http.routers.keycloak.rule=Host(`sso.example.com`)" - "traefik.http.routers.keycloak.entrypoints=websecure" - "traefik.http.services.keycloak.loadbalancer.server.port=8080" traefik: image: traefik:v2.11 command: - "--api.insecure=true" - "--providers.docker=true" - "--entryPoints.websecure.address=:443" - "--certificatesResolvers.myresolver.acme.tlsChallenge=true" |
ポイント
---proxy=edgeを付与すると、Keycloak はヘッダーから元のプロトコル（HTTPS）を正しく認識します。
- リバースプロキシ側で HSTS (Strict-Transport-Security) と HTTP/2 の有効化を推奨します。
外部シークレット管理ツールとの連携例
Keycloak に保存されるクライアントシークレットやデータベース接続情報は、Vault / AWS Secrets Manager / Google Secret Manager などの外部シークレットストアに委任すると安全性が向上します。ここでは HashiCorp Vault と AWS Secrets Manager の具体的手順を示します。
1. HashiCorp Vault からシークレット取得（Linux/PowerShell 共通）
|
1 2 3 4 5 6 7 |
# Vault CLI がインストール済みであること前提 export VAULT_ADDR=https://vault.example.com export VAULT_TOKEN=$(cat /path/to/token) # secret/keycloak に {client-secret: "xxxx"} が格納されていると仮定 CLIENT_SECRET=$(vault kv get -field=client-secret secret/keycloak) |
|
1 2 3 4 5 |
$Env:VAULT_ADDR = "https://vault.example.com" $Env:VAULT_TOKEN = Get-Content C:\secrets\vault-token.txt $ClientSecret = vault kv get -field=client-secret secret/keycloak |
取得したシークレットは Keycloak の管理 API で自動更新できます。
|
1 2 3 4 5 |
curl -X PUT "http://localhost:8080/admin/realms/corp-realm/clients/<client-id>" \ -H "Content-Type: application/json" \ -H "Authorization: Bearer $ADMIN_TOKEN" \ -d "{\"secret\":\"$CLIENT_SECRET\"}" |
2. AWS Secrets Manager を利用する場合（CLI）
|
1 2 3 4 5 6 7 |
aws secretsmanager get-secret-value \ --region ap-northeast-1 \ --secret-id keycloak/client-secret \ --query SecretString --output text > secret.json CLIENT_SECRET=$(jq -r .clientSecret secret.json) |
取得した CLIENT_SECRET を同様に管理 API に POST すれば、シークレットが自動的に更新されます。
重要ポイント
- シークレットは 起動時に環境変数で渡す 方法（例:KC_DB_PASSWORD）でも利用可能です。
- 定期的なローテーションをスケジュールし、Keycloak のクライアントシークレットも同時に更新するスクリプトを CI/CD に組み込むとベストプラクティスが完成します。
新規レルムの作成と基本設定
実運用では「マスターレルム」から独立したレルムを作成し、プロジェクトや部門ごとの認証ポリシーを分離します。本節では GUI 操作だけでなく、REST API を使った自動化例も示します。
1. 管理コンソールでの手順（GUI）
- Realm Settings → Add Realm をクリック
- 「Realm 名」
corp-realmと「表示名」社内ポータルを入力し Create
※ GUI 操作は初回だけに留め、以降は API で自動化するとミスが減ります。
2. REST API によるレルム作成（cURL 例）
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 |
# 管理者トークン取得 ADMIN_TOKEN=$(curl -s "http://localhost:8080/realms/master/protocol/openid-connect/token" \ -d "grant_type=password" -d "client_id=admin-cli" \ -d "username=admin" -d "password=StrongPassword123!" | jq -r .access_token) # レルム作成 JSON cat > realm.json <<EOF { "realm": "corp-realm", "enabled": true, "displayName": "社内ポータル" } EOF curl -X POST "http://localhost:8080/admin/realms" \ -H "Authorization: Bearer $ADMIN_TOKEN" \ -H "Content-Type: application/json" \ -d @realm.json |
3. 推奨パスワードポリシー（表）
| 設定項目 | 推奨値 | 補足 |
|---|---|---|
| パスワード長 | 12文字以上 | NIST SP800‑63B に準拠 |
| 大文字 / 小文字 | 必須 | Uppercase、Lowercase を有効化 |
| 数字・特殊文字 | 必須 | Digits と Special characters |
| パスワード履歴保持 | 5 回分 | 同一パスワードの再利用防止 |
| SMTP サーバ | 社内メールサーバ (smtp.mail.example.com) |
Realm Settings → Email に設定し、テスト送信で確認 |
ポイント：パスワードポリシーは「安全性」と「ユーザー体験」のバランスが重要です。最低でも 12 文字・大文字・数字を必須にすれば、一般的なブルートフォース攻撃から十分保護できます。
クライアント登録とプロトコル選択（OIDC / SAML）
Keycloak の Clients 機能は OIDC と SAML の両方に対応しています。以下ではそれぞれの必須項目と、実運用で推奨する設定例を示します。
1. OIDC クライアント（GUI 手順＋表）
- Clients → Create
- Client ID：
my-app-client - Root URL：
https://app.example.com
OIDC の場合は必ず PKCE を有効化し、アクセストークンの有効期限を短く設定してください。
| 項目 | 推奨設定 |
|---|---|
| Access Type | confidential（サーバ間） または public（SPA） |
| Authorization Flow | standard flow（認可コードフロー） |
| PKCE (Code Challenge Method) | S256（必須） |
| Valid Redirect URIs | https://app.example.com/oauth/callback など |
| アクセストークン有効期限 | 300 秒（5 分） |
| Refresh Token 有効期限 | 30 日 |
2. SAML クライアント（メタデータインポート例）
- Clients → Create → プロトコル
saml、Client IDremotepc-saml - Fine Grain SAML Endpoint Configuration → Import from URL に以下を入力
|
1 2 |
https://sso.remotepc.com/rpcnew/sso/metadata |
インポート後は自動的に
Entity IDとSingleSignOnService URLが設定されます。
3. REST API を使ったクライアント登録（cURL）
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 |
cat > client.json <<EOF { "clientId": "my-app-client", "protocol": "openid-connect", "publicClient": false, "secret": "", "redirectUris": ["https://app.example.com/oauth/callback"], "standardFlowEnabled": true, "pkceCodeChallengeMethod": "S256", "accessTokenLifespan": 300, "refreshTokenMaxReuse": 0 } EOF curl -X POST "http://localhost:8080/admin/realms/corp-realm/clients" \ -H "Authorization: Bearer $ADMIN_TOKEN" \ -H "Content-Type: application/json" \ -d @client.json |
本番運用のベストプラクティス
実サービスで安定稼働させるために、HTTPS 強制・シークレット外部管理・署名アルゴリズム選択 を中心にまとめます。
1. HTTPS の徹底
- リバースプロキシ側で TLS 終端し、Keycloak は
--http-enabled=trueと--proxy=edgeを付与 - HSTS (
Strict-Transport-Security: max-age=31536000; includeSubDomains) を必ず有効化
2. クライアントシークレットの外部管理
| ツール | 保存形式 | 更新方法 | メリット |
|---|---|---|---|
| HashiCorp Vault | KV シークレット | CLI / API による自動ローテーション | 高度なアクセス制御、監査ログ |
| AWS Secrets Manager | JSON | Lambda で定期ローテーション | マネージドサービス、IAM 統合 |
| Google Secret Manager | JSON | Cloud Scheduler + Cloud Function | GCP ネイティブ、暗号化自動 |
ポイント：シークレットは 起動時に環境変数（例:
KC_DB_PASSWORD）で渡すか、管理 API で定期的に上書きするスクリプトを CI/CD に組み込みます。
3. トークン署名アルゴリズムの選択
- デフォルトは RS256（RSA‑SHA256）
- 高機密データを扱う場合は ES384 または PS512 に切り替え、Realm Settings → Keys で新しいキーを生成し、旧キーは段階的に廃止
4. ログとエラーの体系的な把握
|
1 2 3 4 5 6 |
# Keycloak 本体ログ（data/log/kc.log） tail -f data/log/kc.log # HTTP アクセス/エラーログ（data/log/server.log） tail -f data/log/server.log |
| エラーコード | 主な原因 | 推奨対策 |
|---|---|---|
| 400 Bad Request | 未登録の redirect_uri |
正しい URI を Clients → Settings に追加 |
| 401 Unauthorized | トークン期限切れ・シークレット不一致 | 有効期限を延長、またはシークレットを再確認 |
| 403 Forbidden | 必要ロールが付与されていない | Authorization ポリシーでロールを割当 |
| 500 Internal Server Error | DB 接続失敗・設定ファイル不正 | kc.log と server.log を確認し、スタックトレースから原因特定 |
5. 定期的なヘルスチェックとバックアップ
- Health endpoint：
http://localhost:8080/realms/master/protocol/openid-connect/token/introspect（Bearer トークン付与） - データベースは 毎日夜間にスナップショット取得、Keycloak の
exportコマンドで設定バックアップも併用
まとめ：TLS 終端はリバースプロキシ側、シークレットは外部管理ツールに委任し、署名アルゴリズムは要件に応じて強化する。これらを実装すれば、本番環境でも安全かつ安定した SSO 基盤が構築できます。
本稿では Windows と Linux の両方でのインストール手順、TLS／リバースプロキシ設定例、外部シークレット連携方法を網羅的に掲載しました。実際の運用では各組織のポリシーやネットワーク構成に合わせてパラメータを調整し、定期的な監査とバックアップを忘れずに行ってください。