セキュリティ

Keycloak ログイン画面のカスタマイズ手順：テーマ作成・ロゴ差し替えと日本語メッセージの上書き

Keycloak ログイン画面のカスタマイズ手順：テーマ作成・ロゴ差し替えと日本語メッセージの上書き

Keycloakのログイン画面は、テーマを作って既定の画面を継承させれば、本体に手を入れずにロゴ・配色・文言を変えられます。本記事は2026年11月6日時点の最新版Keycloak 26.8.2を前提に、既定のログインテーマkeycloak.v2を継承するカスタムテーマの作り方、CSS変数でロゴを差し替える設定、日本語のメッセージを自社の用語に上書きする2つの方法を順に解説します。後半で比較するのは、FreeMarkerテンプレートの上書きやKeycloakifyでReact製の画面を作る方法と、それぞれの版上げにかかる手間です。

まとめ：ログイン画面はkeycloak.v2継承のテーマとCSSでの改修が基本

ロゴ・色・背景の変更は、keycloak.v2を親にしたテーマにCSSを1枚足すだけで済みます。文言は、テーマにmessages_ja.propertiesを置くか、管理画面のLocalizationタブで上書きします。どちらも既定のテンプレートをそのまま使うため、版を上げても追随の作業がほとんど出ません。

画面の構造を変えたい場合だけ、FreeMarkerテンプレートを上書きします。ただし上書きしたテンプレートは、版上げのたびに差分の確認が必要です。ログイン以外の画面まで自社のデザインで作り込み、Reactを保守できる体制があるなら、Keycloakifyが候補に入ります。

Keycloakのログイン画面を変える4つの手段と改修範囲ごとの選び分け

ここで扱うのは、利用者がサインインするときに見る画面の見た目と文言です。どの順に何を確かめるかという認証の手順は画面ではなくフローの設定で決まり、Keycloak 認証フローの設定手順で解説しています。

管理画面の表示名・ローカライズ上書き・テーマ・Keycloakifyの守備範囲

変えたい範囲が狭いほど、軽い手段で足ります。

手段 変えられる範囲 サーバー作業 版上げ時の手間
レルムの表示名 画面上部の名称・ロゴの枠 不要 ほぼなし
Localizationタブ 個々の文言 不要 ほぼなし
カスタムテーマ CSS・画像・文言・一部の画面 テーマの配置 上書きした画面の確認
Keycloakify 画面全体をReactで作る JARの配置 ライブラリの更新と再ビルド

レルムの表示名は、管理画面のRealm settingsで変えられる見出しの文字列です。26.8.2のRealmBean.javaを読むと、HTML表示名が空なら表示名、それも空ならレルム名が出る作りです。社名を出すだけなら、テーマを作る前にここを埋めれば足ります。

26.0.0で既定になったkeycloak.v2とPatternFly 5のクラス

26.0.0のリリースノートによると、新しいレルムの既定のログインテーマはkeycloak.v2です。ログインテーマを明示していなかった既存のレルムも、keycloak.v2に切り替わりました。旧版のkeycloak（v1）は非推奨で、将来削除される予定です。

keycloak.v2のtheme.propertiesは、親をbaseにし、PatternFly 5のCSSを読み込む構成です。kcFormClass=pf-v5-c-form pf-v5-u-w-100のように、画面の部品ごとのクラスがプロパティで定義されています。darkMode=trueも入っており、OSやブラウザの設定に合わせて暗い配色に切り替わります。古い解説記事がPatternFly 3や4のクラス名でCSSを書いている場合、そのままでは当たりません。

keycloak.v2を継承するカスタムテーマの作成とロゴ・配色を差し替えるCSS

例として、レルムcorpに、テーマcorpを当てます。UI Customization GuideのCreating a themeは、同梱のテーマを直接編集せず、拡張するよう求めています。

テーマの配置先とtheme.propertiesのparentとstylesの書き方

サーバーのthemesディレクトリに、テーマ名・画面の種類の順でディレクトリを切ります。既定のテーマはkeycloak-themesのJARに同梱されているため、themesは初めは空です。

themes/
└── corp/
    └── login/
        ├── theme.properties
        ├── footer.ftl
        ├── messages/
        │   └── messages_ja.properties
        └── resources/
            ├── css/corp.css
            └── img/corp-logo.svg

