サーバーガイド

第1章 Red Hat build of Keycloak の設定

この章では、Red Hat build of Keycloak の設定方法と、設定を開始して適用する方法を説明します。これには、Red Hat build of Keycloak を最適化して起動を高速化し、メモリー使用量を減らすための設定ガイドラインが含まれています。

1.1. Red Hat build of Keycloak のソース設定

Red Hat build of Keycloak は、次の 4 つのソースから設定をロードします。ここでは適用順にリストされています。

コマンドラインパラメーター
環境変数
conf/keycloak.conf ファイルまたはユーザーが作成した設定ファイルで定義されたオプション
ユーザーが作成した Java KeyStore ファイルで定義された機密オプション

オプションが複数のソースに設定されている場合、そのオプションの値はリストの最初にあるソースにより決定されます。たとえば、コマンドラインパラメーターにより設定されたオプションの値は、同じオプションの環境変数よりも優先されます。

1.1.1. 例: db-url-host パラメーターの設定

次の例は、db-url 値が 4 つの設定ソースでどのように設定されるかを示しています。

ソース	形式
コマンドラインパラメーター	`--db-url=cliValue`
環境変数	`KC_DB_URL=envVarValue`
設定ファイル	`db-url=confFileValue`
Java KeyStore ファイル	`kc.db-url=keystoreValue`

アプリケーションの優先順位に基づくと、最も優先順位が高いのはコマンドラインであるため、起動時に使用される値は cliValue になります。

--db-url=cliValue が使用されていない場合、適用される値は KC_DB_URL=envVarValue になります。値がコマンドラインまたは環境変数によって適用されていない場合は、db-url=confFileValue が使用されます。前述の値がいずれも適用されていない場合は、使用可能な設定ソースの中で優先順位が最も低い kc.db-url=confFileValue の値が使用されます。

1.2. 設定用の形式

この設定では、ソースごとに統一された 形式が使用されており、キー/値ペアの、ある設定ソースから別の設定ソースへの変換が簡素化されます。この形式は spi オプションにも適用されることに注意してください。

コマンドラインパラメーターの形式: コマンドラインの値には、--<key-with-dashes>=<value> の形式が使用されます。一部の値は、-<abbreviation>=<value> の省略表現もあります。
環境変数の形式: 環境変数の値には、大文字の KC_<key_with_underscores>=<value> 形式が使用されます。
設定ファイルの形式: 設定ファイルに格納される値には、<key-with-dashes>=<value> 形式が使用されます。
KeyStore 設定ファイルの形式: KeyStore 設定ファイルに格納される値には、kc.<key-with-dashes> 形式が使用されます。<value> は、KeyStore に保存されているパスワードです。

設定の各章の最後で、該当する設定形式を定義する 関連オプション の見出しを探してください。すべての設定オプションについては、すべての設定を参照してください。ユースケースに適用できる設定ソースと形式を選択します。

1.2.1. 例 - 設定ソースに基づく代替形式

次の例は、3 つの設定ソースにおける db-url-host の設定形式を示しています。

コマンドラインパラメーター

bin/kc.[sh|bat] start --db-url-host=mykeycloakdb

環境変数

export KC_DB_URL_HOST=mykeycloakdb

conf/keycloak.conf

db-url-host=mykeycloakdb

1.2.2. コマンドラインパラメーターの形式

Red Hat build of Keycloak には、設定用の多くのコマンドラインパラメーターが同梱されています。使用可能な設定形式を確認するには、次のコマンドを入力します。

bin/kc.[sh|bat] start --help

もしくは、すべての設定ですべてのサーバーオプションを確認できます。

1.2.3. 環境変数の形式

${ENV_VAR} 構文を使用することで、keycloak.conf ファイル内の環境変数から環境固有の値をプレースホルダーを使用して解決できます。

db-url-host=${MY_DB_HOST}

環境変数を解決できない場合は、フォールバック値を指定できます。ここで示すとおり、mydb の前に : (コロン) を使用します。

db-url-host=${MY_DB_HOST:mydb}

1.2.4. 特定の設定ファイルを含める形式

デフォルトでは、サーバーは常に conf/keycloak.conf ファイルから設定オプションを取得します。新規インストールの場合、このファイルには、実稼働環境で実行する際の設定案がコメントとして格納されているだけです。

次のコマンドを入力し、[-cf|--config-file] オプションを使用して設定ファイルの場所を明示的に指定することもできます。

bin/kc.[sh|bat] --config-file=/path/to/myconfig.conf start

このオプションを設定すると、Red Hat build of Keycloak は conf/keycloak.conf ではなく指定されたファイルから設定を読み取ります。

1.2.5. Java KeyStore ファイルを使用して機密オプションを設定する

KeyStore 設定ソースにより、[--config-keystore] および [--config-keystore-password] オプションを使用して Java KeyStore からプロパティーを直接ロードできます。必要に応じて、[--config-keystore-type] オプションを使用して KeyStore タイプを指定できます。デフォルトの KeyStore タイプは PKCS12 です。

KeyStore 内のシークレットは、PBE (パスワードベースの暗号化) キーアルゴリズムを使用して保存する必要があります。この場合のキーは、KeyStore のパスワードから導出します。次の keytool コマンドを使用して、このような KeyStore を生成できます。

keytool -importpass -alias kc.db-password -keystore keystore.p12 -storepass keystorepass -storetype PKCS12 -v

コマンドを実行すると、Enter the password to be stored というプロンプトが表示されます。これは、上記の kc.db-password プロパティーの値を表します。

KeyStore が作成されると、次のパラメーターを使用してサーバーを起動できます。

bin/kc.[sh|bat] start --config-keystore=/path/to/keystore.p12 --config-keystore-password=storepass --config-keystore-type=PKCS12

1.2.6. raw Quarkus プロパティーの形式

ほとんどの場合、使用可能な設定オプションでサーバーを設定できます。ただし、Red Hat build of Keycloak 設定に欠けている特定の動作または機能については、基礎となる Quarkus フレームワークのプロパティーを使用できます。

可能であれば、Quarkus から直接プロパティーを使用することは避けてください。それらは Red Hat build of Keycloak でサポートされていません。どうしても必要な場合は、まず機能拡張リクエストを作成することを検討してください。このアプローチは、ニーズに合わせて Red Hat build of Keycloak の設定を改善するのに役立ちます。

拡張リクエストが不可能な場合は、raw Quarkus プロパティーを使用してサーバーを設定できます。

conf ディレクトリーに、quarkus.properties ファイルを作成します。
そのファイルで、必要なプロパティーを定義します。
Quarkus ドキュメントで定義されている Quarkus 拡張機能のサブセットのみ使用できます。以下に示す、Quarkus プロパティーの違いにも注意してください。
- Quarkus ドキュメントに示される Quarkus プロパティーの鍵アイコンは、ビルド時のプロパティーを表しています。このプロパティーを適用するには、build コマンドを実行します。ビルドコマンドの詳細は、Red Hat build of Keycloak の最適化に関する後続セクションを参照してください。
- Quarkus ガイドの鍵アイコンがないプロパティーは、Quarkus および Red Hat build of Keycloak のランタイムプロパティーです。
[-cf|--config-file] コマンドラインパラメーターを使用して、そのファイルを含めます。

