keycloak-administration

KeyCloak 管理

概要

インストール、設定、レルム管理、セキュリティ強化、運用のベストプラクティスを網羅した、体系的な KeyCloak 管理ガイドを提供します。安全でスケーラブルな ID およびアクセス管理（IAM）ソリューション向けに、スタンドアロンとクラスターの両方のデプロイをサポートします。

クイックスタートガイド

タスクを選択し、適切なリファレンスを読み込みます。

1. 新規インストール → 「インストールとセットアップ」に進みます
2. レルムとユーザーの管理 → realm-management.md を読み込みます
3. クライアント設定 → client-configuration.md を読み込みます
4. 認証と SSO → authentication-sso.md を読み込みます
5. 認可と RBAC → authorization-rbac.md を読み込みます
6. ユーザーフェデレーション（LDAP/AD） → user-federation.md を読み込みます
7. セキュリティ強化 → security-hardening.md を読み込みます
8. 高可用性とスケーリング → ha-scalability.md を読み込みます
9. トラブルシューティング → troubleshooting.md を読み込みます
10. 統合例 → integration-examples.md を読み込みます

インストールとセットアップ

デプロイオプション

1. スタンドアロンモード（開発／テスト）

# Download and start KeyCloak
wget https://github.com/keycloak/keycloak/releases/download/[VERSION]/keycloak-[VERSION].tar.gz
tar -xvzf keycloak-[VERSION].tar.gz
cd keycloak-[VERSION]
bin/kc.sh start-dev

# Access: http://localhost:8080
# Create initial admin user on first access

2. データベースを使用した本番モード

# Configure and build
bin/kc.sh build --db=postgres

# Set environment variables
export KC_DB=postgres
export KC_DB_URL=jdbc:postgresql://localhost/keycloak
export KC_DB_USERNAME=keycloak
export KC_DB_PASSWORD=password
export KC_HOSTNAME=keycloak.example.com

# Start production mode
bin/kc.sh start --optimized

3. Docker デプロイ

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

4. Kubernetes - KeyCloak Operator または Helm チャートを使用します

初期設定手順

1. 管理者アカウント：初回アクセス時に、強力なパスワード（12 文字以上）を設定して作成します
2. ホスト名：本番環境では KC_HOSTNAME を設定します
3. SSL/TLS：証明書を設定します（本番環境では必須）
4. データベース：PostgreSQL 接続を設定します
5. メール：通知用に SMTP を設定します

# Email settings
KC_SMTP_HOST=smtp.example.com
KC_SMTP_PORT=587
[email protected]
KC_SMTP_STARTTLS=true

主な概念

レルム

• マスターレルム：管理用レルム（アプリには使用しないでください）
• アプリケーションレルム：アプリや環境ごとに個別のレルムを作成します
• 作成方法：管理コンソール → レルムを作成

ユーザーとグループ

• ユーザー：認証情報を持つ個別のアカウント
• グループ：ユーザーを階層的に整理します
• 属性：カスタムのキーと値のペア
• フェデレーション：LDAP/AD から同期します（user-federation.md を参照）

クライアント

• OIDC クライアント：最新の OAuth 2.0/OIDC アプリケーション
• SAML クライアント：従来型のエンタープライズアプリケーション
• 種類：Confidential（サーバーサイド）または Public（SPA／モバイル）
• 詳細：client-configuration.md を参照

ロールと権限

• レルムロール：すべてのクライアントに適用されるグローバルなロール
• クライアントロール：1 つのクライアントに固有のロール
• 複合ロール：複数のロールを継承します
• 詳細：authorization-rbac.md を参照

一般的なタスク

アプリケーションの SSO を設定する

1. アプリケーション用の OIDC クライアントを作成します

2. リダイレクト URI を設定します（ワイルドカードは使用せず、正確な URL を指定します）

3. クライアントの種類を設定します：

   • Confidential：サーバーサイドアプリ（クライアントシークレットが必要です）
   • Public：SPA／モバイルアプリ（PKCE を使用します）

4. レルムのエンドポイントから 設定を取得します：

   https://keycloak.example.com/realms/{realm}/.well-known/openid-configuration
   

5. アプリと 統合します（integration-examples.md を参照）

多要素認証を有効にする

1. Authentication → Flows
2. Browser フローを複製します
3. OTP または WebAuthn 認証器を追加します
4. Required または Conditional に設定します
5. レルムにバインドします
6. ユーザーは次回のログイン時に MFA を設定します

詳細：authentication-sso.md を参照

LDAP/Active Directory に接続する

