この記事について

今回はkeycloakに非管理者としてログインする時の画面のテーマの変更を行います。Keycloak Server Guide(日本語)を参考にして新しいテーマを作成していきます。

{
    "themes": [{
        "name" : "base",
        "types": [ "admin", "account", "login", "email" ]
    }, {
        "name" : "keycloak",
        "types": [ "admin", "account", "login", "common", "email", "welcome" ]
    }, {
        "name" : "keycloak-preview",
        "types": [ "account" ]
    }, {
        "name" : "mytheme",
        "types": [ "login", "welcome" ]
    }]
}

追加できるテーマは、admin, account, login, common, email, welcomeですが、今回追加したいのはwelcome画面とログイン画面だけなので"login"と"welcome"しか追加しません

テーマのデザイン

themes/src/main/resources/themeの配下に新しくmythemeというフォルダを作ります

keycloakの既存のデザインを元に作るので、resources/theme/keycloakのloginとwelcomeをmythemeの中にコピペします

持ってきたフォルダにはresourcesというフォルダとtheme.propertiesがあると思います

theme.propertiesは触らなくていいです

resourcesの中にスタイルシート、画像、メッセージ・バンドルやスクリプトのフォルダを作り中身を入れていきます

・スタイルシート -> css/styles.css
・画像 -> img
・スクリプト -> js
・メッセージ -> messages/messages_en.properties

メッセージとスクリプトに関して詳しく知りたい方はKeycloak Server Guideの3.4.5と3.4.6をご覧ください

Freemarkerの章で複数のftlと言いました

keycloakではbaseというデザインの中にtemplate.ftlという雛形のftlファイルがあり、これと各テーマに合ったftlファイルを結合させていきます

結合させるftlは各テーマのフォルダの中に{テーマ}.ftlという名前で格納します。

といってもフルスクラッチは難しいので、全てのデザインの元となっているtheme/baseの中のftlを持ってきます

例えば、loginテーマを変更する場合はthemes/src/main/resources/theme/base/login/login.ftlをthemes/src/main/resources/theme/mytheme/loginに置き、HTMLの文法で変更していきます

キャッシュの無効化

テーマを作成する際は、キャッシュを無効にすることをお勧めします

これにより再起動せずに管理者コンソールのthemeディレクトリーから直接テーマを選択できる様になります

方法は、distribution/server-dist/target/keycloak-8.0.0-SNAPSHOT/standalone/configuration/standalone.xmlを編集します

$KEYCLOAK_HOME/distribution/server-dist/target/keycloak-8.0.0-SNAPSHOT/standalone/configuration/standalone.xml

<theme>
    <staticMaxAge>-1</staticMaxAge>
    <cacheThemes>false</cacheThemes>
    <cacheTemplates>false</cacheTemplates>
    ...
</theme>

パフォーマンスには影響が出るので、プロダクション環境では有効にしてください

まとめ

僕が最初これに取り組んだときはftlにこんがらがっていましたが、よくよく見るとただのHTMLなので全然平気です
雛形のtemplateと分岐ができるHTMLという事で拡張性が上がっていると同時に必要以上に複雑になっていますね
いまだにtemplate.ftlとlogin.ftlがどうやって混ざっているのかわかりません(笑)

参考文献

Keycloakのカスタマイズポイントを整理してみる
 [Java] Robotクラスを使ってマウスを自動操作する方法
 Keycloak Server Guide(日本語)
Freemarkerを使用したフロント開発入門

Keycloakのテーマをカスタマイズする

この記事について

目次

準備

Freemarkerとは

テーマの追加

テーマのデザイン

キャッシュの無効化

まとめ

参考文献