同様に、Quarkus プロパティーを Java KeyStore に保存することもできます。

quarkus.http.port や同様の必須プロパティーなど、一部の Quarkus プロパティーはすでに Red Hat build of Keycloak 設定にマップされていることに注意してください。プロパティーが Red Hat build of Keycloak によって使用されている場合、quarkus.properties でそのプロパティーキーを定義しても効果はありません。Red Hat build of Keycloak の設定値は、Quarkus のプロパティー値よりも優先されます。

1.2.7. 値に特殊文字を使用する

Red Hat build of Keycloak は、Quarkus と MicroProfile に依存して設定値を処理します。評価式がサポートされていることに注意してください。たとえば、${some_key} は some_key の値と評価されます。

式の評価を無効にするには、\ 文字をエスケープ文字として使用します。特に、$ で式を定義する場合や $ が繰り返し現れる場合、\ によって $ の使用をエスケープする必要があります。たとえば、設定値 my$$password が必要な場合は、代わりに my\$\$password を使用します。ほとんどの Unix シェルを使用する場合、またはプロパティーファイルに現れる場合は、\ 文字を追加でエスケープするか、引用符で囲む必要があることに注意してください。たとえば、bash で一重引用符を使用すると、単一のバックスラッシュ --db-password='my\$\$password' が保持されます。また、bash で二重引用符を使用する場合は、バックスラッシュがもう 1 つ --db-password="my\\$\\$password" が必要です。同様に、プロパティーファイルでも、バックスラッシュ文字をエスケープする必要があります (kc.db-password=my\\$\\$password)。

1.3. Red Hat build of Keycloak の起動

Red Hat build of Keycloak は、development mode または production mode で起動できます。各モードでは、対象となる環境に応じて異なるデフォルトが提供されます。

1.3.1. Red Hat build of Keycloak を開発モードで起動する

開発モードは、Red Hat build of Keycloak を初めて試す場合に、すばやく起動するために使用します。このモードは、Red Hat build of Keycloak の開発など、開発者にとって便利なデフォルト設定を提供します。

開発モードで起動するには、次のコマンドを入力します。

bin/kc.[sh|bat] start-dev

デフォルト

開発モードでは、次のデフォルト設定が適用されます。

HTTP は有効
厳密なホスト名解決は無効
キャッシュはローカルに設定 (高可用性のため、分散キャッシュメカニズムは使用されません)
テーマとテンプレートのキャッシュは無効

1.3.2. Red Hat build of Keycloak を実稼働モードで起動する

Red Hat build of Keycloak を実稼働環境にデプロイするには、実稼働モードを使用します。このモードは、セキュアバイデフォルト (デフォルトでセキュア) の原則に従います。

実稼働モードで起動するには、次のコマンドを入力します。

bin/kc.[sh|bat] start

追加で設定を行わなければ、このコマンドを実行しても Red Hat build of Keycloak は起動せず、代わりにエラーが表示されます。Red Hat build of Keycloak は セキュアバイデフォルト の原則に従っているため、この応答は意図的なものです。実稼働モードでは、起動時にホスト名を設定し、HTTPS/TLS 設定を使用可能にすることが想定されています。

デフォルト

実稼働モードでは、次のデフォルトが設定されます。

トランスポート層セキュリティー (HTTPS) が必須であるため、HTTP は無効になっています。
ホスト名の設定が想定されています。
HTTPS/TLS の設定が想定されています。

Red Hat build of Keycloak を実稼働環境にデプロイする前に、必ず Red Hat build of Keycloak を実稼働用に設定するに概説されている手順に従ってください。

デフォルトでは、実稼働モードの設定オプション例は、デフォルトの conf/keycloak.conf ファイル内でコメント化されています。これらのオプションは、実稼働環境で Red Hat build of Keycloak を実行する際に考慮すべき主要な設定についてアイデアを提供します。

1.4. 初期管理者ユーザーの作成

初期管理者ユーザーは、ローカル接続 (localhost) を使用してアクセスする Web フロントエンドを使用して作成できます。代わりに、環境変数を使用してこのユーザーを作成することもできます。初期管理者ユーザー名は KEYCLOAK_ADMIN= <username>、初期管理者パスワードは KEYCLOAK_ADMIN_PASSWORD= <password> を設定します。

Red Hat build of Keycloak は、初回起動時にこれらの値を解析して、管理者権限を持つ最初のユーザーを作成します。管理者権限を持つ最初のユーザーが存在する場合は、管理コンソールまたはコマンドラインツール kcadm.[sh|bat] を使用して追加のユーザーを作成できます。

初期管理者がすでに存在し、起動時に環境変数がまだ存在している場合は、初期管理者の作成が失敗したことを示すエラーメッセージがログに表示されます。Red Hat build of Keycloak はこの値を無視し、正しく起動します。

1.5. Red Hat build of Keycloak の起動を最適化する

Red Hat build of Keycloak を実稼働環境にデプロイする前に、Red Hat build of Keycloak を最適化して起動を高速化し、メモリー消費量を改善することが推奨されます。このセクションでは、最適なパフォーマンスと実行時の動作を実現するために、Red Hat build of Keycloak の最適化を適用する方法を説明します。

1.5.1. 最適化された Red Hat build of Keycloak ビルドの作成

デフォルトでは、start または start-dev コマンドを使用すると、Red Hat build of Keycloak は便宜上、内部で build コマンドを実行します。

この build コマンドは、起動時と実行時の動作に対して一連の最適化を実行します。ビルドプロセスには数秒かかる場合があります。特に、Kubernetes や OpenShift などのコンテナー化された環境で Red Hat build of Keycloak を実行する場合、起動時間は重要です。無駄な時間を発生させないために、起動前に build (CI/CD パイプラインの別のステップなど) を明示的に実行します。

1.5.1.1. 最初のステップ: build を明示的に実行する

build を実行するには、次のコマンドを入力します。

bin/kc.[sh|bat] build <build-options>

このコマンドは、入力した build options を表示します。Red Hat build of Keycloak は、build コマンドの実行時に使用できる ビルドオプション と、サーバーの起動時に使用できる 設定オプション を区別します。

Red Hat build of Keycloak の起動が最適化されていない場合、この区別には意味がありません。ただし、起動前に build を実行する場合、build コマンドではオプションのサブセットしか使用できません。この制限は、最適化された Red Hat build of Keycloak イメージに対して build オプションが永続化されることが原因です。たとえば、db-password (設定オプション) などの認証情報の設定は、セキュリティー上の理由から永続化することは禁止されています。

