Keycloakのテーマのカスタマイズ - 開発者ドキュメント

1. 概要

Keycloak は、オープンソースのIDおよびアクセス管理またはIAMソリューションであり、Webまたはモバイルアプリケーションの認証および承認要件を管理するためのサードパーティの承認サーバーとして使用できます。

このチュートリアルでは、 Keycloakサーバーのテーマをカスタマイズして、エンドユーザー向けのWebページのルックアンドフィールを変える方法に焦点を当てます。

まず、スタンドアロンのKeycloakサーバーの観点から背景を確立します。後のセクションでは、埋め込まれた例のコンテキストで同様の例を見ていきます。

そのために、は以前の記事に基づいて構築します：Spring Bootアプリケーションに埋め込まれたKeycloakとKeycloakを使用するためのクイックガイド。したがって、始めたばかりの人にとっては、最初にそれらを確認することをお勧めします。

2. Keycloakのテーマ

2.1. デフォルトのテーマ

いくつかのテーマはKeycloakで事前に構築されており、ディストリビューションにバンドルされています。

スタンドアロンサーバーの場合、これらは、 keycloak- / themes ディレクトリ：

base ：HTMLテンプレートとメッセージバンドルを含む骨格テーマ。カスタムテーマを含むすべてのテーマは、通常、それを継承します
keycloak ：ページを美しくするための画像とスタイルシートが含まれています。カスタムテーマを提供しない場合、これはデフォルトで使用されるテーマです

既存のテーマを変更することはお勧めしません。代わりに、上記の2つのうちの1つを拡張する新しいテーマを作成する必要があります。

新しいカスタマイズされたテーマを作成するには、テーマディレクトリに新しいフォルダを追加する必要があります。これをカスタムと呼びましょう。完全なオーバーホールが必要な場合は、baseフォルダーからコンテンツをコピーするのがキックスタートの最良の方法です。

このデモでは、すべてを置き換える予定はないため、keycloakディレクトリからコンテンツを取得するのが実用的です。

次のセクションで説明するように、 custom には、オーバーライドするテーマタイプのコンテンツのみが必要であり、keycloakフォルダー全体は必要ありません。

2.2. テーマの種類

Keycloakは、次の6種類のテーマをサポートしています。

共通：フォントなどの一般的なアイテム用。他のテーマタイプによってインポートされます
ようこそ：ランディングページ用
ログイン：ログイン、OTP、付与、登録、およびパスワードを忘れた場合のページ
アカウント：ユーザーアカウント管理ページ用
管理コンソール：管理コンソール用
Eメール：サーバーから送信されるEメール用

上記のリストの最後の4つのテーマは、スタンドアロンサーバーの管理コンソールを介して設定できます。 themes ディレクトリに新しいフォルダを作成すると、サーバーの再起動後に選択できるようになります。

クレデンシャルinitial1 / zaq1！QAZ を使用して管理コンソールにログインし、レルムのテーマタブに移動します。

特に、テーマはレルムごとに設定されているため、レルムごとに異なるテーマを設定できます。ここでは、SpringBootKeycloakレルムのユーザーアカウント管理用のカスタムテーマを設定しています。

2.3. テーマタイプの構造

デフォルトのテーマセクションで概説されているHTMLテンプレート、メッセージバンドル、画像、スタイルシートとは別に、Keycloakのテーマは、テーマのプロパティとスクリプトという2つの要素で構成されています。

各テーマタイプには、theme.propertiesファイルが含まれています。例として、accountタイプのこのファイルを見てみましょう。

parent=base
import=common/keycloak

styles=css/account.css
stylesCommon=node_modules/patternfly/dist/css/patternfly.min.css node_modules/patternfly/dist/css/patternfly-additions.min.css

ご覧のとおり、このテーマは base テーマから拡張され、すべてのHTMLとメッセージのバンドルを取得し、 common テーマをインポートして、からいくつかのスタイルを含めます。それ。それとは別に、独自のスタイル css /account.cssも定義します。

スクリプトはオプション機能です。特定のテーマタイプのテンプレートに合わせたJavaScriptファイルを含める必要がある場合は、 resources /jsディレクトリを作成してそこに保持できます。次に、それらをtheme.propertiesに含める必要があります。

scripts=js/script1.js js/script2.js

2.4. カスタマイズの追加

さあ、楽しい部分に移りましょう！

アカウント管理ページの例を見て、外観を変更する方法を見てみましょう。正確には、ページに表示されるロゴを変更します。

すべての変更を行う直前に、 http：// localhost：8180 / auth / realms / SpringBootKeycloak /accountで入手できる元のテンプレートを以下に示します。

ロゴを自分のものに変えてみましょう。そのためには、 themes /customディレクトリ内にaccountという新しいフォルダを追加する必要があります。必要な要素がすべて揃うように、 themes /keycloakディレクトリからコピーします。

これで、新しいロゴファイル、たとえばbaeldung.pngをcustomディレクトリのresources/ img に追加し、resources/を変更するだけです。 css / account.css ：

