---
title: "Keycloak ログイン画面のカスタマイズ手順：テーマ作成・ロゴ差し替えと日本語メッセージの上書き"
url: "https://www.issoh.co.jp/tech/details/19390/"
published: 2026-11-06
updated: 2026-11-06
categories: ["セキュリティ"]
publisher: "株式会社一創"
---
# 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 認証フローの設定手順](https://www.issoh.co.jp/tech/details/19386/)で解説しています。
### 管理画面の表示名・ローカライズ上書き・テーマ・Keycloakifyの守備範囲
変えたい範囲が狭いほど、軽い手段で足ります。
| 手段 | 変えられる範囲 | サーバー作業 | 版上げ時の手間 |
| -------------- | --------------- | ------ | ------------- |
| レルムの表示名 | 画面上部の名称・ロゴの枠 | 不要 | ほぼなし |
| Localizationタブ | 個々の文言 | 不要 | ほぼなし |
| カスタムテーマ | CSS・画像・文言・一部の画面 | テーマの配置 | 上書きした画面の確認 |
| Keycloakify | 画面全体をReactで作る | JARの配置 | ライブラリの更新と再ビルド |
レルムの表示名は、管理画面のRealm settingsで変えられる見出しの文字列です。[26.8.2のRealmBean.java](https://github.com/keycloak/keycloak/blob/26.8.2/services/src/main/java/org/keycloak/forms/login/freemarker/model/RealmBean.java)を読むと、HTML表示名が空なら表示名、それも空ならレルム名が出る作りです。社名を出すだけなら、テーマを作る前にここを埋めれば足ります。
### 26.0.0で既定になったkeycloak.v2とPatternFly 5のクラス
[26.0.0のリリースノート](https://www.keycloak.org/docs/latest/release%5Fnotes/index.html#new-default-login-theme)によると、新しいレルムの既定のログインテーマはkeycloak.v2です。ログインテーマを明示していなかった既存のレルムも、keycloak.v2に切り替わりました。旧版のkeycloak（v1）は非推奨で、将来削除される予定です。
[keycloak.v2のtheme.properties](https://github.com/keycloak/keycloak/blob/26.8.2/themes/src/main/resources/theme/keycloak.v2/login/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](https://www.keycloak.org/ui-customization/themes#%5Fcreating-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の節](https://www.keycloak.org/ui-customization/themes#%5Ftheme%5Fstylesheet)のとおり、後ろに書いたCSSが親の指定を上書きするためです。親の`css/styles.css`を外すと、ロゴや背景を指定している既定のCSSが読み込まれません。
### CSS変数–keycloak-logo-urlでロゴと背景画像を替える設定
[keycloak.v2のstyles.css](https://github.com/keycloak/keycloak/blob/26.8.2/themes/src/main/resources/theme/keycloak.v2/login/resources/css/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](https://github.com/keycloak/keycloak/blob/26.8.2/common/src/main/java/org/keycloak/common/Version.java)で定義された`kc-logo-text`の要素が入った状態です。新しく作ったレルムは空なので、ロゴを出すにはHTML表示名を設定します。
```
kcadm.sh update realms/corp \
-s 'displayNameHtml=Corp
' \
-s loginTheme=corp
```
中の`span`は既定のCSSで非表示になり、画面には画像だけが出ます。レルムの設定をAPIで変える流れは[Keycloak APIの使い方](https://www.issoh.co.jp/tech/details/19378/)にまとめました。
### 開発中にテーマのキャッシュを切る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とは](https://www.issoh.co.jp/tech/details/7663/)の日本語化の章で解説しました。ここでは、既定の訳語を自社の用語に変える方法を扱います。
### テーマ側messages\_ja.propertiesでの文言上書きとキー名の調べ方
キー名は、[26.8.2のmessages\_ja.properties](https://github.com/keycloak/keycloak/blob/26.8.2/themes/src/main/resources-community/theme/base/login/messages/messages%5Fja.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の国際化の節](https://www.keycloak.org/docs/latest/server%5Fadmin/index.html#enabling-internationalization)は、テーマが持つ全ての文言を、Localizationタブでレルム固有の文言に上書きできると書いています。
複数の環境へ同じ設定を入れるなら、[Admin REST API](https://www.keycloak.org/docs-api/latest/rest-api/index.html)の`localization`を使います。[RealmLocalizationResource.java](https://github.com/keycloak/keycloak/blob/26.8.2/services/src/main/java/org/keycloak/services/resources/admin/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の節](https://www.keycloak.org/docs/latest/upgrading/index.html#message-keys-no-longer-support-html-or-html-entities-in-the-login-theme)によると、ログインテーマのメッセージではHTMLもHTMLの文字参照も使えなくなりました。例外は、利用規約の同意画面で使う`termsText`だけです。
古い版で` `や`br`タグを文言に入れていた場合、26.5.0以降は記号がそのまま画面に出ます。文字参照はUTF-8の文字に置き換え、改行や太字が要るならテンプレート側で組みます。
## FreeMarkerテンプレートの上書きとフッター追加で画面の構造を変える場面
CSSと文言で足りない変更は、テンプレートで行います。KeycloakはApache FreeMarkerでサーバー側でHTMLを組み立てるため、テーマに同じ名前の`.ftl`を置くとその画面だけが差し替わります。
### footer.ftlだけを置いて問い合わせ先リンクを足す26.0.0以降の方法
「ログインできない場合の問い合わせ先」を足すだけなら、`login.ftl`は触りません。[keycloak.v2のtemplate.ftl](https://github.com/keycloak/keycloak/blob/26.8.2/themes/src/main/resources/theme/keycloak.v2/login/template.ftl)は`footer.ftl`を読み込んでおり、既定の中身は空のマクロです。
```
<#-- themes/corp/login/footer.ftl -->
<#macro content>
```
この仕組みは[Adding a custom footer to a login themeの節](https://www.keycloak.org/ui-customization/themes#%5Ftheme%5Fcustom%5Ffooter)で案内されています。フッターが入るのはカードの下で、全ての画面に共通です。
### login.ftlを丸ごとコピーした場合に版上げで追随が必要になる箇所
[Creating a custom HTML templateの節](https://www.keycloak.org/ui-customization/themes#%5Fcreating%5Fa%5Fcustom%5Fhtml%5Ftemplate)は、組み込みのテンプレートをなるべく使い、見た目はCSSで変えるよう勧めています。テンプレートを上書きすると、新しい版で更新が必要になる場合があるからです。
上書きしたテンプレートは、元の版の改修を取り込みません。26.6系で`login.ftl`をコピーしたテーマは、26.7.0で入ったボタンの横並びの統一も、26.8.0のIdPボタンの再設計も反映されない状態で残ります。上書きは、入力欄の並べ替えや注意書きの常設など、CSSで書けない変更に限ります。
### クライアント単位のlogin\_theme属性でアプリごとに画面を分ける設定
取引先向けのポータルだけ別の画面にしたい場合は、クライアントにログインテーマを指定します。[DefaultThemeSelectorProvider.java](https://github.com/keycloak/keycloak/blob/26.8.2/services/src/main/java/org/keycloak/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の節](https://www.keycloak.org/ui-customization/themes#%5Fdeploying%5Fthemes)も、版の管理がしやすいアーカイブを本番向けとしています。
### 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の本番構成](https://www.issoh.co.jp/tech/details/19368/)で解説しています。
### Keycloakify 11.16系のビルドで出る2つのJARと対象バージョン
[Keycloakify](https://github.com/keycloakify/keycloakify)は、ログイン画面をReactで書き、Keycloakのテーマとして固めるMITライセンスのOSSです。Keycloakの公式の一部ではありません。2026年11月6日時点の最新版は11.16.4（10月21日公開）で、[keycloakify-starter](https://github.com/keycloakify/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の配備の手順](https://docs.keycloakify.dev/deploying-your-theme)によると、出力される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のカスタマイズ](https://www.issoh.co.jp/tech/details/3441/)では変えられる範囲が設定項目に限られる様子をまとめています。
### 26.7.0と26.8.0の画面変更から見る版上げ時の確認リスト
Keycloakは、GitHubの公開日（UTC）で26.8.0が10月1日、26.8.1が10月13日、[26.8.2](https://github.com/keycloak/keycloak/releases/tag/26.8.2)が11月5日と、短い間隔で版が出ます。Upgrading Guideには、ログイン画面に関わる変更が毎回のように載っています。
1. [26.8.0のIdPボタンの再設計](https://www.keycloak.org/docs/latest/upgrading/index.html#redesigned-identity-provider-buttons-on-the-login-page)：`social-providers.ftl`を上書きしたテーマや、IdPのアイコンを狙ったCSSは表示が崩れる可能性がある
2. [26.7.0の画面変更](https://www.keycloak.org/docs/latest/upgrading/index.html#login-theme-changes-may-affect-custom-themes)：操作ボタンの横並びの統一、パスキーの画面での機器ごとのアイコン表示
3. 26.5.0のメッセージのHTML不可：自作の`messages_*.properties`とLocalizationタブの値を確認する
版上げの前に、検証環境で自社テーマのログイン・パスワード再設定・外部IdPのボタンの3画面を開いて比べる手順を、更新作業の一覧に入れてください。更新の判断の進め方は[Keycloakの脆弱性対応の手順](https://www.issoh.co.jp/tech/details/19094/)で扱いました。ログイン画面の設計から、テーマやKeycloakifyの開発、版上げの検証まで任せたい場合は、一創の[認証基盤・ID管理システム開発](https://www.issoh.co.jp/service/system/identity/)で支援しています。
## Keycloakのログイン画面カスタマイズで導入担当者からよく受ける質問
ログイン画面を変えるときに出やすい疑問をまとめました。
### ログイン画面が英語のまま日本語にならないのはなぜですか？
レルムの国際化が無効のままだと、ブラウザが日本語を求めても英語で表示されます。翻訳ファイルは同梱されているため、テーマを作る必要はありません。Realm settingsのLocalizationタブで国際化を有効にし、対応言語に日本語を加えます。既定の言語や、言語を選ぶ優先順位の考え方は[Keycloakとは](https://www.issoh.co.jp/tech/details/7663/)の日本語化の章にまとめました。訳語を変えたいときは、本記事の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の本番構成](https://www.issoh.co.jp/tech/details/19368/)で解説しています。
### ログインを拒否したときのエラーメッセージも変えられますか？
変えられます。ユーザー名やパスワードの誤りはinvalidUserMessage、無効化されたアカウントはaccountDisabledMessageのように、画面に出る文言を決めるのはメッセージのキーです。キーをmessages\_ja.propertiesかLocalizationタブで上書きすれば、自社の問い合わせ先を添えた文に変えられます。認証フローのDeny Accessで止めた場合の文言は、実行ステップの設定で指定します。フローの組み方は[Keycloak 認証フローの設定手順](https://www.issoh.co.jp/tech/details/19386/)で扱いました。
### ログイン画面に外部IdPのボタンを出すのもテーマで行いますか？
ボタンを出すかどうかは、テーマではなくIdentity Providersの設定で決まります。外部IdPを登録すると、ログイン画面に自動でボタンが並びます。テーマで変えられるのは見た目だけで、26.8.0ではこのボタンの配置とアイコンが作り直されました。Entra IDを外部IdPにする手順は[Keycloak SAML設定：Entra IDを外部IdPにする手順と属性マッパー](https://www.issoh.co.jp/tech/details/19370/)、ボタンを飛ばして直接外部IdPへ送る指定は[Keycloak SSOの設定手順](https://www.issoh.co.jp/tech/details/19384/)で解説しています。
## 関連記事
- [Keycloakとは？Oktaとの違いと連携手順｜Auth0・Cognito比較で導入を判断【2026年10月】](https://www.issoh.co.jp/tech/details/7663/)：Keycloakの全体像と、ログイン画面を日本語で出す国際化の設定です。
- [Keycloak 認証フローの設定手順：ブラウザフロー複製と条件付きOTP・Required Actions](https://www.issoh.co.jp/tech/details/19386/)：ログイン画面の裏で動く認証の手順を組み替える方法です。
- [Keycloak Dockerの本番構成：Composeでの起動とリバースプロキシ・ヘルスチェックの設定](https://www.issoh.co.jp/tech/details/19368/)：テーマを組み込むコンテナの本番構成です。
- [Keycloak APIの使い方：Admin REST APIでユーザー作成とロール付与をcurlで行う手順](https://www.issoh.co.jp/tech/details/19378/)：表示名や文言の設定をAPIで自動化するときの土台です。
- [Keycloak SSOの設定手順：複数アプリのOIDCクライアント登録とセッション・ログアウト連携](https://www.issoh.co.jp/tech/details/19384/)：複数のアプリから同じログイン画面を使う設定です。
---
出典: [Keycloak ログイン画面のカスタマイズ手順：テーマ作成・ロゴ差し替えと日本語メッセージの上書き]()（株式会社一創）