Keycloak: 外観のカスタマイズ

Stackhero で Keycloak のログインページ、アカウントコンソール、メールのブランド化が簡単にできます。色、ロゴ、テキストを設定したり、内蔵のオンラインエディタで完全なカスタムテーマを作成することも可能です。

👋 Stackheroドキュメントへようこそ！

Stackheroは、Keycloakクラウドサービスを提供しており、本番環境対応のアイデンティティプロバイダーをわずか2分でデプロイできます：

無制限のユーザー、レルム、クライアント

OpenID Connect、OAuth 2.0、SAML 2.0、ソーシャルログイン、LDAPおよびActive Directoryフェデレーションに対応

カスタムドメイン名と組み込みのHTTPSによる安全なアクセス（例：https://login.your-company.com）

カスタムテーマ：付属のオンラインエディターでログインページ、アカウントコンソール、メールを簡単にブランディング可能

SPF、DKIM、DMARC対応の専用メールサーバーを搭載し、アカウント確認やパスワードリセットも自動で処理

管理コンソールを独立したクローズ可能なポートで利用できる組み込みPostgreSQLデータベース

ワンクリックアップデートで、手動作業なしにシステムを常に最新状態に維持

設定作業ではなく開発に時間を使いましょう：StackheroのKeycloakクラウドソリューションは最短5分でお試しいただけます。

Keycloak の外観をカスタマイズする

ログインページは、ユーザーが最初に目にするものの一つです。Stackhero なら、数分で自分のブランドに合わせてカスタマイズできます。サポートする各言語ごとに色、ロゴ、文言を設定可能です。同じ方法で、Keycloak が送信するメールもカスタマイズできます。

主に2つのツールがご利用いただけます（どちらもサービスに含まれています）：

テーマエディタ：オンラインのファイルエディタで、ここにテーマが保存されます。
Quick Theme：Keycloak 管理コンソールに組み込まれたビジュアルテーマデザイナー。CSS を編集せずに色やブランド設定ができます。

SSH 接続や再ビルド、再デプロイは不要です。

テーマエディタを開く

Stackhero ダッシュボードのサービスページに、管理コンソールの隣に Themes editor の URL が表示されています：

https://your-domain.com:4443/stackhero_themes/

Keycloak 管理者アカウントの認証情報（管理コンソールと同じもの）でログインしてください。

注意点が2つあります：

エディタは管理用ポートで動作します。アプリケーションが利用するポートとは異なります。Stackhero ファイアウォールでこのポートを閉じると、管理コンソールとエディタの両方にアクセスできなくなりますが、アプリケーションの認証は通常通り動作します。
ここでの変更内容はすべてサービスディスク上に保存され、バックアップに含まれ、再起動やアップデート後も保持されます。

2つのディレクトリが表示されます：

ディレクトリ	目的
`themes/`	ログインページ、アカウントコンソール、メールの外観設定
`providers/`	Keycloak の高度なカスタマイズ用 Java 拡張（`.jar` ファイル）

各ディレクトリには、サービスバージョンに対応した最新ドキュメントが記載された README.md ファイルが含まれています。

テーマの編集準備ができています

themes/ を開くと default/ ディレクトリがあります。これが現在アクティブなテーマで、すでに Keycloak インスタンスで使用されています。選択操作は不要です。ファイルを編集するだけで、即座に変更が反映されます。

Keycloak テーマの事前知識は不要です。各ファイルには、よく変更される設定項目がすでに記載されており、現在の Keycloak の値がコメントアウトされた例として示されています。 値を変更するには、コメント記号を外し、値を調整して保存してください。

コメントのまま残した行は、Keycloak のデフォルト値が使用されます。これにより、アップデート後も常に標準の Keycloak 動作が維持されます。