# themes/corp/login/theme.properties
parent=keycloak.v2
import=common/keycloak
styles=css/styles.css css/corp.css

stylesには親のCSSを先に、自分のCSSを最後に書きます。Add a stylesheet to a themeの節のとおり、後ろに書いたCSSが親の指定を上書きするためです。親のcss/styles.cssを外すと、ロゴや背景を指定している既定のCSSが読み込まれません。

CSS変数–keycloak-logo-urlでロゴと背景画像を替える設定

keycloak.v2のstyles.cssは、ロゴ・背景・カード上端の色を:rootのCSS変数で持っています。変数の値だけを差し替えれば、セレクタを書き写す必要はありません。

/* themes/corp/login/resources/css/corp.css */
:root {
  --keycloak-logo-url: url('../img/corp-logo.svg');
  --keycloak-logo-height: 48px;
  --keycloak-logo-width: 220px;
  --keycloak-bg-logo-url: none;
  --keycloak-card-top-color: #0b5fa5;
}
.login-pf body {
  background-color: #f3f5f8;
}

ロゴはkc-logo-textクラスの要素に背景画像として描かれます。masterレルムの表示名HTMLには、Version.javaで定義されたkc-logo-textの要素が入った状態です。新しく作ったレルムは空なので、ロゴを出すにはHTML表示名を設定します。

kcadm.sh update realms/corp \
  -s 'displayNameHtml=<div class="kc-logo-text"><span>Corp</span></div>' \
  -s loginTheme=corp

中のspanは既定のCSSで非表示になり、画面には画像だけが出ます。レルムの設定をAPIで変える流れはKeycloak APIの使い方にまとめました。

開発中にテーマのキャッシュを切る3つの起動オプションと本番の戻し

Keycloakはテーマとテンプレートをキャッシュするため、CSSを直しても再起動まで画面に出ません。UI Customization Guideは、開発中に次の3つのオプションでキャッシュを切る方法を示しています。

bin/kc.sh start-dev \
  --spi-theme--static-max-age=-1 \
  --spi-theme--cache-themes=false \
  --spi-theme--cache-templates=false

この指定は、開発中に使い、本番では外す設定です。キャッシュを有効にしたまま入れ替えた場合は、data/tmp/kc-gzip-cacheを消してから再起動します。ブラウザ側のキャッシュが残っている場合もあるため、確認はシークレットウィンドウで行うと切り分けが速くなります。

ログイン画面の日本語化とメッセージを自社の用語に上書きする2つの方法

日本語の翻訳ファイルは標準で同梱されています。画面を日本語で出すにはレルムの国際化を有効にする必要があり、その手順はKeycloakとはの日本語化の章で解説しました。ここでは、既定の訳語を自社の用語に変える方法を扱います。

テーマ側messages_ja.propertiesでの文言上書きとキー名の調べ方

キー名は、26.8.2のmessages_ja.propertiesで探せます。たとえば見出しの「アカウントにサインイン」はloginAccountTitle、誤入力時の「無効なユーザー名またはパスワードです。」はinvalidUserMessageです。

# themes/corp/login/messages/messages_ja.properties
loginAccountTitle=社員アカウントでサインイン
usernameOrEmail=社員番号またはメールアドレス
invalidUserMessage=社員番号またはパスワードが違います。
doForgotPassword=パスワードを忘れた場合

書くのは変えたいキーだけです。UI Customization Guideは、親を継承したテーマは親のメッセージを全て引き継ぎ、個別に上書きできると説明しています。ファイルの文字コードは、23.0.0からUTF-8が既定になりました。英語の画面も変えるなら、同じキーをmessages_en.propertiesにも書きます。

管理画面とAdmin REST APIによるレルム単位の文言上書き

テーマを作らずに文言だけ変える方法もあります。Server Administration Guideの国際化の節は、テーマが持つ全ての文言を、Localizationタブでレルム固有の文言に上書きできると書いています。

複数の環境へ同じ設定を入れるなら、Admin REST APIのlocalizationを使います。RealmLocalizationResource.javaを読むと、言語単位のPOSTはJSONのキーと値の組をまとめて受け取ります。1件ずつのPUTは本文をtext/plainで受け取る仕様です。