警告

すべてのビルドオプションは、プレーンテキストで保持されます。機密データは、ビルドオプションとして保存しないでください。これは、KeyStore Config Source を含む、使用可能なすべての設定ソースに適用されます。したがって、ビルドオプションを Java KeyStore に保存することも推奨されません。設定オプションに関しては、主に機密データの保存に KeyStore Config Source を使用することが推奨されます。機密性のないデータの場合は、残りの設定ソースを使用できます。

ビルドオプションは、All configuration でツールアイコンでマークされます。利用可能なビルドオプションを見つけるには、次のコマンドを入力します。

bin/kc.[sh|bat] build --help

例: 起動前に build を実行してデータベースを PostgreSQL に設定する

bin/kc.[sh|bat] build --db=postgres

1.5.1.2. 2 番目のステップ: `--optimized` を使用して Red Hat build of Keycloak を起動する

ビルドが成功すると、次のコマンドを入力して Red Hat build of Keycloak を起動し、デフォルトの起動動作をオフにできます。

bin/kc.[sh|bat] start --optimized <configuration-options>

--optimized パラメーターは、Red Hat build of Keycloak に対して、事前にビルドおよび最適化された Red Hat build of Keycloak の使用を前提とするように指示します。その結果、Red Hat build of Keycloak の起動時にビルドの直接確認と実行は行われず、時間が短縮されます。

起動時にすべての設定オプションを入力できます。これらのオプションは、All configuration でツールアイコンが 付いていない オプションです。

起動時に、build の入力時に使用した値と同じ値のビルドオプションが見つかった場合、--optimized パラメーターを使用すると、そのオプションは暗黙的に無視されます。
そのオプションの値が、ビルドの入力時に使用した値と異なる場合、ログに警告が表示され、以前にビルドした値が使用されます。この値を有効にするには、起動する前に新しい build を実行します。

最適化されたビルドを作成する

次の例は、Red Hat build of Keycloak の起動時に、--optimized パラメーターを使用して最適化されたビルドを作成する方法を示しています。

build コマンドを使用して、PostgreSQL データベースベンダーのビルドオプションを設定します。
```
bin/kc.[sh|bat] build --db=postgres
```

conf/keycloak.conf ファイルで、postgres の実行時設定オプションを設定します。

db-url-host=keycloak-postgres
db-username=keycloak
db-password=change_me
hostname=mykeycloak.acme.com
https-certificate-file

最適化されたパラメーターでサーバーを起動します。
```
bin/kc.[sh|bat] start --optimized
```

build コマンドを使用すると、起動時と実行時の動作のほとんどを最適化できます。また、keycloak.conf ファイルを設定ソースとして使用すると、CLI 自体の初期化など、コマンドラインパラメーターが必要となる起動時の一部の手順を回避できます。その結果、サーバーの起動時間がさらに短縮されます。

1.6. 基礎となる概念

このセクションでは、Red Hat build of Keycloak が使用する基礎となる概念、特に起動の最適化にかかわる概念を説明します。

Red Hat build of Keycloak は、Quarkus フレームワークと再拡張/mutable-jar アプローチを内部で使用します。このプロセスは、build コマンドが実行されると開始されます。

以下は、build コマンドにより実行される最適化の一部です。

インストールされているプロバイダーに関する閉世界仮説が作成されます。つまり、Red Hat build of Keycloak の起動ごとに、レジストリーを再作成してファクトリーを初期化する必要がなくなります。
設定ファイルは、サーバー起動時の I/O を削減するために事前に解析されます。
データベース固有のリソースは、特定のデータベースベンダーに対して実行するように設定および準備されています。
ビルドオプションをサーバーイメージに対して永続化すると、サーバーは設定オプションを解釈して自身を (再) 設定するための追加の手順を実行しません。

詳細は、該当する Quarkus ガイドを参照してください。

第2章 Red Hat build of Keycloak を実稼働用に設定する

Red Hat build of Keycloak の実稼働環境は、数千人のユーザーをサポートするオンプレミスのデプロイメントから数百万のユーザーにサービスを提供するデプロイメントまで、幅広いデプロイメントに対してセキュアな認証と認可を提供します。

この章では、実稼働に対応した Red Hat build of Keycloak 環境に必要な設定に関する一般的な情報を提供します。この情報は、環境に応じて異なる実際の実装ではなく、一般的な概念に重点を置いています。この章で説明する重要な側面は、コンテナー化、オンプレミス、GitOps、Ansible のいずれかにかかわらず、すべての環境に当てはまります。

2.1. セキュアな通信のための TLS

Red Hat build of Keycloak は、継続的に機密データを交換します。つまり、Red Hat build of Keycloak との間のすべての通信には、セキュアな通信チャネルが必要です。さまざまな攻撃ベクトルを防ぐには、そのチャネルに対して HTTP over TLS (HTTPS) を有効にします。

Red Hat build of Keycloak のためにセキュアな通信チャネルを設定するには、TLS の設定および送信 HTTP 要求の設定を参照してください。

Red Hat build of Keycloak のキャッシュ通信を保護するには、分散キャッシュの設定を参照してください。

2.2. Red Hat build of Keycloak のホスト名

通常、実稼働環境では、Red Hat build of Keycloak インスタンスはプライベートネットワークで実行されます。しかし、保護すべきアプリケーションと通信するために、Red Hat build of Keycloak は特定のパブリック向けエンドポイントを公開する必要があります。

エンドポイントカテゴリーの詳細と、それらのパブリックホスト名を設定する方法については、ホスト名の設定を参照してください。

2.3. 分散環境でのリバースプロキシー

通常、ホスト名の設定とは別に、実稼働環境にはリバースプロキシー/ロードバランサーコンポーネントが含まれています。これは、会社や組織が使用するネットワークへのアクセスの分離や統合を行います。Red Hat build of Keycloak の実稼働環境では、このコンポーネントが推奨されます。

Red Hat build of Keycloak でプロキシー通信モードを設定する方法の説明は、リバースプロキシーの使用を参照してください。Red Hat build of Keycloak がアプリケーションを保護するために、パブリックアクセスから隠すべきパスと、公開すべきパスに関する推奨も記載されています。

2.4. キューに入れる要求の数の制限

実稼働環境では、過負荷状態から保護して、可能な限り多くの有効な要求に応答し、状況が正常に戻ったときに通常の操作を継続できるようにする必要があります。これを実現する 1 つの方法は、特定のしきい値に達したときに追加の要求を拒否することです。

負荷制限は、環境内のロードバランサーを含むすべてのレベルで実装する必要があります。さらに、Red Hat build of Keycloak には、すぐに処理できないためキューに入れる必要がある要求の数を制限する機能があります。デフォルトでは制限は設定されていません。オプション http-max-queued-requests を設定すると、キューに入れる要求の数を、環境に合わせて特定のしきい値に制限できます。この制限を超える要求には、即時に 503 Server not Available 応答が返されます。

