Contents
前提条件と環境構築
Keycloak 25 以降は Docker と JDK 17 があれば数分で SAML IdP の土台が完成します。本章では Docker イメージの取得 → コンテナ起動 → HTTPS の最小構成 を順を追って解説し、実務で頻出する設定ポイントだけに絞ります。
Keycloak 25+ のインストール手順
Keycloak 25 以上は JDK 17 が必須です。公式 Docker イメージは Alpine ベースの軽量イメージ quay.io/keycloak/keycloak:25（または latest）で提供されています。
|
1 2 3 |
docker pull quay.io/keycloak/keycloak:25 docker run --rm quay.io/keycloak/keycloak:25 version # バージョン確認 |
ポイント：CPU 2 コア、RAM 2 GB 程度の環境で問題なく動作します。開発・CI のいずれでも同様です。
Docker コンテナでの起動（HTTPS を含む最小構成）
本番環境では TLS が必須です。ここでは自己署名証明書をマウントする例を示しますが、実運用時は Let’s Encrypt や社内 CA の証明書に差し替えてください。
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 |
version: "3.8" services: keycloak: image: quay.io/keycloak/keycloak:25 environment: - KC_DB=dev-file # 開発用ファイル DB - KEYCLOAK_ADMIN=admin # 管理者ユーザー - KEYCLOAK_ADMIN_PASSWORD=StrongPwd! # 強力パスワード - KC_HTTPS_CERTIFICATE_FILE=/certs/tls.crt - KC_HTTPS_CERTIFICATE_KEY_FILE=/certs/tls.key ports: - "8080:8080" # 開発用 HTTP（内部だけ公開可） - "8443:8443" # 本番向け HTTPS volumes: - ./certs:/certs:ro # 証明書格納ディレクトリをマウント command: start-dev --https-port=8443 |
- ポート設計：外部からは
8443（HTTPS）のみ公開し、8080はファイアウォールで遮断します。 - 証明書管理：自己署名でも有効期限切れを防ぐために CI パイプラインで自動更新スクリプトを走らせると運用負荷が減ります。
この構成で docker compose up -d を実行すれば、数秒後に管理コンソール https://localhost:8443/ にアクセスできます。
Realm 作成と SAML IdP の基本設定
Keycloak の UI は 25 系からサイドバー形式へ変更されましたが、操作フローは変わりません。本章では Realm の作成 → EntityID／SSO URL 設定 → 署名・暗号化の選択 を実務で推奨する形でまとめます。
Realm の作成手順
- 管理コンソール左上の Master ドロップダウンから Add realm をクリック。
- 名前（例：
corp-realm）と任意の説明を入力し Create。 - 作成した Realm が選択された状態で次へ進みます。
結論：Realm 名は IdP の EntityID に組み込まれるため、社内ドメイン（例:
idp.example.com）と合わせておくとトラブルが減ります。
EntityID と SSO URL の設定
| 項目 | 推奨値の例 | 補足 |
|---|---|---|
| EntityID | https://idp.example.com/realms/corp-realm |
IdP を一意に識別する URI |
| SSO URL | https://idp.example.com/realms/corp-realm/protocol/saml |
Keycloak が自動生成しますが、メモしておくと SP 側設定が楽です |
これらは「Identity Provider」→「SAML 2.0」の画面で Entity ID と Single Sign‑On Service URL に入力します。
署名・暗号化オプション（冗長記述の統合）
| オプション | 推奨設定 | 理由 |
|---|---|---|
| Signature Required | ON | 多くの SP がリクエスト署名を必須としている（※Accel‑Mart 事例）。 |
| Encrypt Assertions | 必要に応じて ON | 個人情報保護方針で暗号化が求められる場合。 |
| Force POST Binding | OFF (Redirect がデフォルト) | POST はブラウザサイズ制限が厳しいため、可能な限り Redirect を使用。 |
ポイント：署名を有効にすると SP 側で証明書のインポートが必要です。次章でメタデータと合わせた手順を示します。
Accel‑Mart 事例の概要（外部リンクの要約）
Accel‑Mart は日本国内の大手小売チェーン向け e‑コマース基盤です。同社は外部パートナーと SAML 連携する際、リクエスト署名が無いとリプレイ攻撃が成立しやすく、監査で指摘されたという背景があります（公式ガイドの抜粋）。このため「Signature Required」を必ず ON にしています。
SP メタデータ取得と Keycloak へのインポート
SAML の連携は メタデータ XML の交換だけで完結します。本章では WordPress と Spring Boot の代表的な取得方法を解説し、Keycloak UI を使ったインポート手順を示します。
SP 側メタデータの取得方法
| 製品 | 取得手段 | 補足 |
|---|---|---|
| WordPress | 公式 SAML SSO プラグイン（例: 「SAML 2.0 Single Sign On」）の管理画面に表示される Metadata URL をクリック → XML がダウンロード | Qiita 記事「KeycloakでSAMLを使ってみる（WordPress編）」では、プラグイン設定手順と取得したメタデータ例が掲載されています（要点は上表参照）。 |
| Spring Boot | http://localhost:8080/saml/metadata に GET リクエストすると XML が返却される |
Spring Security 6 系の標準エンドポイントです。 |
Keycloak へのインポート手順
- 管理コンソール左側メニュー Identity Provider → Import from XML / URL を選択。
- XML タブに取得したメタデータを貼り付け、Import ボタンをクリック。
- 必要に応じて URL タブにメタデータの URL（例:
https://example.com/sp/metadata.xml） を入力しインポートでも可。
インポートが完了すると Entity ID, SSO Service URL, 証明書情報 が自動で設定されます。
結論：手作業でも URL 経由でも結果は同一です。CI パイプラインで自動取得したい場合は URL 方式が便利です。
属性・ロールマッピングと署名設定
SP から受け取る属性を Keycloak のユーザー属性やロールに変換する作業は、認可設計の要となります。本節では「メール」「氏名」「カスタムロール」の３パターンを具体例付きで示します。
SAML Request の署名有効化（重複排除）
- Identity Provider → SAML 2.0 編集画面の Signature Required スイッチを ON。
- Signing Certificate 欄に表示される証明書が自動生成されたものか、社内 CA が発行したものか確認。
背景：Accel‑Mart の事例では、署名が無いとリプレイ攻撃が成立しやすく監査で指摘されたため、必ず有効化しています（上記参照）。
属性マッピング例
| Mapper 名 | SAML アトリビュート (OID) | Keycloak ユーザー属性 |
|---|---|---|
email-mapper |
urn:oid:0.9.2342.19200300.100.1.3（メール） |
email |
givenName-mapper |
urn:oid:2.5.4.42（名） |
firstName |
familyName-mapper |
urn:oid:2.5.4.4（姓） |
lastName |
上表の設定は Mappers タブで Add builtin → User Attribute Mapper を選び、各項目を入力すれば完了です。エクスポートした JSON の例も併記します。
|
1 2 3 4 5 6 7 8 9 10 |
{ "name": "email-mapper", "protocolMapper": "saml-user-attribute-mapper", "config": { "user.attribute": "email", "friendlyName": "email", "attribute.nameformat": "Basic" } } |
カスタムロールマッピングの実装手順
- Add builtin → Role List Mapper を選択。
SAML Attribute Nameにrole、Attribute Valueに正規表現admin|manager|userを設定。- 取得した文字列を Realm Role として自動割当て（ロールは事前に Realm 側で作成しておく）。
ポイント：ロール定義は JSON ファイルで管理し、CI パイプラインから
kc.sh importコマンドで自動投入すると運用が楽です。
実装例・テスト手順・トラブルシューティング・ベストプラクティス
設定が完了したら実際に SP から SSO を試すフェーズへ移ります。本章では WordPress と Spring Boot の代表的な設定例、検証ツールの使い方、よくあるエラーと対策をまとめます。
WordPress 側設定手順
- プラグイン → 「SAML 2.0 Single Sign On」 をインストール。
- Identity Provider Settings に以下を入力：
- IdP Entity ID：
https://idp.example.com/realms/corp-realm - SSO URL：
https://idp.example.com/realms/corp-realm/protocol/saml - X.509 Certificate：Keycloak の証明書（Realm Settings → Keys から取得）
- Advanced Settings で Force Authentication を ON にし保存。
設定完了後、WordPress のログイン画面に「SAML Login」ボタンが表示されます。
Spring Boot 側設定手順
application.yml に SAML SP 設定を追加します（Spring Security 6 系対応）。
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 |
spring: security: saml2: relyingparty: registration: keycloak-idp: identity-provider-metadata-location: classpath:/metadata/keycloak-sp.xml signing-credentials: - private-key-location: classpath:/keys/sp.key certificate-location: classpath:/keys/sp.crt decryption-credentials: - private-key-location: classpath:/keys/sp-decrypt.key certificate-location: classpath:/keys/sp-decrypt.crt |
keycloak-sp.xmlは先ほど Keycloak からエクスポートした SP メタデータです。- 証明書・鍵は PKCS#12 形式で管理し、パスワードは環境変数経由で渡すと安全です。
Assertion の確認手順（SAML Tracer）
- Chrome 拡張機能 SAML‑Tracer をインストール。
- SSO フローを実行し、Tracer 画面から最新リクエストを選択 → 「Response」タブで Assertion XML を表示。
- DevTools の Network タブで
POST /saml/SSOペイロードを確認し、属性 (email,firstName,role) が期待通りか検証。
チェックリスト
- [ ]
<Attribute Name="urn:oid:0.9.2342.19200300.100.1.3">（メール）が含まれる - [ ]
<Signature>要素が存在し、証明書指紋と一致する - [ ]
<Attribute Name="role">にadmin,managerが列挙されている
よくあるエラーと対処法
| エラーメッセージ | 主な原因 | 推奨対策 |
|---|---|---|
| Invalid Signature | SP が署名を期待していない、または証明書が不一致 | Keycloak の Signature Required を OFF にするか、SP 側に正しい証明書をインポート |
| Metadata mismatch | EntityID または ACS URL が相違 | 両側のメタデータを再確認し、Keycloak の Redirect URI も合わせる |
| Certificate expired | 証明書有効期限切れ | 新証明書を生成し Realm Settings → Keys に再登録。ローテーションスクリプトで自動化 |
キー管理・暗号化・HTTPS 強制のベストプラクティス
- キー管理：
kc.sh start-dev --import-realmと併用し、鍵情報を JSON で GitOps 管理。ローテーションは 90 日ごとに自動化するのが実務上安全です。 - 暗号化：機密属性（例: 社員番号）を送信する場合は
Encrypt Assertionsを ON にし、Keycloak の公開鍵を SP 側へ配布します。 - HTTPS 必須化：SAML は署名があっても通信路の暗号化は必須です。コンテナ内の
--https-port設定に加えて、リバースプロキシ（NGINX/Traefik）で HSTS ヘッダーを付与し、TLS 1.2 以上を強制してください。
まとめ
- 導入は簡単：Docker + JDK 17 だけで Keycloak 25+ が数分で起動。公式イメージ
quay.io/keycloak/keycloak:25を利用し、HTTPS 設定は上記 YAML 1 ファイルに集約できます。 - Realm と SAML IdP の設定：EntityID・SSO URL は明示的にメモし、署名は Accel‑Mart 事例を参考に必ず ON にするのが安全策です。暗号化は要件次第で切り替えます。
- SP メタデータ取得：WordPress のプラグインや Spring Boot のエンドポイントから XML を取得し、Keycloak UI の「Import from XML / URL」だけで完了します。CI では URL インポートが便利です。
- 属性・ロールマッピング：Mappers タブで JSON 設定を作成すれば、メール・氏名・カスタムロールの変換が一元管理でき、認可設計がシンプルになります。
- テストとトラブルシューティング：SAML‑Tracer と DevTools で Assertion を確認し、エラーコード別対処表を活用すれば多くの障害は即座に解決できます。キー管理・HTTPS 強制は本番環境の必須項目です。
以上の手順とベストプラクティスに沿って設定すれば、WordPress・Spring Boot いずれの SP に対しても Keycloak を IdP とした SAML シングルサインオン が即座に利用可能になります。ぜひご自身のプロジェクトで試してみてください。