TOKEN=$(curl -s https://auth.example.com/realms/master/protocol/openid-connect/token \
  -d grant_type=password -d client_id=admin-cli \
  -d username=admin -d password="$ADMIN_PASSWORD" | jq -r .access_token)

curl -s -X POST https://auth.example.com/admin/realms/corp/localization/ja \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"loginAccountTitle":"社員アカウントでサインイン","doLogIn":"ログイン"}'

テーマとLocalizationタブの両方に同じキーがあると、レルムの値が使われます。どちらで管理するかを先に決めておかないと、テーマを直したのに画面が変わらない事態になります。文言の管理を運用担当に任せるならLocalizationタブ、コードと一緒に版管理するならテーマ、という分け方が扱いやすい構成です。

26.5.0以降のメッセージでHTMLと文字参照が使えない制約

Upgrading Guideの26.5.0の節によると、ログインテーマのメッセージではHTMLもHTMLの文字参照も使えなくなりました。例外は、利用規約の同意画面で使うtermsTextだけです。

古い版で&nbsp;やbrタグを文言に入れていた場合、26.5.0以降は記号がそのまま画面に出ます。文字参照はUTF-8の文字に置き換え、改行や太字が要るならテンプレート側で組みます。

FreeMarkerテンプレートの上書きとフッター追加で画面の構造を変える場面

CSSと文言で足りない変更は、テンプレートで行います。KeycloakはApache FreeMarkerでサーバー側でHTMLを組み立てるため、テーマに同じ名前の.ftlを置くとその画面だけが差し替わります。

footer.ftlだけを置いて問い合わせ先リンクを足す26.0.0以降の方法

「ログインできない場合の問い合わせ先」を足すだけなら、login.ftlは触りません。keycloak.v2のtemplate.ftlはfooter.ftlを読み込んでおり、既定の中身は空のマクロです。

<#-- themes/corp/login/footer.ftl -->
<#macro content>
  <ul id="kc-login-footer-links">
    <li><a href="https://intra.example.com/help/login">ログインできない場合の問い合わせ先</a></li>
  </ul>
</#macro>

この仕組みはAdding a custom footer to a login themeの節で案内されています。フッターが入るのはカードの下で、全ての画面に共通です。

login.ftlを丸ごとコピーした場合に版上げで追随が必要になる箇所

Creating a custom HTML templateの節は、組み込みのテンプレートをなるべく使い、見た目はCSSで変えるよう勧めています。テンプレートを上書きすると、新しい版で更新が必要になる場合があるからです。

上書きしたテンプレートは、元の版の改修を取り込みません。26.6系でlogin.ftlをコピーしたテーマは、26.7.0で入ったボタンの横並びの統一も、26.8.0のIdPボタンの再設計も反映されない状態で残ります。上書きは、入力欄の並べ替えや注意書きの常設など、CSSで書けない変更に限ります。

クライアント単位のlogin_theme属性でアプリごとに画面を分ける設定

取引先向けのポータルだけ別の画面にしたい場合は、クライアントにログインテーマを指定します。DefaultThemeSelectorProvider.javaは、クライアントのlogin_theme属性があればそれを使い、無ければレルムのテーマを使います。

CID=$(kcadm.sh get clients -r corp -q clientId=partner-portal --fields id --format csv --noquotes)
kcadm.sh update clients/"$CID" -r corp -s 'attributes.login_theme=partner'

管理画面では、クライアントの設定画面のLogin settingsにあるLogin themeで同じ指定ができます。SSO済みの利用者は画面を見ずに通過するため、テーマの違いが表に出るのは最初のログインのときです。

JARにまとめた本番配備とKeycloakifyでReact製の画面を作る選択肢

開発中はディレクトリに置いたテーマで確かめ、本番にはJARで入れます。Deploying themesの節も、版の管理がしやすいアーカイブを本番向けとしています。

keycloak-themes.jsonを含むJARの作成とprovidersへの配置

JARには、テーマ名と画面の種類を書いたMETA-INF/keycloak-themes.jsonを入れます。テーマの本体はtheme/の下に置きます。

# corp-theme/META-INF/keycloak-themes.json
{ "themes": [ { "name": "corp", "types": ["login", "email"] } ] }