2.5. 実稼働グレードのデータベース

Red Hat build of Keycloak で使用されるデータベースは、Red Hat build of Keycloak の全体的なパフォーマンス、可用性、信頼性、整合性において非常に重要です。サポート対象データベースの設定方法の説明は、データベースの設定を参照してください。

2.6. クラスター内での Red Hat build of Keycloak のサポート

Red Hat build of Keycloak インスタンスがダウンした場合もユーザーのログインを継続するために、一般的な実稼働環境には Red Hat build of Keycloak インスタンスが 2 つ以上含まれています。

Red Hat build of Keycloak は、JGroups および Infinispan 上で実行されます。これらは、クラスター化されている場合に高い信頼性と可用性を提供します。クラスターにデプロイされている場合は、組み込み Infinispan サーバーの通信を保護する必要があります。この通信を保護するには、認証と暗号化を有効にするか、クラスター通信に使用されるネットワークを分離します。

複数のノード、さまざまなキャッシュ、環境に適したスタックを使用する場合の詳細は、分散キャッシュの設定を参照してください。

2.7. Red Hat build of Keycloak サーバーで IPv4 または IPv6 を設定する

システムプロパティーである java.net.preferIPv4Stack と java.net.preferIPv6Addresses を使用して、IPv4 または IPv6 アドレスを使用するように JVM を設定できます。

デフォルトでは、Red Hat build of Keycloak は、同時に IPv4 アドレスと IPv6 アドレスを介してアクセスできます。IPv4 アドレスのみで実行する場合は、プロパティー java.net.preferIPv4Stack=true を指定する必要があります。そうすることで、ホスト名から IP アドレスへの変換では必ず IPv4 アドレスのバリアントが返されるようになります。

これらのシステムプロパティーは、JAVA_OPTS_APPEND 環境変数を使用して容易に設定できます。たとえば、IP スタック設定を IPv4 に変更するには、次のように環境変数を設定します。

export JAVA_OPTS_APPEND="-Djava.net.preferIPv4Stack=true"

第3章 Red Hat build of Keycloak をコンテナー内で実行する

この章では、コンテナーを実行する際に最適なエクスペリエンスを実現するために、Red Hat build of Keycloak コンテナーイメージを最適化して実行する方法を説明します。

警告

この章は、OpenShift 環境で実行するイメージのビルドにのみ適用されます。このイメージは OpenShift 環境のみをサポートします。他の Kubernetes ディストリビューションで実行する場合はサポートされません。

3.1. カスタマイズおよび最適化されたコンテナーイメージの作成

デフォルトの Red Hat build of Keycloak コンテナーイメージは、すぐに設定および最適化できる状態で出荷されます。

Red Hat build of Keycloak コンテナーを最適に起動するには、コンテナーのビルド中に build ステップを実行してイメージをビルドします。この手順を実行することで、後に続くコンテナーイメージの各起動フェーズで時間を節約できます。

3.1.1. 最適化された Red Hat build of Keycloak Dockerfile を記述する

次の Dockerfile は、健全性およびメトリクスのエンドポイントとトークン交換機能を有効にし、PostgreSQL データベースを使用する、事前設定済みの Red Hat build of Keycloak イメージを作成します。

Dockerfile:

FROM registry.redhat.io/rhbk/keycloak-rhel9:24 as builder

# Enable health and metrics support
ENV KC_HEALTH_ENABLED=true
ENV KC_METRICS_ENABLED=true

# Configure a database vendor
ENV KC_DB=postgres

WORKDIR /opt/keycloak
# for demonstration purposes only, please make sure to use proper certificates in production instead
RUN keytool -genkeypair -storepass password -storetype PKCS12 -keyalg RSA -keysize 2048 -dname "CN=server" -alias server -ext "SAN:c=DNS:localhost,IP:127.0.0.1" -keystore conf/server.keystore
RUN /opt/keycloak/bin/kc.sh build

FROM registry.redhat.io/rhbk/keycloak-rhel9:24
COPY --from=builder /opt/keycloak/ /opt/keycloak/

# change these values to point to a running postgres instance
ENV KC_DB=postgres
ENV KC_DB_URL=<DBURL>
ENV KC_DB_USERNAME=<DBUSERNAME>
ENV KC_DB_PASSWORD=<DBPASSWORD>
ENV KC_HOSTNAME=localhost
ENTRYPOINT ["/opt/keycloak/bin/kc.sh"]

ビルドプロセスには複数の段階が含まれます。

build コマンドを実行してサーバーのビルドオプションを設定し、最適化されたイメージを作成します。
build 段階で生成されたファイルが、新しいイメージにコピーされます。
最後のイメージで、ホスト名とデータベースの追加の設定オプションが設定されているため、コンテナーの実行時にそれらを再度設定する必要はありません。
エントリーポイントで、kc.sh により、すべてのディストリビューションのサブコマンドがアクセス可能になります。

カスタムプロバイダーは、JAR ファイルを /opt/keycloak/providers ディレクトリーに含めるステップを定義するだけでインストールできます。このステップは、以下のように、build コマンドを RUNs 行の前に配置する必要があります。

# A example build step that downloads a JAR file from a URL and adds it to the providers directory
FROM registry.redhat.io/rhbk/keycloak-rhel9:24 as builder

...

# Add the provider JAR file to the providers directory
ADD --chown=keycloak:keycloak --chmod=644 <MY_PROVIDER_JAR_URL> /opt/keycloak/providers/myprovider.jar

...

# Context: RUN the build command
RUN /opt/keycloak/bin/kc.sh build

3.1.2. 追加の RPM パッケージをインストールする

FROM registry.redhat.io/rhbk/keycloak-rhel9 段階で新しいソフトウェアをインストールしようとすると、microdnf、dnf、さらには rpm がインストールされていないことがわかります。また、利用できるパッケージは非常に少なく、bash シェルと Red Hat build of Keycloak 自体の実行に必要なものしかありません。これは、Red Hat build of Keycloak の攻撃対象領域を減らすセキュリティー強化対策によるものです。

まず、ユースケースを別の方法で実装できるかどうかを検討し、なるべく最終的なコンテナーへの新規 RPM のインストールを回避します。

Dockerfile 内の RUN curl 命令は、リモート URL をネイティブにサポートしているため、ADD に置き換えることができます。
一部の一般的な CLI ツールは、Linux ファイルシステムを創造的に使用することで置き換えることができます。たとえば、ip addr show tap0 は cat/sys/class/net/tap0/address になります。
RPM を必要とするタスクはイメージビルドの前の段階に移動し、代わりに結果をコピーできます。

以下は例です。前のビルド段階で update-ca-trust を実行し、後の段階に結果をコピーします。

FROM registry.access.redhat.com/ubi9 AS ubi-micro-build
COPY mycertificate.crt /etc/pki/ca-trust/source/anchors/mycertificate.crt
RUN update-ca-trust