変更内容	編集するファイル
色、ロゴ、背景、ログインフォント	`default/login/resources/css/stackhero.css`
ログインページのテキスト	`default/login/messages/messages_en.properties`
メールの件名・本文	`default/email/messages/messages_en.properties`
ライト／ダークテーマ	`default/login/theme.properties`
アカウント／管理コンソールのロゴ	`default/account/theme.properties`, `default/admin/theme.properties`
ログインページの HTML 構造	Keycloak の `.ftl` ファイルを `default/login/` にコピーして編集

ロゴの更新

default/login/resources/img/ を開くと、現在ログインページで使用されている2つの画像が表示されます。同じファイル名（keycloak-logo-text.svg）でご自身のロゴをアップロードし、Ctrl+F5（macOS の場合は Cmd+Shift+R）でログインページをリロードしてください。

これだけで完了です。ファイル編集やサービス再起動は不要で、保存と同時に変更が反映されます。背景画像を変更したい場合は、同じフォルダ内の keycloak-bg-darken.svg を更新してください。

異なるファイル名を使いたい場合は、default/login/resources/css/stackhero.css の「Your logo」セクションで参照先を変更できます。

色の設定

stackhero.css には、現在の値が記載された変数がすでに用意されています：

:root {
  /* ---------- Colors ---------- */
  /* The buttons */
  /* --pf-v5-global--primary-color--100: #06c; */
  /* The buttons, while hovered */
  /* --pf-v5-global--primary-color--200: #004080; */
  /* The links */
  /* --pf-v5-global--link--Color: #06c; */
  /* The colored line on top of the login box */
  /* --keycloak-card-top-color: #06c; */

変更を適用するには、コメント記号を外し、色を設定して保存し、ページをリロードしてください。これだけです。

作業中の注意: ブラウザはテーマの CSS、画像、スクリプトを1時間キャッシュします。繰り返し編集する場合は、常に Ctrl+F5 でリロードして最新の変更を確認してください。訪問者には1時間以内に更新が反映されます。

完全なコントロールが可能です。このファイルはプレーンな CSS で、最後に読み込まれるため、どんなスタイルも上書きできます。ブラウザの DevTools（F12）で要素を調査してください。Keycloak 26 では PatternFly design system が使われており、多くの色変数は --pf-v5-global--* という名前で、:root で再定義できます。

会社名の設定

この設定にはテーマ編集は不要です。管理コンソールで Realm settings > General を開き、Display name を設定してください。この名前はログインページやメールに表示されます。

テキストの多言語対応・変更

CSS や HTML を編集せずにテキストを変更できます。default/login/messages/messages_en.properties には、ログインフォームの全テキストとデフォルト文言が記載されています。行頭の # を外し、任意のテキストを入力して保存してください：

loginAccountTitle=Sign in to Acme
doLogIn=Sign in
doForgotPassword=I forgot my password

messages_fr.properties（フランス語）や messages_de.properties（ドイツ語）などのファイルを追加し、管理コンソールの Realm settings > Localization で該当言語を有効化してください。

ヒント：Localization タブには Realm overrides セクションもあり、コンソール上で直接テキストを変更できます。ファイル編集や再起動は不要です。ワークフローに合った方法をご利用ください。

メールのブランド化

Keycloak はアドレス確認、パスワードリセット、ユーザー招待などのメールを送信します。default/email/messages/messages_en.properties には、標準の件名や本文が記載されており、すぐにカスタマイズできます：

emailVerificationSubject=Confirm your Acme account
passwordResetSubject=Reset your Acme password

メール本文を編集する際は、以下にご注意ください：

{0}、{1}、{2} のプレースホルダーはそのまま残してください（Keycloak がリンク、表示名、遅延時間を自動で挿入します）。
アポストロフィは2つ連続で記述してください（例：don''t）。

メール HTML を上書きしたい場合は、Keycloak base email theme からテンプレートを default/email/html/ にコピーし、そのコピーを編集してください。

Stackhero では SPF、DKIM、DMARC 設定済みでメール送信が構成されています。Realm settings > Email で、サービスページに記載されたホスト名とポートを使って設定してください。

テーマをリセットしたい場合

問題が発生した場合は、default ディレクトリを丸ごと削除し、サービスを再起動してください。Stackhero が新しいデフォルトテーマを作成し、Keycloak 標準の外観が復元されます。

realm、ユーザー、クライアントはデータベースに保存されているため影響を受けません。

Quick Theme でビジュアルにテーマを作成

Keycloak 管理コンソールには Quick Theme（Keycloak のビジュアルテーマデザイナー）が用意されています。ロゴをアップロードし、色を選択し、ログインページやアカウントコンソールをプレビューし、完成したテーマを .jar ファイルとしてダウンロードできます。

インストールするには、エディタで themes/ ディレクトリにファイルを配置し、サービスを再起動してください。.jar はテーマディレクトリに展開され、アーカイブは削除されます：

themes/acme.jar        becomes     themes/acme/

新しいテーマは Realm settings > Themes に表示されます。必要に応じて、ファイルを手動で編集し続けることも可能です。

この方法は Keycloakify で作成したテーマや、デザイナーから提供されたテーマにも対応しています。テーマを含む .jar または .zip ファイルはこの方法でインストールできます。同名のテーマがすでに存在する場合は、新しいものは acme-1 としてインストールされ、アップロードによって既存の作業が上書きされることはありません。ファイルがテーマでない場合はそのまま無視され、Keycloak は通常通り起動します。

realm ごとにブランドを分ける：ホワイトラベル対応

テーマは Realm settings > Themes でrealm ごとに選択できます。ログイン、アカウント、管理、メールの各ページタイプごとに設定可能です。個別のアプリケーションでも、クライアント設定で独自のログインテーマを指定できます。

複数ブランドの運用やホワイトラベル提供の場合は、ブランドごとに realm を分け、それぞれにカスタムテーマを割り当ててください：

エディタで default ディレクトリをコピーし、コピーに新しい名前（例：acme）を付けます。
サービスを再起動します。
管理コンソールで該当する realm を開き、ログインテーマとして acme を選択します。

設定していない realm は引き続き default テーマを使用します。

Keycloak テーマ構造の理解

テーマは、各ページタイプごとのサブディレクトリを含むディレクトリです：

themes/
  acme/
    login/                             # ユーザーサインインページ
      theme.properties                 # テーマ継承と CSS インクルード
      resources/css/stackhero.css      # カスタム CSS
      resources/img/logo.svg           # 画像
      messages/messages_en.properties  # テキスト
    account/                           # ユーザープロファイル管理
    admin/                             # 管理コンソールの外観
    email/                             # メールテンプレート

テーマは標準の Keycloak テーマを継承し、必要な部分だけを上書きします。典型的な login/theme.properties は次のようになります：

parent=keycloak.v2
styles=css/styles.css css/stackhero.css

parent でベースとなるテーマを指定します。
styles で読み込む CSS ファイルを列挙します。カスタム CSS は最後に記載し、変更が確実に反映されるようにしてください。

styles のリストは親テーマのリストを置き換えます。拡張ではありません。必ず親のスタイルシート（css/styles.css）を含めてください。含めないとデフォルトのスタイルが失われます。

HTML 構造を変更したい場合のみ FreeMarker テンプレート（.ftl ファイル）が必要です。色、ロゴ、背景、テキスト、多言語対応だけならテンプレート編集は不要です。詳細は Keycloak テーマドキュメントをご覧ください。

Java 拡張（providers）

providers/ ディレクトリは、テーマだけでは実現できない機能（カスタム認証、ユーザーストレージ、イベントリスナー、プロトコルマッパーなど）のためのものです。

.jar ファイルをこのディレクトリに配置し、サービスを再起動してください。この再起動は Keycloak が自身を再構築するため、通常より少し時間がかかります（約1分）。拡張を削除したい場合はファイルを削除し、再度再起動してください。

テーマの .jar ファイルもここに配置できますが、テーマの場合は themes/ ディレクトリの利用を推奨します。再構築が不要で、後からファイル編集も可能だからです。