Contents
Keycloakカスタムテーマ作成の基本構造と前提知識
KeycloakのUIブランド化は、セキュリティポリシーに沿ったログイン画面を構築する上で不可欠な技術です。本記事では、Red Hat公式ドキュメントに準拠したthemesディレクトリ構成と、カスタムテーマを有効化するための設定ファイルの書き方を解説します。
Keycloakのテーマ管理はthemes/ディレクトリ配下で行い、各テーマには明確な階層構造が必要です。
themesディレクトリ構成と役割
Keycloakテーマは以下のディレクトリ構造に従って構成されます。この構造はRed Hat公式ドキュメントに記載されているものであり、カスタムテーマを作成する際の基本となる設計基準です。
| ディレクトリ | 内容 | 注意点 |
|---|---|---|
mytheme/ |
カスタムテーマ名（任意） | 避けるべき名称例: admin, loginなど既存テーマと重複する名称 |
mytheme/login/ |
ログイン画面テンプレート | login-override.htmlを上書き可能 |
mytheme/welcome/ |
ユーザー歓迎画面テンプレート | welcome-override.htmlを上書き可能 |
mytheme/static/ |
CSSやJavaScriptファイル | 相対パスで参照される |
重要:
parentフィールドには、カスタムテーマの基底となる既存テーマ（例:base,account）を指定します。これにより、デフォルトスタイルやコンポーネントを継承できます。
ログイン・ウェルカムページ専用テーマの作成手順
ログイン画面とウェルカム画面は、ユーザー認証フローにおいて最も重要なUI要素です。両画面のカスタマイズには、以下のような差分戦略を意識する必要があります。
HTML/CSSテンプレートの上書きポイント
Keycloakではlogin.ftlやwelcome.ftlなどのFreeMarkerテンプレートが使用されます。以下のファイルを編集することで、UI要素を変更できます。
login-override.html: ログインフォーム全体のHTML構造welcome-override.html: ユーザー情報表示・アクティビティ一覧のレイアウト
差分戦略比較表
| 項目 | login.ftl |
welcome.ftl |
|---|---|---|
| 主な変更対象 | ロゴ・フォームレイアウト | アクティビティカードスタイル |
| CSS注入先 | /static/login.css |
/static/welcome.css |
| セキュリティ考慮点 | CAPTCHA追加の可否 | セッションタイムアウト表示 |
ロゴとブランドカラーの設定方法
themes/mytheme/static/images/にロゴ画像を配置-
login.ftlの<header>タグ内に画像リンクを追記
html
<img src="/static/images/logo.png" alt="企業名"> -
CSSファイルでブランドカラーを定義（例:
#007BFF）
css
.kc-login-form {
background-color: #007BFF;
}
即時反映可能なキャッシュ無効化設定
Keycloakはデフォルトで静的リソースをブラウザと内部キャッシュに保存するため、変更が即時反映されません。
静的リソースキャッシュメカニズムの対策
-
ブラウザキャッシュ無効化:
URLパラメータでバージョン管理（例:?v=20260703）を追加 -
Keycloak内部キャッシュ無効化:
起動オプションに以下を指定
bash
-Dkeycloak.theme.cache.disabled=true
注意:
keycloak.theme.cache.disabled=trueという起動パラメータの正確性は、Keycloakのバージョンによって変化する可能性があります。公式ドキュメントで確認してください。
ホスト環境ごとの設定差異
| 環境 | 手順 |
|---|---|
| 開発環境 | 上記の起動オプションをstandalone.xmlに追加 |
| 本番環境 | 静的リソースファイル名を定期的に変更（例: style-20260703.css） |
keycloakifyによるReactテーマ開発ワークフロー
keycloakifyは、TypeScriptとReactでKeycloakカスタムテーマを開発できるツールですが、Red Hat公式ガイドラインには記載されていません。導入時は外部ライブラリとしての利用可能性を確認してください。
TypeScriptプロジェクト構築手順
- Node.js 18以降をインストール
-
keycloakify CLIをグローバルインストール
bash
npm install -g keycloakify -
新しいプロジェクトを作成
bash
npx keycloakify create mytheme --typescript注意:
npx keycloakify createコマンドは、keycloakifyの最新バージョンで動作するか確認してください。公式リポジトリを参照ください。
コンポーネントベースのUI設計
keycloakifyでは、src/components/配下に以下のコンポーネントを配置します。
Login.tsx: ログインフォームのカスタマイズWelcome.tsx: ウェルカム画面のUI構築
スタイルシート注入方法
src/styles/global.cssでテーマカラー定義theme.jsに以下を追記
js
import './styles/global.css';
実務向けテーマ開発チェックリスト
企業導入時のリスク回避策と、クロスブラウザテストの実施方法を以下の項目でまとめます。
セキュリティ要件対応項目
- パスワードフィールドに
type="password"が設定されているか - CAPTCHAの有効性検証（セキュリティポリシーに基づく可否判定が必要）
- ARIA属性を含むアクセシビリティ対策
レスポンシブ設計の検証ポイント
- スマートフォン・タブレットでの表示確認
- モバイル最適化用CSS（
max-width,flexbox）が適用されているか - 画面幅変更時のレイアウト崩壊テスト
実務導入における注意点とまとめ
Keycloakのカスタムテーマ開発においては、以下の点に留意することが重要です。
開発に関する重要事項
- Red Hat公式ガイドラインへの準拠: keycloakifyなどの外部ツールは、公式ドキュメントに記載されていないため、導入前に仕様確認を。
- キャッシュ無効化の正確性:
keycloak.theme.cache.disabled=trueなどはバージョン依存のため、最新版での動作確認が必要です。 - CAPTCHA導入: セキュリティ要件により必須または不要となる場合があるため、導入前にはポリシーの確認が不可欠です。
本記事の目的と方向性
本記事では、Keycloakのカスタムテーマ構築に必要な知識や手順を解説し、実務でのリスク回避策も提示しました。読者自身が安全かつ効率的にUIブランド化を進められるよう、セキュリティ・開発フロー両面からのアプローチを意識してください。