FROM registry.redhat.io/rhbk/keycloak-rhel9
COPY --from=ubi-micro-build /etc/pki /etc/pki

絶対に必要な場合は、ubi-micro で確立された次の 2 段階のパターンに従い、新しい RPM をインストールできます。

FROM registry.access.redhat.com/ubi9 AS ubi-micro-build
RUN mkdir -p /mnt/rootfs
RUN dnf install --installroot /mnt/rootfs <package names go here> --releasever 9 --setopt install_weak_deps=false --nodocs -y && \
    dnf --installroot /mnt/rootfs clean all && \
    rpm --root /mnt/rootfs -e --nodeps setup

FROM registry.redhat.io/rhbk/keycloak-rhel9
COPY --from=ubi-micro-build /mnt/rootfs /

このアプローチでは chroot (/mnt/rootfs) を使用するため、指定したパッケージとその依存関係のみがインストールされます。その結果、推測を必要とせずに第 2 段階に簡単にコピーできます。

警告

一部のパッケージには、依存関係の大きなツリーがあります。新しい RPM をインストールすると、コンテナーの攻撃対象領域が意図せず増大する可能性があります。インストールされているパッケージのリストを慎重に確認してください。

3.1.3. コンテナーイメージの構築

実際の container イメージをビルドするには、Dockerfile を含むディレクトリーから次のコマンドを実行します。

podman build . -t mykeycloak

3.1.4. 最適化された Red Hat build of Keycloak コンテナーイメージの起動

イメージを起動するには、以下を実行します。

podman run --name mykeycloak -p 8443:8443 \
        -e KEYCLOAK_ADMIN=admin -e KEYCLOAK_ADMIN_PASSWORD=change_me \
        mykeycloak \
        start --optimized

Red Hat build of Keycloak は、セキュアな HTTPS 通信のみを使用して実稼働モードで開始され、https://localhost:8443 で使用できます。

ヘルスチェックエンドポイントは、https://localhost:8443/health、https://localhost:8443/health/ready、および https://localhost:8443/health/live で使用できます。

https://localhost:8443/metrics を開くと、モニタリングソリューションで使用できる運用メトリクスを含むページが表示されます。

3.2. コンテナーを別のポートに公開する

デフォルトで、サーバーはポート 8080 と 8443 を使用して、それぞれ http 要求と https 要求をリッスンします。

別のポートを使用してコンテナーを公開する場合は、それに応じて hostname-port を設定する必要があります。

デフォルトポート以外のポートを使用してコンテナーを公開する

podman run --name mykeycloak -p 3000:8443 \
        -e KEYCLOAK_ADMIN=admin -e KEYCLOAK_ADMIN_PASSWORD=change_me \
        mykeycloak \
        start --optimized --hostname-port=3000

hostname-port オプションを設定すると、https://localhost:3000 のサーバーにアクセスできるようになります。

3.3. 開発モードで Red Hat build of Keycloak を試用する

開発またはテスト目的でコンテナーから Red Hat build of Keycloak を試用する場合、開発モードが最適です。start-dev コマンドを使用します。

podman run --name mykeycloak -p 8080:8080 \
        -e KEYCLOAK_ADMIN=admin -e KEYCLOAK_ADMIN_PASSWORD=change_me \
        registry.redhat.io/rhbk/keycloak-rhel9:24 \
        start-dev

このコマンドを呼び出すと、Red Hat build of Keycloak サーバーが開発モードで起動します。

このモードはデフォルトがセキュアではないため、実稼働環境では絶対に使用しないでください。Red Hat build of Keycloak を実稼働環境で実行する方法の詳細は、Red Hat build of Keycloak を実稼働用に設定するを参照してください。

3.4. 標準の Red Hat build of Keycloak コンテナーを実行する

イミュータブルインフラストラクチャーなどの概念に従い、コンテナーは定期的に再プロビジョニングする必要があります。これらの環境では、素早く起動するコンテナーが必要なため、前のセクションで説明したように、最適化されたイメージを作成する必要があります。ただし、環境に異なる要件がある場合は、start コマンドを実行するだけで標準の Red Hat build of Keycloak イメージを実行できます。以下に例を示します。

podman run --name mykeycloak -p 8080:8080 \
        -e KEYCLOAK_ADMIN=admin -e KEYCLOAK_ADMIN_PASSWORD=change_me \
        registry.redhat.io/rhbk/keycloak-rhel9:24 \
        start \
        --db=postgres --features=token-exchange \
        --db-url=<JDBC-URL> --db-username=<DB-USER> --db-password=<DB-PASSWORD> \
        --https-key-store-file=<file> --https-key-store-password=<password>

このコマンドを実行すると、最初にビルドオプションを検出して適用する Red Hat build of Keycloak サーバーが起動します。この例では、--db=postgres --features=token-exchange の行でデータベースベンダーが PostgreSQL に設定され、トークン交換機能が有効になります。

その後、Red Hat build of Keycloak が起動し、設定が環境に適用されます。このアプローチでは起動時間が大幅に増加し、ミュータブルなイメージが作成されますが、これはベストプラクティスではありません。

3.5. コンテナー内での実行時に初期の管理者認証情報を入力する

Red Hat build of Keycloak では、ローカルネットワーク接続からのみ初期管理ユーザーを作成できます。コンテナー内で実行する場合、これは当てはまりません。そのため、イメージ実行時に次の環境変数を指定する必要があります。

# setting the admin username
-e KEYCLOAK_ADMIN=<admin-user-name>

# setting the initial password
-e KEYCLOAK_ADMIN_PASSWORD=change_me

3.6. 起動時にレルムをインポートする

Red Hat build of Keycloak コンテナーには、ディレクトリー /opt/keycloak/data/import があります。ボリュームマウントまたはその他の手段でこのディレクトリーに 1 つ以上のインポートファイルを配置し、起動引数 --import-realm を追加すると、Red Hat build of Keycloak コンテナーが起動時にそのデータをインポートします。これは、開発モードでのみの使用が合理的です。

podman run --name keycloak_unoptimized -p 8080:8080 \
        -e KEYCLOAK_ADMIN=admin -e KEYCLOAK_ADMIN_PASSWORD=change_me \
        -v /path/to/realm/data:/opt/keycloak/data/import \
        registry.redhat.io/rhbk/keycloak-rhel9:24 \
        start-dev --import-realm

管理者ブートストラッププロセスの機能強化については、誰でも参加できる GitHub ディスカッションがあります。お気軽にご参加ください。

3.7. 異なるメモリー設定を指定する

Red Hat build of Keycloak コンテナーでは、初期ヒープサイズと最大ヒープサイズにハードコード値を指定せずに、コンテナーの合計メモリーに対する相対値を使用します。この動作は、JVM オプション -XX:MaxRAMPercentage=70 および -XX:InitialRAMPercentage=50 によって実現されます。