.navbar-title {
    background-image: url('../img/baeldung.png');
    height: 25px;
    background-repeat: no-repeat;
    width: 123px;
    margin: 3px 10px 5px;
    text-indent: -99999px;
}

.container {
    height: 100%;
    background-color: #fff;
}

そして、これがページが今どのように見えるかです：

重要なことに、開発フェーズでは、サーバーを再起動せずに、変更の効果をすぐに確認したいと思います。これを有効にするには、 Standalone /configurationフォルダーにあるKeycloakのstandalone.xmlにいくつかの変更を加える必要があります。

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

ここでアカウントテーマをカスタマイズしたのと同様に、他のテーマタイプのルックアンドフィールを変更するには、 admin 、 email、という新しいフォルダーを追加する必要があります。 ]またはloginを選択し、同じプロセスに従います。

2.5. ウェルカムページのカスタマイズ

ウェルカムページをカスタマイズするには、まず、Standalone.xmlに行を追加する必要があります。

<theme>
    ...
    <welcomeTheme>custom</welcomeTheme>
    ... 
</theme>

次に、 themes /customの下にwelcomeフォルダーを作成する必要があります。繰り返しになりますが、index.ftlとtheme.propertiesを、既存のresourcesとともにデフォルトのkeycloakテーマディレクトリからコピーするのが賢明です。

それでは、このページの背景を変更してみましょう。

http：// localhost：8180 / auth / に移動して、最初の外観を確認しましょう。

背景画像を変更するには、 geo.png、などの新しい画像を themes / custom / welcome / resources 内に保持してから、 resources / css/welcome.cssを編集します。 ：

body {
    background: #fff url(../geo.png);
    background-size: cover;
}

効果は次のとおりです。

3. 組み込みKeycloakサーバーのカスタマイズ

組み込みKeycloakサーバーは、定義上、マシンにIAMプロバイダーがインストールされていないことを意味します。したがって、 themes.propertiesやCSSファイルなど、必要なすべてのアーティファクトをソースコードに保持する必要があります。

SpringBootプロジェクトのsrc/ main / resources /themesフォルダーにそれらを保持するのに適した場所です。

もちろん、テーマ構造のファイルは同じであるため、それらをカスタマイズする方法もスタンドアロンサーバーと同じです。

ただし、Keycloakサーバーにカスタムテーマからコンテンツを取得するように指示するために、いくつかの設定を行う必要があります。

3.1. レルム定義ファイルの変更

まず、特定のテーマタイプにカスタムテーマを指定する方法を見てみましょう。

スタンドアロンサーバーの場合、管理コンソールのテーマページで、アカウントテーマのドロップダウンからカスタムテーマを追加したことを思い出してください。

ここで同じ効果を得るには、レルム定義ファイルbaeldung-realm.jsonに行を追加する必要があります。

"accountTheme": "custom",

そして、それが私たちに必要なすべてです。 ログインやメールなどの他のすべてのタイプは、引き続き標準のテーマに従います。

3.2. カスタムテーマディレクトリへのリダイレクト

次に、上記のcustomテーマがどこにあるかをサーバーに伝える方法を見てみましょう。

これはいくつかの方法で実行できます。

組み込みサーバーのブートアプリを起動するときに、VM引数としてテーマディレクトリを指定できます。

mvn spring-boot:run -Dkeycloak.theme.dir=/src/main/resources/themes

プログラムで同じことを実現するために、@SpringBootApplicationクラスのシステムプロパティとして設定できます。

public static void main(String[] args) throws Exception {
    System.setProperty("keycloak.theme.dir","src/main/resources/themes");
    SpringApplication.run(JWTAuthorizationServerApp.class, args);
}

または、keycloak-server.jsonでサーバー構成を変更できます。

"theme": {
    ....
    "welcomeTheme": "custom",
    "folder": {
        "dir": "src/main/resources/themes"
    }
},

特に、ここでは welcomeTheme 属性も追加して、ウェルカムページをカスタマイズできるようにしました。

前述のように、CSSファイルと画像に対する他のすべての変更は同じままです。

ウェルカムページへの変更を表示するには、組み込みサーバーを起動し、 http：// localhost：8083 /authに移動する必要があります。

アカウント管理ページはhttp：// localhost：8083 / auth / realms / baeldung / account で利用でき、次の資格情報を使用してアクセスできます： john@test.com / 123.

4. 結論

このチュートリアルでは、 Keycloakのテーマ–そのタイプと構造について学びました。

次に、いくつかの事前に作成されたテーマと、それらを拡張してスタンドアロンインスタンスで独自のカスタマイズされたテーマを作成する方法を確認しました。

最後に、組み込みのKeycloakサーバーで同じことを実現する方法を見ました。

いつものように、ソースコードはGitHubで入手できます。スタンドアロンサーバーの場合はチュートリアルGitHubにあり、組み込みインスタンスの場合は OAuthGitHubにあります。