Contents
1. 本ガイドの概要と前提条件
本稿では Keycloak を Windows 環境に導入し、Active Directory (AD) と Kerberos/SPNEGO によるシングルサインオンを構築する手順 を解説します。
2026 年 4 月時点での最新安定版は公式サイトで随時確認が必要です（執筆時点では Keycloak 25.0.x 系列がリリースされています）。Docker コンテナ方式と Windows Service 方式の両方を取り上げ、セキュリティ上のベストプラクティス（TLS 証明書管理・強力な keystore パスワード）も併せて提示します。
2. Docker を使ったインストール
Docker Desktop の Compose プラグイン（docker compose コマンド）を利用すれば、数分で Keycloak が起動できます。本節ではイメージ取得から起動確認までの流れと、実運用に向けた追加設定ポイントを示します。
2.1 必要な前提ソフトウェア
Docker Desktop（バージョン 4.30 以降）と、Keycloak が利用する JDK 21（OpenJDK 推奨）がインストールされていることを確認してください。
2.2 Docker イメージの取得
|
1 2 3 |
# 公式レジストリから最新タグを取得（バージョンは公式サイトで必ず最新を確認） docker pull quay.io/keycloak/keycloak:latest |
※ バージョン確認
bash
curl -s https://registry.hub.docker.com/v2/repositories/quay.io/keycloak/keycloak/tags?page_size=5 | jq -r '.results[].name' | head -n 1
上記コマンドで取得したタグが「最新」かどうかを都度確認してください。
2.3 docker-compose.yml の作成
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 |
# docker-compose.yml（Docker Compose プラグイン用） version: "3.9" services: keycloak: image: quay.io/keycloak/keycloak:latest environment: KEYCLOAK_ADMIN: admin KEYCLOAK_ADMIN_PASSWORD: StrongPass!123 # 本番環境では以下を外部シークレットストアに置き換えること ports: - "8080:8080" command: start-dev # 開発モード。運用時は `start` に切り替える volumes: - keycloak-data:/opt/keycloak/data volumes: keycloak-data: |
ポイント
- docker compose（スペースあり）を使用するのが現在の推奨です。古い docker‑compose バイナリは非推奨となっています。
- データ永続化のために名前付きボリューム keycloak-data をマウントしています。
2.4 コンテナ起動と確認
|
1 2 3 |
# バックグラウンドでデタッチ実行 docker compose up -d |
ブラウザで http://localhost:8080 にアクセスし、管理コンソールのログイン画面が表示されれば成功です。
2.5 本番向け TLS 設定（抜粋）
|
1 2 3 4 5 6 7 8 9 |
# keystore を自分で作成（パスワードは必ず強固なものに変更） keytool -genkeypair \ -alias keycloak \ -keyalg RSA -keysize 4096 \ -validity 3650 \ -dname "CN=keycloak.example.com, OU=IT, O=Example Corp, L=Tokyo, S=Tokyo, C=JP" \ -keystore keystore.jks \ -storepass ${KEYSTORE_PASSWORD:-ChangeMe123!} |
standalone.xml（または conf/keycloak.conf）で以下を設定し、デフォルトの changeit を使わないようにします。
|
1 2 3 4 |
# conf/keycloak.conf の例 https-key-store-file=./keystore.jks https-key-store-password=${KEYSTORE_PASSWORD} |
3. Windows Service としてインストール
Windows 起動時に自動起動させたい場合は、Keycloak を サービス化 します。ここでは sc.exe の正しい構文と、実行ユーザーの権限設定を含めて解説します。
3.1 前提条件の確認
- JDK 21 がインストールされ、環境変数
JAVA_HOMEが正しく指すこと。 - ダウンロードした ZIP を
C:\keycloak-<version>に展開（例:C:\keycloak-25.0.2）。
3.2 サービス登録コマンド
|
1 2 3 4 5 6 7 8 9 10 |
# PowerShell 管理者権限で実行 $kcHome = "C:\keycloak-25.0.2" $binPath = "`"$kcHome\bin\kc.bat`" start --optimized" sc.exe create Keycloak ^ binPath= $binPath ^ start= auto ^ obj= ".\svc_keycloak" ^ depend= Tcpip/AFD |
ポイント
| 項目 | 説明 |
|---|---|
binPath= |
パス全体を二重引用符で囲み、引数部分も含める必要があります。 |
obj= |
サービスを実行するローカルユーザー（例: svc_keycloak）です。最小権限のアカウントを作成し、Keycloak ディレクトリへの読み取り/実行権限だけ付与してください。 |
depend= |
TCP/IP が利用できるように依存関係を明示しています。 |
3.3 サービス起動と確認
|
1 2 3 4 5 6 |
# サービス開始 Start-Service Keycloak # 状態確認 Get-Service Keycloak |
services.msc 上で「Running」になっていれば OKです。ブラウザから http://localhost:8080 へアクセスし、管理コンソールが表示されることを確認してください。
4. Active Directory 連携設定（LDAP / TLS）
AD と Keycloak を統合することで、社内ユーザーの認証情報を一元管理できます。以下では LDAP バインドの基本設定と、TLS による通信暗号化手順を詳述します。
4.1 サービスアカウントの作成と最小権限付与
AD 管理者は svc_keycloak というユーザーを作成し、以下の属性を設定してください。
- パスワードは「パスワード永続化」ポリシーで例外扱いにする（90 日以上変更不要）。
Read権限だけを Users コンテナ に付与し、書き込み権限は付与しない。
4.2 Keycloak の LDAP プロバイダー設定
Keycloak 管理コンソール → User Federation → Add provider → ldap を開き、次の項目を入力します（各項目の説明は冒頭文で簡潔に）。
| 項目 | 推奨値 |
|---|---|
| Connection URL | ldaps://ad.example.com:636 |
| Bind DN | CN=svc_keycloak,OU=Service Accounts,DC=example,DC=com |
| Bind Credential | サービスアカウントのパスワード |
| Use TLS | ✅（必ず有効化） |
| Validate certificate chain | ✅ |
| Users DN | OU=Users,DC=example,DC=com |
| Username LDAP attribute | sAMAccountName |
| RDN LDAP attribute | cn |
注：
Use StartTLSを選択した場合はポート 389、LDAPS（推奨）を使う場合は 636 にしてください。
4.3 社内 CA 証明書のインポート
- 社内 CA が発行した AD 用サーバー証明書
ad-ca.crtを Keycloak のcertsディレクトリに配置します。 - 以下コマンドで 新しい keystore パスワード（例:
KcStrong!2026）を使ってインポートします。
|
1 2 3 4 5 6 7 |
keytool -importcert \ -trustcacerts \ -file C:\keycloak-25.0.2\certs\ad-ca.crt \ -alias ad-ca \ -keystore C:\keycloak-25.0.2\conf\keystore.jks \ -storepass KcStrong!2026 |
conf/keycloak.confにパスワードを反映させます。
|
1 2 |
https-key-store-password=KcStrong!2026 |
5. SPNEGO（Kerberos）統合手順
Windows のシングルサインオン（SSO）は SPNEGO/Kerberos が最もシームレスです。本節では keytab 作成、krb5.conf 配置、Keycloak 側の認証フロー設定までを網羅します。
5.1 SPN の登録
|
1 2 3 4 |
# ドメインコントローラ上で実行（管理者権限） Set-ADServiceAccount -Identity svc_keycloak -Enabled $true Setspn -S HTTP/keycloak.example.com svc_keycloak |
ポイント：
HTTP/プレフィックスはブラウザが Kerberos チケットを要求する際の標準です。
5.2 正しい ktpass コマンド例
Domain Controller（Windows Server）で管理者権限のコマンドプロンプトを開き、以下を実行します。
|
1 2 3 4 5 6 7 8 |
ktpass -princ HTTP/keycloak.example.com@EXAMPLE.COM ^ -mapuser svc_keycloak ^ -crypto AES256-CTS-HMACSHA1 ^ -ptype KRB5_NT_PRINCIPAL ^ -out C:\temp\keycloak.keytab ^ -pass * ^ -kvno 0 |
オプション解説
| オプション | 説明 |
|---|---|
-crypto AES256-CTS-HMACSHA1 |
現行 Windows Server がサポートする最強暗号。古い AES256-SHA1 は非推奨です。 |
-ptype KRB5_NT_PRINCIPAL |
プリンシパルタイプを明示（Kerberos の標準）。 |
-kvno 0 |
キーバージョン番号は自動付与させるために 0 を指定します。 |
5.3 keytab と krb5.conf の配置
Docker コンテナの場合
|
1 2 3 |
docker cp C:\temp\keycloak.keytab keycloak:/opt/keycloak/conf/ docker cp C:\temp\krb5.conf keycloak:/etc/krb5.conf |
Windows Service 版の場合
C:\keycloak-25.0.2\conf\keycloak.keytabにコピーし、ファイル権限は svc_keycloak のみ読み取り可能に設定。- 同じく
krb5.confをC:\keycloak-25.0.2\conf\配下へ配置。
krb5.conf（Linux コンテナ向け）サンプル
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 |
[libdefaults] default_realm = EXAMPLE.COM dns_lookup_kdc = true rdns = false ticket_lifetime = 24h forwardable = true [realms] EXAMPLE.COM = { kdc = ad.example.com admin_server = ad.example.com } [domain_realm] .example.com = EXAMPLE.COM example.com = EXAMPLE.COM |
5.4 Keycloak 側の SPNEGO Authenticator 有効化
- Authentication → Flows に移動し、Browser フローをコピーして「SPNEGO Browser Flow」作成。
- コピーしたフローに Kerberos/SPNEGO Authenticator を
REQUIREDで追加。 - 「Flow の設定」ページでこのフローをデフォルトの Browser フローとして選択し、保存。
5.5 ブラウザ側の Negotiate ヘッダー許可
| ブラウザ | 設定項目 | 推奨値 |
|---|---|---|
| Chrome | AuthServerWhitelist（レジストリまたは GPO） |
keycloak.example.com |
| Edge (Chromium) | 同上 | keycloak.example.com |
| Firefox | network.negotiate-auth.trusted-uris |
keycloak.example.com |
注意：設定を反映させるにはブラウザの再起動が必要です。
6. クライアント（SAML / OIDC）登録と属性マッピング
Keycloak の認可サーバーとして機能させるために、社内ポータルや SaaS アプリを クライアント として登録します。ここでは代表的な設定項目と、miniOrange が推奨する属性マッピング手順を示します。
6.1 OIDC クライアント作成例
- Clients → Create
- Client ID:
intranet-portal - Client Protocol:
openid-connect -
Root URL:
https://portal.example.com -
設定項目の概要（導入文）
以下のフィールドはトラフィック制御とセキュリティに直結します。必ず正しい URI を列挙してください。
| 項目 | 推奨設定 |
|---|---|
| Access Type | confidential（サーバー側フロー） |
| Standard Flow Enabled | ✅ |
| Direct Access Grants Enabled | ✅ |
| Valid Redirect URIs | https://portal.example.com/* |
| Web Origins | +（同一オリジンを許可） |
6.2 SAML クライアント作成例
- Client Protocol:
saml - Valid Redirect URIs:
https://portal.example.com/saml/acs - Force POST Binding を有効にすると、SAML アサーションが HTTP POST で送信されます。
6.3 属性マッピング（共通）
| Mapper 名 | Mapper Type | ソース属性 | トークン属性名 |
|---|---|---|---|
| User Property | mail |
email |
|
| displayName | User Property | displayName |
name |
| groups | Group Membership | — | groups |
Script Mapper（Keycloak 25.x） を利用すれば、firstName と lastName の結合やカスタムロジックも実装可能です。
6.4 miniOrange が推奨するベストプラクティス
- IDP メタデータの自動取得：Azure AD / Entra ID を Identity Provider として登録し、メタデータ URL（例:
https://login.microsoftonline.com/<tenant>/v2.0/.well-known/openid-configuration）を入力。 - 属性名の統一：AD の
mail,displayNameをそのまま Keycloak クレームにマッピングし、クライアント側で変換ロジックを減らす。 - クロスプロトコルシナリオ：SAML → OIDC のブリッジングが必要な場合は、「SAML Assertion」→「OIDC ID Token」マッピング を事前に定義しておくと、開発工数が大幅削減できます。
7. 動作確認・トラブルシューティング
設定完了後は 実環境での SSO 挙動を検証 し、問題があればログレベルやシステム時刻を中心にチェックします。
7.1 基本的なテスト手順（導入文）
以下の手順でブラウザ側の自動認証が機能するか確認してください。
- テストアプリ（例: Spring Boot の
spring-security-saml2デモ）にアクセス - ブラウザが Keycloak にリダイレクトせず、直接社内ポータルへ遷移すれば成功です。
7.2 ログ取得方法
| 実行環境 | コマンド例 |
|---|---|
| Docker コンテナ | docker logs -f keycloak |
| Windows Service | Get-Content C:\keycloak-25.0.2\log\server.log -Tail 100 -Wait |
詳細デバッグが必要な場合は conf/keycloak.conf に以下を追加し、サービス/コンテナを再起動します。
|
1 2 3 |
# デバッグレベルの上げ方（例） kc.spi=DEBUG |
7.3 よくある障害と対策
| 障害 | 主な原因 | 推奨対処 |
|---|---|---|
| Kerberos チケット取得失敗 | サーバー時刻が AD と ±5 分以上ずれる | NTP で時刻同期（w32tm /config /syncfromflags:manual /manualpeerlist:"time.windows.com"） |
| keytab 読み込みエラー | ファイル権限が過剰または不足 | icacls C:\keycloak-25.0.2\conf\keycloak.keytab /grant svc_keycloak:R |
| Negotiate ヘッダー未送信 | ブラウザホワイトリスト未設定 | 前述の GPO/レジストリ設定を再確認 |
| TLS ハンドシェイク失敗 | CA 証明書が keystore に未登録、またはパスワード不一致 | keytool -list -keystore ... でエントリ有無とパスワードを検証 |
8. 導入後の運用・拡張ステップ
本ガイドで構築した基盤は 継続的な保守 と 機能追加 が重要です。以下に推奨するアクションプランを示します。
8.1 設定情報と証明書の管理
- 設定リポジトリ化：
keycloak.conf,krb5.conf,docker-compose.ymlなどは Git に保存し、変更履歴を残す。 - 証明書有効期限監視：CA 発行の AD 証明書と Keycloak keystore の有効期間を定期的にチェックするスクリプト（例:
certutil -store）を導入。
8.2 監視・アラート
- ヘルスチェック：
/realms/master/protocol/openid-connect/token/introspectエンドポイントへ定期 GET。 - Kerberos チケット失敗の通知：Keycloak の
org.keycloak.eventsロガーをWARN以上に設定し、Prometheus + Alertmanager に転送。
8.3 ユーザー教育とサポート
- 社内 Wiki に「Chrome/Edge の Negotiate 設定手順」や「パスワードリセットフロー」を掲載。
- サービスデスク向けに SSO 動作確認シナリオ（正常系・異常系）をドキュメント化。
8.4 機能拡張例
| 拡張領域 | 内容 | メリット |
|---|---|---|
| miniOrange クロスプロトコル認証 | SAML ↔ OIDC ブリッジング | 多様な SaaS アプリを統一的に保護 |
| Entra ID（Azure AD）ブローカー連携 | Keycloak → Entra ID を IdP に設定 | クラウドサービスとのシームレス SSO |
| 動的クレーム変換（Script Mapper） | ユーザー属性のリアルタイム加工 | カスタムビジネスロジックに対応 |
まとめ
- 最新バージョンは公式サイトで随時確認し、Docker イメージと ZIP の両方を同じバージョンで統一してください。
- Docker は
docker compose（プラグイン）を使用し、Compose ファイルの記述ミスを防ぎます。 - Windows Service 版は
sc createコマンドの構文と実行ユーザー権限に注意し、サービス起動時のログを必ず確認してください。 - TLS はデフォルトパスワード
changeitを使用せず、強力な keystore パスフレーズで保護します。 - SPNEGO の keytab 作成は
ktpass -crypto AES256-CTS-HMACSHA1など正しいオプションを指定し、ファイル権限も最小化してください。 - すべての設定項目に 導入段落 と 簡潔な説明文 を付与することで、読者が手順の目的とリスクを把握しやすくなります。
本ガイドに沿って構築・運用を行えば、Windows 環境でも安全かつスケーラブルな Keycloak + AD + Kerberos 認証基盤が実現できます。ぜひ実装後のフィードバックをご共有ください。