# corp-theme/theme/corp/login/ に themes/corp/login の中身を置いて固める
jar cf corp-theme.jar -C corp-theme .
cp corp-theme.jar /opt/keycloak/providers/
/opt/keycloak/bin/kc.sh build

同じ節は、FreeMarkerのテンプレートがサーバーで実行されるため、悪意のあるテンプレートはKeycloakの権限で任意のコードを動かせると注意しています。themesとprovidersに書き込める人を絞り、配布元の分からないテーマは入れません。コンテナでの組み込み方はKeycloak Dockerの本番構成で解説しています。

Keycloakify 11.16系のビルドで出る2つのJARと対象バージョン

Keycloakifyは、ログイン画面をReactで書き、Keycloakのテーマとして固めるMITライセンスのOSSです。Keycloakの公式の一部ではありません。2026年11月6日時点の最新版は11.16.4（10月21日公開）で、keycloakify-starterから始めます。

git clone https://github.com/keycloakify/keycloakify-starter
cd keycloakify-starter
yarn install
npm run build-keycloak-theme   # 内部で vite build と keycloakify build を実行。Maven が必要
ls dist_keycloak/

Keycloakifyの配備の手順によると、出力されるJARは2つです。Keycloak 26以降で使うのはkeycloak-theme-for-kc-all-other-versions.jarで、もう1つのkeycloak-theme-for-kc-22-to-25.jarは22〜25向けです。配置先は自作のテーマと同じprovidersで、Realm settingsのThemesタブで選びます。

ログイン画面の改修を自前テーマで済ませる条件とKeycloakifyを選ぶ条件

手段の選び方は、変えたい画面の数と、版上げを誰が受け持つかで決まります。

CSSとメッセージで足りる要件にテンプレート上書きを持ち込まない判断

ロゴ・色・背景・文言・問い合わせ先の追加までなら、テンプレートは1枚も上書きしません。CSS変数とmessages_ja.propertiesとfooter.ftlだけのテーマは、版を上げても既定の画面の改修がそのまま入ります。社内向けのSSOの入口を整える案件の多くは、この範囲に収まります。

上書きが必要になるのは、入力欄の並びを変える、画面に固定の注意書きを出す、といった構造の変更です。その場合も、上書きする.ftlは必要な画面だけに絞ります。login.ftl・register.ftl・login-reset-password.ftlの3画面を超えて上書きが増えるなら、次の項のKeycloakifyと手間を比べます。

Keycloakifyの導入が見合う画面数とReactの保守体制の目安

Keycloakifyが見合うのは、ログイン・登録・パスワード再設定・アカウント画面まで、自社のデザインシステムで揃えたい場合です。ReactのコンポーネントとStorybookで画面を確かめられるため、フロントエンドの担当者がFreeMarkerを覚えずに済みます。

見送るべき場面もはっきりしています。社内にReactの保守担当がいない、ロゴと色を変えたいだけ、という場合は過剰です。Keycloakifyの更新とKeycloakの更新の両方を追うことになり、ビルドにNode.jsとMavenが要ります。マネージドの認証サービスと比べると、画面の自由度と引き換えに保守を自社で持つ形です。比較の材料として、AWS Cognito Hosted UIのカスタマイズでは変えられる範囲が設定項目に限られる様子をまとめています。

26.7.0と26.8.0の画面変更から見る版上げ時の確認リスト

Keycloakは、GitHubの公開日（UTC）で26.8.0が10月1日、26.8.1が10月13日、26.8.2が11月5日と、短い間隔で版が出ます。Upgrading Guideには、ログイン画面に関わる変更が毎回のように載っています。

  1. 26.8.0のIdPボタンの再設計：social-providers.ftlを上書きしたテーマや、IdPのアイコンを狙ったCSSは表示が崩れる可能性がある
  2. 26.7.0の画面変更：操作ボタンの横並びの統一、パスキーの画面での機器ごとのアイコン表示
  3. 26.5.0のメッセージのHTML不可：自作のmessages_*.propertiesとLocalizationタブの値を確認する

版上げの前に、検証環境で自社テーマのログイン・パスワード再設定・外部IdPのボタンの3画面を開いて比べる手順を、更新作業の一覧に入れてください。更新の判断の進め方はKeycloakの脆弱性対応の手順で扱いました。ログイン画面の設計から、テーマやKeycloakifyの開発、版上げの検証まで任せたい場合は、一創の認証基盤・ID管理システム開発で支援しています。