1. User Federation → Add LDAP Provider
2. 接続を設定します（URL、バインド DN、認証情報）
3. 検索ベースを設定します：ou=users,dc=example,dc=com
4. 属性用のマッパーを設定します
5. 接続をテストし、ユーザーを同期します

詳細：user-federation.md を参照

本番環境への安全なデプロイ

必須のセキュリティ対策：

• SSL/TLS：本番環境のすべてのトラフィックで必須です
• パスワードポリシー：12 文字以上、複雑さの要件を設定します
• ブルートフォース攻撃対策：ロックアウト機能を有効にします
• トークンの有効期間：アクセストークンを短く設定します（5～15 分）
• 管理者の MFA：すべての管理者アカウントで有効にします
• イベントログ：認証イベントを監視します

チェックリストの全文：security-hardening.mdを参照してください。

高可用性の設定

1. 共有データベース：すべてのノードで PostgreSQL/MySQL を使用します
2. 分散キャッシュ：Infinispan を設定します
3. ロードバランサー：スティッキーセッションを有効にした HAProxy/NGINX を使用します
4. ヘルスチェック：/health/ready と /health/live を使用します
5. 監視：/metrics の Prometheus メトリクスを使用します

詳細：ha-scalability.mdを参照してください。

トラブルシューティングのクイックリファレンス

ユーザーがログインできない

• ユーザーが有効になっているか確認します
• リダイレクト URI が完全に一致しているか確認します
• 必須アクションを確認します
• イベント → ログインイベントを確認します

トークンの検証に失敗する

• レルムの公開鍵を確認します
• トークンの有効期限を確認します
• 発行者 URL を検証します
• オーディエンスクレームを確認します

LDAP 同期の問題

• LDAP 接続をテストします
• バインド認証情報を確認します
• ユーザー DN のパスを確認します
• 手動で同期を実行します

トラブルシューティングガイドの全文：troubleshooting.mdを参照してください。

必須コマンド

# Start modes
bin/kc.sh start-dev                    # Development
bin/kc.sh start --optimized            # Production

# Build for database
bin/kc.sh build --db=postgres

# Export/Import realm
bin/kc.sh export --dir /backup --realm my-realm
bin/kc.sh import --dir /backup

# Admin CLI
bin/kcadm.sh config credentials --server http://localhost:8080 --realm master --user admin
bin/kcadm.sh create realms -s realm=my-realm -s enabled=true
bin/kcadm.sh create users -r my-realm -s username=john -s enabled=true
bin/kcadm.sh set-password -r my-realm --username john --new-password secret

ベストプラクティスのまとめ

アーキテクチャ

• アプリケーション／環境ごとにレルムを分けます
• 構成にはグループを、権限にはロールを使用します
• セキュリティ要件に基づいてトークンの有効期間を計画します
• クラスターでセッションレプリケーションを有効にします

セキュリティ

• 本番環境では必ず SSL/TLS を使用します
• 特権アカウントで MFA を有効にします
• ブルートフォース攻撃対策を実装します
• 定期的にセキュリティ監査を実施します
• 最小権限の原則を適用します

運用

• バックアップを自動化し、復元をテストします
• メトリクスを監視し、アラートを設定します
• 設定を文書化します
• 定期的に更新とパッチ適用を行います
• キャパシティプランニングを実施します

開発

• パブリッククライアントでは PKCE を使用します
• 適切なトークン更新を実装します
• トークンの有効期限切れを適切に処理します
• トークンを正しく検証します
• 適切なグラントタイプを使用します

リファレンスドキュメント

詳しいガイダンスについては、適切なリファレンスファイルを読み込んでください。

• realm-management.md - レルム設定、ユーザー、グループ
• client-configuration.md - OIDC/SAML クライアント、スコープ、マッパー
• authentication-sso.md - 認証フロー、MFA、ソーシャルログイン、IdP
• authorization-rbac.md - ロール、権限、きめ細かな認証
• user-federation.md - LDAP/AD 統合、カスタムプロバイダー
• security-hardening.md - セキュリティポリシー、監視、監査
• ha-scalability.md - クラスタリング、パフォーマンス、バックアップ、DR
• troubleshooting.md - よくある問題、ログ記録、診断
• integration-examples.md - Spring Boot、Node.js、React、Python、Docker、K8s

その他のリソース

• 公式ドキュメント：https://www.keycloak.org/documentation
• 自動化向けの Admin CLI リファレンス
• フレームワーク向けのクライアントアダプターのドキュメント
• サポートについてはコミュニティフォーラム