Contents
Keycloakテーマ構成とディレクトリ構造の確認方法
Keycloakでカスタムテーマを作成する際、既存のテーマ構成を理解することが不可欠です。標準テーマはthemes/src/main/resources/theme/keycloak/以下に配置され、この中にloginやaccountなどのサブテーマが含まれています。カスタムテーマを実装するには、このディレクトリ構造をベースに独自のフォルダを作成し、必要ファイルをコピー・編集します。
ターミナルでのテーマ構成確認手順
Keycloakテーマ構成を確認する際は、以下の手順で階層やファイル種別を把握することが重要です。
-
テーマディレクトリの確認
themes/
└── src/
└── main/
└── resources/
└── theme/
├── keycloak/ (標準テーマ)
│ ├── login/
│ ├── account/
│ └── ...
└── mytheme/ (カスタムテーマ作成用フォルダ) -
ファイル種別の確認
主に以下のファイルが存在します。 -
login.ftl：ログイン画面テンプレート（Keycloak公式ドキュメントを参照） theme.properties：テーマ設定ファイル（親テーマ指定など）assets/：CSSやJSなどの静的リソース
カスタムテーマ作成時の注意点と手順
カスタムテーマの実装においては、バージョン変更に応じた構造調整やブランド情報の一貫性が求められます。以下のポイントを意識してください。
- バージョンごとの変更：Keycloak 20以降では
login.ftlの構造が一部変更されているため、公式ドキュメントで最新情報を確認してください。 - 親テーマの指定：
theme.propertiesにparent=keycloakを記述し、標準テーマを継承してカスタマイズします。 - ブランド情報の一貫性：企業向け利用時はKeycloakの商用ライセンス条件をご確認ください（公式ライセンスページを参照）。
loginテーマのHTML/FreeMarkerファイルのカスタマイズ手順
Keycloakのログイン画面はlogin.ftlなどのテンプレートで構成されています。このファイルを直接編集することで、UIデザインや認証フローに合わせたカスタム実装が可能になります。
login.ftlの基本構造と編集方法
login.ftlはFreeMarkerタグ（${}）で動的な値を出力しています。代表的なタグ例とUI変更手順を以下に示します。
- 基本構造確認
- UI変更手順
- ロゴの追加：
<img src="/assets/images/logo.png" alt="企業ロゴ">のようにassets/に配置した画像を参照 - 認証方法の変更：
<input type="radio" name="authenticator" value="password"/>パスワード認証など
認証フローに合わせたUI調整とセキュリティ対策
複数ステップの認証フローに対応するには、以下の実装方法が推奨されます。
- セキュリティ対策：CSRFトークンを自動生成する
<input type="hidden" name="redirect_uri" value="${redirectUri}">を追加することで、不正な認証リクエストを防ぎます。 - マルチステップ認証対応：複数の認証ステップがある場合、
<div class="step step1">...</div>などにクラス分けし、JavaScriptで表示切り替えを実装します。
注意：JavaScriptコードサンプルにおけるセキュリティリスク（例:
alert()による入力チェック）については、サーバーサイドでの検証が必須です。クライアント側の検証は補助的役割に留めることを推奨します。
静的リソース（CSS/JS）の追加方法
独自のデザイン要素やJavaScript機能を統合するには、静的リソースをassets/フォルダに配置し、FreeMarkerテンプレートから参照する必要があります。
assetsディレクトリ構造と配置手順
themes/src/main/resources/theme/mytheme/assets/以下にCSSやJSを配置します。整合性の検証が必要なため、以下の説明を参考にしてください。
| ファイルタイプ | 配置先 | 目的 |
|---|---|---|
| CSSファイル | assets/css/ |
UIデザインのカスタマイズ |
| JSファイル | assets/js/ |
インタラクティブな機能実装 |
テンプレートからの参照方法とリソース管理
静的リソースはテンプレート内から以下のように参照します。
- CSSの読み込み：
<link rel="stylesheet" href="/assets/css/custom.css">とlogin.ftlに記述します。 - JSの読み込み：
<script src="/assets/js/validation.js"></script>をテンプレート末尾に追加してください。
注意点：CDN経由でリソースを呼び出す場合、Keycloakのセキュリティポリシーに従って設定してください。
国際化設定（messages.properties）の実装
複数言語対応にはmessages.propertiesファイルを作成し、各言語ごとのメッセージを定義します。これにより、管理画面で言語を選択できるようになります。
メッセージファイルの作成手順と言語切り替え
以下の手順で国際化設定を行います。
-
ファイル配置場所
themes/src/main/resources/theme/mytheme/messages.propertiesに以下のように記述：
properties
Username=ユーザー名
Password=パスワード
Login=ログイン -
多言語対応ファイルの作成例
-
英語:
messages_en.properties
Username=Username
Password=Password
Login=Login -
中国語:
messages_zh.properties
Username=用户名
Password=密码
Login=登录
言語切り替え時の挙動確認とテストケース
言語設定が正しく反映されるかを検証するには、以下の手順でテストしてください。
| テスト項目 | 期待される挙動 | 検証手順 |
|---|---|---|
| ログイン画面の表示 | カスタムデザインが適用される | ブラウザでアクセスして視覚チェック |
| 言語切り替えの動作 | 設定した言語に自動変更される | 管理コンソールから言語を変更し、再アクセス |
テーマ適用後のKeycloak設定変更
カスタムテーマを作成したら、管理コンソールで実際に適用する必要があります。ここでは手順とテスト方法を解説します。
管理コンソールでのテーマ選択手順
以下のように手順を踏むことで、カスタムテーマの適用が可能です。
- Realmの設定画面へアクセス
-
ログイン後、
realms/[realm-name]→ 「Themes」タブを開きます。 -
ログインテーマの変更
-
「Login Theme」ドロップダウンから
mythemeを選択し、「Save」をクリックします。 -
ブラウザでの表示確認
http://[keycloak-server]/realms/[realm-name]/loginにアクセスし、カスタムテーマが反映されているか確認してください。
自社ブランドに最適化されたログイン画面の設計ポイント
カスタムテーマは企業イメージの強化にもつながります。UI/UXとセキュリティのバランスを取った設計ポイントを以下にまとめます。
UI/UX最適化とブランド情報の一貫性
ブランド情報を統一するために以下の実装方法を検討してください。
- ロゴ配置：
<div class="logo">...</div>にロゴ画像を挿入し、ブランドイメージを強調します。 - 色調統一：企業カラー（例:
#007BFF）をCSSで定義し、全体のUIと一致させる。
セキュリティとデザインのバランス
セキュリティ対策を設計に組み込むことで、信頼性が向上します。
- CSRトークンの自動挿入：
<input type="hidden" name="csrf_token" value="${csrftoken}">をテンプレートに含めることで、不正なリクエストを防ぎます。 - パスワード入力欄の強化：JavaScriptで「12文字以上」や「数字・記号混在」をチェックするスクリプトを組み込むことで、セキュリティを高めます。
企業向け利用時はKeycloakの商用ライセンス条件をご確認ください。また、バージョンアップに備えて、テーマ構成を最新版と比較して更新することをおすすめします。