Keycloakのログイン画面カスタマイズで導入担当者からよく受ける質問

ログイン画面を変えるときに出やすい疑問をまとめました。

ログイン画面が英語のまま日本語にならないのはなぜですか？

レルムの国際化が無効のままだと、ブラウザが日本語を求めても英語で表示されます。翻訳ファイルは同梱されているため、テーマを作る必要はありません。Realm settingsのLocalizationタブで国際化を有効にし、対応言語に日本語を加えます。既定の言語や、言語を選ぶ優先順位の考え方はKeycloakとはの日本語化の章にまとめました。訳語を変えたいときは、本記事のmessages_ja.propertiesかLocalizationタブで上書きします。

テーマのCSSを直したのに画面に反映されないのはなぜですか？

原因の切り分けでは、次の3つを確認してください。1つ目はサーバーのテーマのキャッシュで、開発中はキャッシュを切るオプションを付けて起動します。2つ目はブラウザのキャッシュで、シークレットウィンドウで開く方法が切り分けに有効です。3つ目はテーマの割り当てで、レルムでは新しいテーマを選んでいても、クライアントにlogin_theme属性が残っていればそちらが使われます。theme.propertiesのstylesに自分のCSSを書き忘れている例も多く見られます。

Dockerで動かすKeycloakにテーマを入れるにはどうしますか？

開発中は、テーマのディレクトリをコンテナの/opt/keycloak/themesにマウントすれば、キャッシュを切った状態で編集をすぐ確かめられます。本番では、テーマをJARに固め、独自のイメージを作るDockerfileで/opt/keycloak/providersへコピーし、kc.sh buildまで済ませておく形が扱いやすい構成です。起動のたびにマウントする方式より、どの版のテーマが入っているかをイメージのタグで追えます。Composeでの本番構成はKeycloak Dockerの本番構成で解説しています。

ログインを拒否したときのエラーメッセージも変えられますか？

変えられます。ユーザー名やパスワードの誤りはinvalidUserMessage、無効化されたアカウントはaccountDisabledMessageのように、画面に出る文言を決めるのはメッセージのキーです。キーをmessages_ja.propertiesかLocalizationタブで上書きすれば、自社の問い合わせ先を添えた文に変えられます。認証フローのDeny Accessで止めた場合の文言は、実行ステップの設定で指定します。フローの組み方はKeycloak 認証フローの設定手順で扱いました。

ログイン画面に外部IdPのボタンを出すのもテーマで行いますか？

ボタンを出すかどうかは、テーマではなくIdentity Providersの設定で決まります。外部IdPを登録すると、ログイン画面に自動でボタンが並びます。テーマで変えられるのは見た目だけで、26.8.0ではこのボタンの配置とアイコンが作り直されました。Entra IDを外部IdPにする手順はKeycloak SAML設定：Entra IDを外部IdPにする手順と属性マッパー、ボタンを飛ばして直接外部IdPへ送る指定はKeycloak SSOの設定手順で解説しています。

関連記事

お気に入りに入れた記事の一覧

一創の公式 SNS

X では毎朝の新着記事と IT ニュースの速報を、YouTube・TikTok・Instagram・LinkedIn・Facebook では記事の解説動画を配信しています。

この記事は以下の記事からリンクされています

この記事に関連するサービス

資料請求

今日のトレンド記事 直近 24 時間で、いつもより多く読まれている記事

  1. 2026.11.05　テックブログ Linuxカーネルの脆弱性CVE-2026-98432：修正版の見分け方とnftablesの緩和策
  2. 2026.11.04　テックブログ CVE-2026-119977：WordPress更新中のRCEと安全な更新手順
  3. 2026.11.03　テックブログ クラブツーリズム不正アクセス：約432万件の対象確認と偽メールの見分け方・流出検知の設計
  4. 2026.10.29　テックブログ ソニー生命の情報漏洩38.5万件｜ログインできない理由、再開状況と窓口の電話番号
  5. 2026.11.05　コラム 給与支払報告書とは？令和8年分の提出期限・書き方と源泉徴収票みなし提出への対応

RELATED POSTS 関連記事

一覧へ戻る

目次