-XX:MaxRAMPercentage オプションは、最大ヒープサイズをコンテナーメモリーの合計の 70% として表します。-XX:InitialRAMPercentage オプションは、初期ヒープサイズをコンテナーメモリー全体の 50% として表します。これらの値は、Red Hat build of Keycloak メモリー管理の詳細な分析に基づいて選択されています。

ヒープサイズはコンテナーの合計メモリーに基づいて動的に計算されるため、コンテナーの メモリー制限を必ず設定 してください。以前は、最大ヒープサイズは 512 MB に設定されていましたが、同じ値に近づけるには、メモリー制限を少なくとも 750 MB に設定する必要があります。小規模な実稼働環境対応のデプロイメントの場合、推奨されるメモリー制限は 2 GB です。

ヒープに関連する JVM オプションは、環境変数 JAVA_OPTS_KC_HEAP を設定することによってオーバーライドされる可能性があります。JAVA_OPTS_KC_HEAP のデフォルト値は、kc.sh または kc.bat スクリプトのソースコードにあります。

たとえば、環境変数とメモリー制限を次のように指定できます。

podman run --name mykeycloak -p 8080:8080 -m 1g \
        -e KEYCLOAK_ADMIN=admin -e KEYCLOAK_ADMIN_PASSWORD=change_me \
        -e JAVA_OPTS_KC_HEAP="-XX:MaxHeapFreeRatio=30 -XX:MaxRAMPercentage=65" \
        registry.redhat.io/rhbk/keycloak-rhel9:24 \
        start-dev

警告

メモリー制限が設定されていない場合、ヒープサイズがコンテナーの合計メモリーの最大 70% まで増加する可能性があるため、メモリー消費量が急激に増加します。JVM がメモリーを割り当てると、現在の Red Hat build of Keycloak の GC 設定により、そのメモリーが消極的に OS に返されます。

3.8. 関連するオプション

	値
`db` 🛠 データベースベンダー CLI: `--db` 環境変数: `KC_DB`	`dev-file` (デフォルト)、`dev-mem`、`mariadb`、`mssql`、`mysql`、`oracle`、`postgres`
`db-password` データベースユーザーアカウントのパスワード CLI: `--db-password` 環境変数: `KC_DB_PASSWORD`
`db-url` データベースの完全な JDBC URL 指定しない場合、選択したデータベースベンダーに基づきデフォルト URL が設定されます。たとえば、`postgres` を使用している場合、デフォルトの JDBC URL は `jdbc:postgresql://localhost/keycloak` になります。 CLI: `--db-url` 環境変数: `KC_DB_URL`
`db-username` データベースユーザーのユーザー名 CLI: `--db-username` 環境変数: `KC_DB_USERNAME`
`features` 🛠 1 つ以上の機能セットを有効にします。 CLI: `--features` 環境変数: `KC_FEATURES`	`account-api[:v1]`, `account2[:v1]`, `account3[:v1]`, `admin-api[:v1]`, `admin-fine-grained-authz[:v1]`, `admin2[:v1]`, `authorization[:v1]`, `ciba[:v1]`, `client-policies[:v1]`, `client-secret-rotation[:v1]`, `client-types[:v1]`, `declarative-ui[:v1]`, `device-flow[:v1]`, `docker[:v1]`, `dpop[:v1]`, `dynamic-scopes[:v1]`, `fips[:v1]`, `hostname[:v1]`, `impersonation[:v1]`, `js-adapter[:v1]`, `kerberos[:v1]`, `linkedin-oauth[:v1]`, `login2[:v1]`, `multi-site[:v1]`, `offline-session-preloading[:v1]`, `oid4vc-vci[:v1]`, `par[:v1]`, `preview`, `recovery-codes[:v1]`, `scripts[:v1]`, `step-up-authentication[:v1]`, `token-exchange[:v1]`, `transient-users[:v1]`, `update-email[:v1]`, `web-authn[:v1]`
`health-enabled` 🛠 サーバーがヘルスチェックエンドポイントを公開する必要があるかどうか。有効にすると、`/health`、`/health/ready`、および `/health/live` エンドポイントでヘルスチェックが利用可能になります。 CLI: `--health-enabled` 環境変数: `KC_HEALTH_ENABLED`	`true`、`false` (デフォルト)
`hostname` Keycloak サーバーのホスト名 CLI: `--hostname` 環境変数: `KC_HOSTNAME`
`https-key-store-file` 個別のファイルを指定する代わりに、証明書情報を保持するキーストア。 CLI: `--https-key-store-file` 環境変数: `KC_HTTPS_KEY_STORE_FILE`
`https-key-store-password` キーストアファイルのパスワード CLI: `--https-key-store-password` 環境変数: `KC_HTTPS_KEY_STORE_PASSWORD`	`password` (デフォルト)
`metrics-enabled` 🛠 サーバーがメトリクスを公開する必要があるかどうか。有効にすると、`/metrics` エンドポイントでメトリクスを利用できるようになります。 CLI: `--metrics-enabled` 環境変数: `KC_METRICS_ENABLED`	`true`、`false` (デフォルト)

第4章 TLS の設定

Transport Layer Security (略称: TLS) は、保護されたチャネル上でデータを交換するために重要です。実稼働環境では、Red Hat build of Keycloak が他のアプリケーションと交換する内容の中核に機密データが含まれるため、HTTP 経由で Red Hat build of Keycloak エンドポイントを公開しないでください。この章では、HTTPS/TLS を使用するように Red Hat build of Keycloak を設定する方法を説明します。

4.1. Red Hat build of Keycloak で TLS を設定する

Red Hat build of Keycloak は、PEM 形式のファイルを使用するか、Java Keystore から、必要な証明書インフラストラクチャーをロードするように設定できます。両方の手段が設定されている場合、PEM ファイルが Java Keystore よりも優先されます。

4.1.1. PEM 形式の証明書を指定する

PEM 形式の証明書ファイルと秘密鍵ファイルのペアを使用する場合は、次のコマンドを実行して、それらを使用するように Red Hat build of Keycloak を設定します。

bin/kc.[sh|bat] start --https-certificate-file=/path/to/certfile.pem --https-certificate-key-file=/path/to/keyfile.pem

Red Hat build of Keycloak は、メモリー内のこれらのファイルからキーストアを作成し、以降はこのキーストアを使用します。

4.1.2. Java Keystore を指定する

キーストアファイルが明示的に設定されておらず、http-enabled が false に設定されている場合、Red Hat build of Keycloak は conf/server.keystore ファイルを探します。

代わりに、次のコマンドを実行して既存のキーストアを使用することもできます。

bin/kc.[sh|bat] start --https-key-store-file=/path/to/existing-keystore-file

4.1.2.1. Keystore のパスワードを設定する

https-key-store-password オプションを使用して、キーストアにセキュアなパスワードを設定できます。

bin/kc.[sh|bat] start --https-key-store-password=<value>

パスワードが設定されていない場合は、デフォルトのパスワードである password が使用されます。

4.2. TLS プロトコルの設定

デフォルトでは、Red Hat build of Keycloak は非推奨の TLS プロトコルを有効にしません。クライアントが非推奨のプロトコルのみをサポートしている場合は、クライアントのアップグレードを検討してください。一時的な回避策として、次のコマンドを実行し、非推奨のプロトコルを有効にできます。

bin/kc.[sh|bat] start --https-protocols=<protocol>[,<protocol>]

TLSv1.2 も許可するには、kc.sh start --https-protocols=TLSv1.3,TLSv1.2 などのコマンドを使用します。

4.3. HTTPS ポートの切り替え

Red Hat build of Keycloak は、ポート 8443 で HTTPS トラフィックをリッスンします。このポートを変更するには、次のコマンドを使用します。

bin/kc.[sh|bat] start --https-port=<port>

4.4. トラストストアの使用

クライアント証明書を適切に検証し、TLS 相互認証 (mTLS) などの特定の認証方法を有効にするために、サーバーが信頼する必要があるすべての証明書 (および証明書チェーン) を含むトラストストアを設定できます。多くの機能は、このトラストストアに依存して、次のような証明書でクライアントを適切に認証します。

相互 TLS クライアント認証
エンドユーザー X.509 ブラウザー認証

次のコマンドを実行して、このトラストストアの場所を設定できます。

bin/kc.[sh|bat] start --https-trust-store-file=/path/to/file

注記

これは、Red Hat build of Keycloak がサーバーとして機能するクライアントを認証するためのトラストストアです。Red Hat build of Keycloak が TLS を介して外部サービスへのクライアントとして機能するトラストストアの設定については、信頼済み証明書の設定を参照してください。

4.4.1. トラストストアのパスワードを設定する

https-trust-store-password オプションを使用して、トラストストアのセキュアなパスワードを設定できます。

bin/kc.[sh|bat] start --https-trust-store-password=<value>

パスワードが設定されていない場合は、デフォルトのパスワードである password が使用されます。

4.5. 認証情報の保護

CLI を使用するか、conf/keycloak.conf ファイルにパスワードを追加するなどして、プレーンテキストでのパスワード設定を回避してください。代わりに、vault/マウントされたシークレットを使用するなどの適切な方法を使用してください。詳細は、vault の使用および Red Hat build of Keycloak を実稼働用に設定するを参照してください。

4.6. 相互 TLS の有効化

mTLS を使用した認証は、デフォルトで無効になっています。Red Hat build of Keycloak がサーバーであり、Red Hat build of Keycloak エンドポイントに対する要求からの証明書を検証する必要がある場合に mTLS 証明書の処理を有効にするには、Red Hat build of Keycloak トラストストアに適切な証明書を配置し、次のコマンドを使用して mTLS を有効にします。

bin/kc.[sh|bat] start --https-client-auth=<none|request|required>

値に required を使用すると、必ず Red Hat build of Keycloak が証明書を要求し、要求内に証明書がない場合は失敗するように設定されます。値を request に設定すると、Red Hat build of Keycloak は証明書がない要求も受け入れ、証明書が存在する場合にのみ証明書の正確性を検証します。

これは、Red Hat build of Keycloak がサーバーとして機能する mTLS ユースケースの、基本的な証明書設定であることに注意してください。Red Hat build of Keycloak がクライアントとして機能する場合 (たとえば Red Hat build of Keycloak が mTLS によって保護されているブローカーアイデンティティープロバイダーのトークンエンドポイントからトークンを取得しようとする場合)、キーストア内の適切な証明書を送信要求に提供するように、HttpClient を設定する必要があります。このようなシナリオで mTLS を設定するには、送信 HTTP 要求の設定を参照してください。

4.7. 関連するオプション

	値
`http-enabled` HTTP リスナーを有効にします。 CLI: `--http-enabled` 環境変数: `KC_HTTP_ENABLED`	`true`、`false` (デフォルト)
`https-certificate-file` PEM 形式のサーバー証明書または証明書チェーンへのファイルパス。 CLI: `--https-certificate-file` 環境変数: `KC_HTTPS_CERTIFICATE_FILE`
`https-certificate-key-file` PEM 形式の秘密鍵へのファイルパス。 CLI: `--https-certificate-key-file` 環境変数: `KC_HTTPS_CERTIFICATE_KEY_FILE`
`https-cipher-suites` 使用する暗号スイート。指定されていない場合、適切なデフォルトが選択されます。 CLI: `--https-cipher-suites` 環境変数: `KC_HTTPS_CIPHER_SUITES`
`https-client-auth` 🛠 クライアント認証を必要とする、または要求するようにサーバーを設定します。 CLI: `--https-client-auth` 環境変数: `KC_HTTPS_CLIENT_AUTH`	`none` (デフォルト)、`request`、`required`
`https-key-store-file` 個別のファイルを指定する代わりに、証明書情報を保持するキーストア。 CLI: `--https-key-store-file` 環境変数: `KC_HTTPS_KEY_STORE_FILE`
`https-key-store-password` キーストアファイルのパスワード CLI: `--https-key-store-password` 環境変数: `KC_HTTPS_KEY_STORE_PASSWORD`	`password` (デフォルト)
`https-key-store-type` キーストアファイルの型。指定されていない場合、ファイル名に基き自動的に型が検出されます。`fips-mode` が `strict` に設定され、値が設定されていない場合、デフォルトの `BCFKS` になります。 CLI: `--https-key-store-type` 環境変数: `KC_HTTPS_KEY_STORE_TYPE`
`https-port` 使用される HTTPS ポート。 CLI: `--https-port` 環境変数: `KC_HTTPS_PORT`	`8443` (デフォルト)
`https-protocols` 明示的に有効にするプロトコルのリスト。 CLI: `--https-protocols` 環境変数: `KC_HTTPS_PROTOCOLS`	`[TLSv1.3, TLSv1.2]` (デフォルト)
`https-trust-store-file` 信頼する証明書の証明書情報を保持するトラストストア。 CLI: `--https-trust-store-file` 環境変数: `KC_HTTPS_TRUST_STORE_FILE` 非推奨。代わりにシステムトラストストアを使用してください。詳細はドキュメントを参照してください。
`https-trust-store-password` トラストストアファイルのパスワード。 CLI: `--https-trust-store-password` 環境変数: `KC_HTTPS_TRUST_STORE_PASSWORD` 非推奨。代わりにシステムトラストストアを使用してください。詳細はドキュメントを参照してください。
`https-trust-store-type` トラストストアファイルの型。指定されていない場合、ファイル名に基き自動的に型が検出されます。`fips-mode` が `strict` に設定され、値が設定されていない場合、デフォルトの `BCFKS` になります。 CLI: `--https-trust-store-type` 環境変数: `KC_HTTPS_TRUST_STORE_TYPE` 非推奨。代わりにシステムトラストストアを使用してください。詳細はドキュメントを参照してください。

第5章ホスト名の設定

5.1. サーバーエンドポイント

Red Hat build of Keycloak は、アプリケーションと対話したり、管理コンソールへのアクセスを許可したりするための、さまざまなエンドポイントを公開します。これらのエンドポイントは、次の 3 つの主要なグループに分類できます。

フロントエンド
バックエンド
管理コンソール

各グループのベース URL は、トークンの発行方法と検証方法、ユーザーを Red Hat build of Keycloak にリダイレクトする必要があるアクション (メールリンクを通じてパスワードをリセットする場合など) のリンクの作成方法、さらにはアプリケーションが realms/{realm-name}/.well-known/openid-configuration から OpenID Connect Discovery Document を取得する際にこれらのエンドポイントを検出する方法に重要な影響を与えます。

5.1.1. フロントエンド

フロントエンドのエンドポイントは、パブリックドメインを通じてアクセスでき、通常はフロントチャネルを通じて発生する認証/認可フローに関連します。たとえば、SPA がユーザーを認証する必要がある場合、SPA はユーザーを authorization_endpoint にリダイレクトし、ユーザーがフロントチャネル経由でブラウザーを使用して認証できるようにします。

デフォルトでは、ホスト名設定が行われていない場合、これらのエンドポイントのベース URL は受信要要求に基づくため、HTTP スキーム、ホスト、ポート、パスは要求と同じになります。発行者もフロントエンドエンドポイントに設定された URL に基づくため、デフォルトの動作は、サーバーがトークンを発行する方法にも直接影響します。ホスト名設定が行われていない場合、トークン発行者も受信要求に基づくことになり、クライアントが異なる URL を使用してトークンを要求している場合は一貫性が失われます。

通常、実稼働環境にデプロイする場合、要求の構築方法に関係なく、フロントエンドエンドポイントとトークン発行者の一貫した URL が必要になります。この一貫性を実現するために、hostname または hostname-url オプションを設定できます。

ほとんどの場合、フロントエンド URL の ホスト のみを変更するには、hostname オプションを設定するだけで十分です。

bin/kc.[sh|bat] start --hostname=<host>

hostname オプションを使用している場合、以下を達成するために、サーバーは HTTP スキーム、ポート、およびパスを自動的に解決します。

hostname-strict-https=false を設定しない限り、https スキームが使用されます。
proxy-headers オプションが設定されている場合、プロキシーがデフォルトのポート (80 と 443) を使用します。プロキシーで別のポートを使用する場合は、hostname-url 設定オプションで指定する必要があります。

ただし、ホストだけでなくスキーム、ポート、パスも設定する必要がある場合は、hostname-url オプションを設定できます。

bin/kc.[sh|bat] start --hostname-url=<scheme>://<host>:<port>/<path>

このオプションを使用すると、1 つのオプションで URL のさまざまな部分を設定できるため、柔軟性が向上します。hostname と hostname-url は、相互に排他的であることに注意してください。

注記

hostname と proxy-headers の設定オプションは、静的リソースの URL、リダイレクト URI、OIDC well-known エンドポイントなどにのみ影響します。サーバーが実際にどこでどのポートをリッスンするかを変更するには、http/tls 設定オプション (例: http-host、https-port など) を使用する必要があります。詳細は、TLS の設定およびすべての設定を参照してください。

5.1.2. バックエンド

バックエンドエンドポイントは、パブリックドメインまたはプライベートネットワークを通じてアクセスできるエンドポイントです。これらは、サーバーとクライアント間の、仲介のないプレーン HTTP 要求による直接通信に使用されます。たとえば、ユーザーが認証された後、SPA はトークン要求を token_endpoint に送信することで、サーバーが送信した code をトークンセットと交換する必要があるとします。

デフォルトでは、バックエンドエンドポイントの URL も受信要求に基づいています。この動作をオーバーライドするには、次のコマンドを入力して hostname-strict-backchannel 設定オプションを設定します。

bin/kc.[sh|bat] start --hostname=<value> --hostname-strict-backchannel=true

hostname-strict-backchannel オプションを設定すると、バックエンドエンドポイントの URL はフロントエンドエンドポイントとまったく同じになります。

Red Hat build of Keycloak に接続されているすべてのアプリケーションがパブリック URL 経由で通信する場合は、hostname-strict-backchannel を true に設定します。それ以外の場合は、このパラメーターを false のままにして、プライベートネットワークを介したクライアント/サーバー通信を許可します。

5.1.3. 管理コンソール

サーバーは、特定の URL を使用して管理コンソールと静的リソースを公開します。

デフォルトでは、管理コンソールの URL も受信要求に基づいています。ただし、特定の URL を使用して管理コンソールへのアクセスを制限する場合は、特定のホストまたはベース URL を設定できます。フロントエンド URL の設定方法と同様に、hostname-admin および hostname-admin-url オプションを使用してこれを実現できます。HTTPS が有効になっている場合 (実稼働モードのデフォルト設定として http-enabled 設定オプションは false に設定されています)、Red Hat build of Keycloak サーバーは HTTPS URL の使用を自動的に想定することに注意してください。次に、管理コンソールは HTTPS 経由で Red Hat build of Keycloak に接続しようとします。HTTPS URL は、設定されたリダイレクト/Web オリジン URL にも使用されます。実稼働環境には推奨されませんが、HTTP URL を hostname-admin-url として使用して、この動作をオーバーライドできます。

ほとんどの場合、管理コンソール URL の ホスト のみを変更するのであれば、hostname-admin オプションを設定するだけで十分です。

bin/kc.[sh|bat] start --hostname-admin=<host>

ただし、ホストだけでなくスキーム、ポート、パスも設定する必要がある場合は、hostname-admin-url オプションを設定できます。

bin/kc.[sh|bat] start --hostname-admin-url=<scheme>://<host>:<port>/<path>

hostname-admin と hostname-admin-url は相互に排他的であることに注意してください。

攻撃対象領域を減らすために、Red Hat build of Keycloak の管理エンドポイントと管理コンソールは、パブリックにアクセスできないようにする必要があります。つまり、リバースプロキシーを使用して保護できます。リバースプロキシーを使用して公開するパスの詳細は、リバースプロキシーの使用を参照してください。

5.2. シナリオ例

以下に、ホスト名を設定する別のサンプルシナリオと、対応するコマンドを示します。

start コマンドには TLS の設定が必要であることに注意してください。対応するオプションは例として示されていません。詳細は、TLS の設定を参照してください。

5.2.1. TLS Termination プロキシーの背後にあるサーバーを公開する

この例では、サーバーは TLS Termination プロキシーの背後で実行されており、https://mykeycloak から公開されています。

設定:

bin/kc.[sh|bat] start --hostname=mykeycloak --http-enabled=true --proxy-headers=forwarded|xforwarded