Server Installation and Configuration Guide

スタンドアローン・モードでサーバーを実行する場合、オペレーティング・システム固有の起動スクリプトを実行する必要があります。これらのスクリプトはサーバー配布物の bin/ ディレクトリーにあります。

To boot the server:

このガイドの大半は、Keycloakの基盤レベルの設定について説明します。このレベルの設定は、Keycloakが構築されたアプリケーション・サーバーに特化した設定ファイル内に定義されます。スタンドアローン動作モードでは、このファイルは …​/standalone/configuration/standalone.xml にあります。また、このファイルはKeycloakのコンポーネントに特化した非基盤レベルの設定にも使用されます。

この配布物には、クラスター内で実行するためのアプリケーション・サーバーの設定ファイルが含まれており、その大半は設定が済んでいます。ネットワーク、データベース、キャッシュ、およびディスカバリーのための基盤設定がすべて含まれています。このファイルは …​/standalone/configuration/standalone-ha.xml にあります。しかし、この設定だけでは足りません。共有データベース接続を設定せずに、クラスター内でKeycloakを実行することはできません。また、クラスターのフロントに何らかのロードバランサーを配備する必要があります。このガイドのクラスタリングとデータベースのセクションでは、これらのことを説明します。

Keycloakを起動するには、スタンドアローン・モードで実行したのと同じ起動スクリプトを使用します。スタンドアローン・モードとの違いは、HA設定ファイルを指し示す追加フラグを渡すという点になります。

To boot the server:

このガイドの各章では、データベース、HTTPネットワーク接続、キャッシュ、およびその他の基盤関連のさまざまな設定について説明します。これらを設定するために、スタンドアローン・モードでは standalone.xml ファイルを使用するのに対して、ドメインモードでは …​/domain/configuration/domain.xml を使用します。Keycloakサーバーのドメイン・プロファイルとサーバーグループは、以下で定義されます。

この domain.xml ファイルの特徴を確認していきましょう。 auth-server-standalone と auth-server-clustered の profile のXMLブロックでは、どのような設定にするかの大半を定義します。そして、ネットワーク接続、キャッシュ、データベース接続などを設定します。

auth-server-standalone プロファイルは、非クラスター構成のセットアップ用です。一方 auth-server-clustered プロファイルは、クラスター構成のセットアップ用です。

スクロールダウンしていくと、定義済みの socket-binding-groups が表示されます。

この設定では、各Keycloakサーバー・インスタンスによって開かれる、さまざまなコネクターのデフォルトのポートマッピングを定義します。 ${…​} を含む値はコマンドラインの -D スイッチで上書きできる値です。すなわち、以下のように上書きできます。

Keycloakのサーバーグループの定義は、 server-groups のXMLブロックにあります。ホスト・コントローラーがインスタンスを起動する場合、この定義により、 default で使用されているドメイン・プロファイル、およびJava VMのデフォルト起動引数が指定されます。また、 socket-binding-group はサーバーグループにバインドされます。

Keycloakには、 …​/domain/configuration/ ディレクトリーにある、 host-master.xml と host-slave.xml の2つのホスト・コントローラー設定ファイルが付属しています。 host-master.xml はドメイン・コントローラー、ロードバランサー、および1つのKeycloakサーバー・インスタンスを起動するように設定されています。一方、 host-slave.xml はドメイン・コントローラーと通信し、1つのKeycloakサーバー・インスタンスを起動するように設定されています。

ロードバランサー・サーバー・インスタンスを無効にするには、 host-master.xml を編集し、 "load-balancer" エントリーをコメントアウトまたは削除します。

このファイルに関してもう1つ興味深い点は、認証サーバー・インスタンスの宣言です。これには port-offset が設定されています。 domain.xml の socket-binding-group またはサーバーグループで定義されたネットワークポートには、port-offsetの値が加算されます。このサンプルでは、ロードバランサー・サーバーによって開かれたポートが、起動中の認証サーバー・インスタンスと競合しないように設定しています。

ホスト・ファイルに定義されている各Keycloakサーバー・インスタンスにより、 …​/domain/servers/{SERVER NAME} の下に作業ディレクトリーが作成されます。そこに追加の設定を保存でき、サーバー・インスタンスが必要とする、または作成する一時ファイル、ログファイル、データファイルも保存することができます。これらのサーバー・ディレクトリーごとの構造は、他のWildFlyブートサーバーと同じようなものになります。

ドメインモードでサーバーを実行する場合、オペレーティング・システム固有の起動スクリプトを実行する必要があります。これらのスクリプトは、サーバー配布物の bin/ ディレクトリーにあります。

To boot the server:

起動スクリプトを実行する場合、 --host-config スイッチ経由で、使用するホスト制御設定ファイルを渡す必要があります 。

そのまま利用可能な domain.xml 設定を使用してクラスタリングをテストできます。このサンプルドメインは、1台のマシンで実行され、以下を起動します。

2台のマシンでのクラスターの実行をシミュレートするには、 domain.sh スクリプトを2回実行して2つの別々のホスト・コントローラーを起動させます。はじめに、ドメイン・コントローラー、HTTPロード・バランサー、および1つのKeycloak認証サーバー・インスタンスを起動するマスター・ホスト・コントローラーを起動させます。次に、認証サーバー・インスタンスを起動するだけのスレーブ・ホスト・コントローラーを起動させます。

これは高度なトピックのため、最初に以下を読み、背景にある重要な知識を身につけておくことをお勧めします。

このセクションでは、Keycloakクロスデータセンター・レプリケーションの仕組みについて概念と詳細について説明します。

Keycloakはステートフルなアプリケーションです。データソースとして以下のものを使用します。

このアーキテクチャーの例では、 site1 と site2 と呼ばれる2つのデータセンターがあります。クロスデータセンター・レプリケーションでは、両方のデータソースが確実に動作し、 site2 のKeycloakサーバーによって保存されたデータを site1 のKeycloakサーバーが最終的に読み取ることができるようにする必要があります。

環境に基づいて、次の選択肢から決める必要があります。

詳細は、モードを参照してください。

エンドユーザーのブラウザーは、HTTPリクエストをフロント・エンド・ロードバランサーに送信します。このロードバランサーは、通常mod_cluster、NGINX、HA Proxy、またはその他のソフトウェアかハードウェア・ロードバランサーを使用するHTTPDまたはWildFlyです。

ロードバランサーは、基になるKeycloakインスタンスに、受け取ったHTTPリクエストを転送します。このインスタンスは、複数のデータセンターに分散させることができます。ロードバランサーは通常、スティッキー・セッションをサポートしています。つまり、ロードバランサーは、同じデータセンターの同じKeycloakインスタンスに、同じユーザーのすべてのHTTPリクエストを常に転送することができます。

クライアント・アプリケーションからロードバランサーに送られたHTTPリクエストは バックチャネル・リクエスト と呼ばれます。これらはエンドユーザーのブラウザーからは見えないので、ユーザーとロードバランサー間でスティッキー・セッションの一部になることはできません。バックチャネル・リクエストの場合、ロードバランサーは、HTTPリクエストを任意のデータセンター内のいずれかのKeycloakインスタンスに転送することができます。これは、いくつかのOpenID ConnectといくつかのSAMLフローがユーザーとアプリケーションの両方から複数のHTTPリクエストを必要とするため、難しい問題です。関連するすべてのリクエストを同じデータセンター内の同じKeycloakインスタンスに送信するのにスティッキー・セッションに完全に依存することはできないため、代わりに、データセンター間で一部のデータをレプリケートする必要があります。それにより、データは特定のフロー中の後続のHTTPリクエストによって表示されます。

要件に応じて、クロスデータセンター・レプリケーションには2つの基本的な動作モードがあります。

アクティブ/パッシブモードは、パフォーマンスに優れています。いずれかのモードでキャッシュを設定する方法の詳細については、 SYNCまたはASYNCバックアップ を参照してください。

Keycloakは、リレーショナル・データベース・マネジメント・システム（RDBMS）を使用して、レルム、クライアント、ユーザーなどのメタデータを保持します。詳細については、サーバーインストールガイドのこの章を参照してください。クロスデータセンター・レプリケーションのセットアップでは、両方のデータセンターが同じデータベースと通信するか、すべてのデータセンターに独自のデータベース・ノードがあり、両方のデータベース・ノードがデータセンター間で同期レプリケートされると想定しています。どちらの場合でも、 site1 のKeycloakサーバーがデータを保持してトランザクションをコミットすると、 site2 の後続のDBトランザクションによって、それらのデータがすぐに表示される必要があります。

DBのセットアップの詳細については、Keycloakの範囲外ですが、MariaDBやOracleなどのRDBMSベンダーの多くは、レプリケートされたデータベースと同期レプリケーションを提供しています。これらのベンダーを使用して、Keycloakをテストしています。

このセクションでは、Infinispanキャッシュの概要を説明していきます。キャッシュの設定の詳細は以下のとおりです。

Keycloakには、認証セッションの概念があります。 authenticationSessions と呼ばれる別のInfinispanキャッシュがあり、特定のユーザーの認証時にデータを保存するのに使用されます。このキャッシュからのリクエストには通常、ブラウザーとKeycloakサーバーのみが関与し、アプリケーションは関与しません。ここでは、アクティブ/アクティブモードであっても、スティッキー・セッションに依存することができ、 authenticationSessions キャッシュ・コンテンツをデータセンター間でレプリケートする必要はありません。

アクション・トークンの概念もあります。アクション・トークンは、通常、ユーザーが電子メールでアクションを非同期で確認する必要があるシナリオで使用されます。たとえば、 forget password フローの間に、 actionTokens Infinispanキャッシュは、どのアクション・トークンがすでに使用されているかなどの関連するアクション・トークンに関するメタデータを追跡するために使用されるため、2度目は再利用できません。これは通常、データセンター間でレプリケートする必要があります。

KeycloakはInfinispanを使用して永続化データをキャッシュし、データベースへの不要なリクエストを多く回避します。キャッシュによりパフォーマンスは改善されますが、さらなる問題が加わります。一部のKeycloakサーバーがデータを更新した場合、すべてのデータセンターの他のすべてのKeycloakサーバーはそのことに気づく必要があるため、それらのキャッシュから特定のデータを無効にします。Keycloakは、 realms 、 users 、および authorization と呼ばれるローカルInfinispanキャッシュを使用して、永続化データをキャッシュします。

すべてのデータセンターでレプリケートされる、別のキャッシュ work を使用します。workキャッシュ自体は実際のデータをキャッシュしません。クラスターノードとデータセンター間で無効化メッセージを送信する場合にのみ使用されます。つまり、データ（ユーザー john のようなデータ）が更新されると、Keycloakノードは、同じデータセンター内の他のすべてのクラスターノード、および他のすべてのデータセンターに無効化メッセージを送信します。すべてのノードは、無効通知を受信した後、ローカル・キャッシュから適切なデータを無効にします。

sessions 、 clientSessions 、 offlineSessions 、および offlineClientSessions と呼ばれるInfinispanキャッシュがあり、それらのすべては通常、データセンター間でレプリケートされる必要があります。これらのキャッシュは、ユーザー・セッションに関するデータを保存するために使用され、ユーザーのブラウザー・セッションの長さに対して有効です。キャッシュは、エンドユーザーとアプリケーションからのHTTPリクエストを処理する必要があります。前述のとおり、このインスタンスではスティッキー・セッションを信頼性をもって使用することはできませんが、後続のHTTPリクエストが最新のデータを確認できるようにする必要があります。このため、データは通常、データセンター間でレプリケートされます。

最後に、 loginFailures キャッシュは、ユーザー john が不正なパスワードを入力した回数など、ログイン失敗に関するデータを追跡するために使用されます。詳細は、こちらを参照してください。このキャッシュをデータセンター間でレプリケートするかどうかは、管理者次第です。正確なログイン失敗の回数を取得するには、レプリケーションが必要です。一方、このデータをレプリケートしないことで、パフォーマンスをよくできます。したがって、パフォーマンスがログイン失敗の正確な回数よりも重要な場合は、レプリケーションを避けるという手もあります。

キャッシュの設定方法の詳細については、JDGキャッシュ設定のチューニングを参照してください。

Keycloakは、Infinispanキャッシュの分割されたクラスターを複数使用します。各Keycloakノードは、同じデータセンター内の他のKeycloakノードと共にクラスター内にありますが、異なるデータセンターのKeycloakノードはそのクラスター内にありません。Keycloakノードは、異なるデータセンターのKeycloakノードと直接通信できません。Keycloakノードは、データセンター間の通信に外部JDG（実際にはInfinispanサーバー）を使用します。これは、Infinispan HotRodプロトコルを使用して行われます。

Keycloak側のInfinispanキャッシュは、データがリモート・キャッシュに保存されていることを確認するために、remoteStoreを使用して設定する必要があります。JDGサーバー間に分割されたInfinispanクラスターがあるので、 site1 のJDG1に保存されていたデータは site2 のJDG2にレプリケートされます。

最後に、受信JDGサーバーは、HotRodプロトコルの機能であるクライアント・リスナーを介して、クラスター内のKeycloakサーバーに通知します。次に、 site2 のKeycloakノードがInfinispanキャッシュを更新し、特定のユーザー・セッションが site2 のKeycloakノードにも表示されます。

詳細は、アーキテクチャー図の例を参照してください。

この例では、 site1 と site2 という2つのデータセンター使用して説明します。各データセンターは、1つのInfinispanサーバーと2つのKeycloakサーバーで構成されています。合計すると、2つのInfinispanサーバーと4つのKeycloakサーバーになります。

この設定の例では、4つのKeycloakサーバーすべてが同じデータベースと通信することを前提としています。プロダクション環境では、データベースで説明されているとおり、データセンター間で別々の同期レプリケートされたデータベースを使用することをお勧めします。

このセクションでは、クロスデータセンター・レプリケーションに関するオプションとヒントについて説明します。

たとえば、以下のようなシナリオを想定します。

使用している環境に応じて、サイト間のネットワークが利用できないか、一時的に壊れている（スプリット・ブレイン）可能性があります。これが起こった場合、 site1 のInfinispanサーバーは、 site2 のInfinispanサーバーが利用できないことに気付き、 jdg2 サイトのサーバーへアクセスしようとするのを止めるため、バックアップの失敗は発生しません。これは サイトをオフラインにする と呼ばれています。

サイトをオフラインにするには2つの方法があります。

管理者による手作業 - 管理者は jconsole または他のツールを使用して、いくつかのJMX操作を実行することで、手動で特定のサイトをオフラインにすることができます。これは、特に停止が計画されている場合に役立ちます。 jconsole またはCLIを使用すると、 jdg1 サーバーに接続し、 site2 をオフラインにすることができます。この詳細については、 JDGドキュメント を参照してください。

自動的作業 - バックアップに失敗した後、通常は site2 が自動的にオフラインになります。これは、Infinispanサーバーの設定で設定されたキャッシュ設定内の take-offline 要素の設定によって行われます。

この例では、少なくとも3回連続して失敗したバックアップがあり、60秒以内にバックアップが成功しなかった場合、特定のシングルキャッシュに対してサイトが自動的にオフラインになることを示しています。

自動的にサイトをオフラインにすることは、特に、サイト間の切断されたネットワークが計画外である場合に便利です。欠点は、ネットワークの停止が検出されるまで何らかのバックアップが失敗し、アプリケーション側で障害が起きてる可能性があります。たとえば、一部のユーザーのログインに失敗したり、大きなログインタイムアウトが発生したりします。 特に、値が FAIL の failure-policy が使用されている場合です。

一旦ネットワークが復旧し、 site1 と site2 がお互いに通信することができたら、サイトをオンラインにする必要があります。これは、サイトをオフラインにするのと同じように、JMXまたはCLIを使用して手動で行う必要があります。再度キャッシュをすべてチェックし、オンラインにする必要があります。

サイトをオンラインにしたら、通常は次のようにするのが良いです。

ステート・トランスファーは、手動で行う必要があります。Infinispanサーバーはこれを自動的には行いません。たとえば、スプリット・ブレイン中は、誰がどのサイトを優先するかを管理者のみが決定することができます。したがって、ステート・トランスファーが両方のサイト間で双方向に、または site1 から site2 へのみ単方向で行われる必要がありますが、site2 から site1 への単方向は行われません。

双方向のステート・トランスファーによって、スプリット・ブレインの 後に site1 で作成されたエンティティーが site2 に確実に転送されます。これは site2 ではまだ発生していないので問題ありません。同じように、スプリット・ブレインの 後に site2 で作成されたエンティティーは site1 に転送されます。おそらく問題のある部分は、両方のサイトのスプリット・ブレインの 前に 存在し、両方のサイトのスプリット・ブレイン中に更新されたエンティティーです。これが発生すると、サイトの1つが 勝ち 、2番目のサイトがスプリット・ブレイン中に行った更新を上書きします。

残念ながら、これに対する広く一般的な解決方法はありません。スプリット・ブレインやネットワークの停止は状態に過ぎず、サイト間で100%の一貫性のあるデータで100%正確に処理することは通常不可能です。Keycloakの場合、これは特に重大な問題ではありません。最悪の場合、ユーザーがクライアントに再度ログインするか、loginFailuresの不正カウント数をブルートフォース保護のために追跡する必要があります。スプリット・ブレインに対処するためのヒントについては、Infinispan/JGroupsドキュメントを参照してください。

ステート・トランスファーは、JMXを介してInfinispanサーバー側でも行われます。操作名は pushState です。状態をモニタリングしたり、プッシュ状態をキャンセルしたりするその他の操作はほとんどありません。ステート・トランスファーの詳細については、 Infinispan docs を参照してください。

スプリット・ブレイン後は、Keycloakの管理コンソールで手動でキャッシュをクリアするのが安全です。これは、 site1 のデータベースで変更されたデータがあり、イベントのために無効にする必要のあるキャッシュが、スプリット・ブレイン中に site2 へ転送されなかった可能性があるためです。したがって、 site2 のKeycloakノードでは、キャッシュ内に古いデータがまだ残っている可能性があります。

キャッシュをクリアするには、 サーバー・キャッシュのクリア を参照してください。

ネットワークが復旧したら、いずれかのサイトの1つのKeycloakノードでキャッシュをクリアするだけで十分です。キャッシュの無効化イベントは、それぞれのサイトの他のKeycloakノードすべてに送られます。ただし、すべてのキャッシュ（レルム、ユーザー、鍵）に対して実行する必要があります。詳しくは、サーバー・キャッシュのクリアを参照してください。

このセクションでは、JDGキャッシュを設定するためのヒントとオプションについて説明します。

デフォルトでは、JDGの clustered.xml ファイル内にあるInfinispanキャッシュ設定のバックアップの設定 failure-policy が FAIL に設定されています。必要に応じて WARN または IGNORE に変更できます。

FAIL と WARN の違いは、 FAIL が使用され、Infinispanサーバーが別のサイトにデータのバックアップを試みたときに、バックアップが失敗すると、その失敗が呼び出し側（Keycloakサーバー）に伝播されるという点です。2番目のサイトが一時的に到達不能になったり、同じエンティティーの更新を試みる同時トランザクションが発生した場合は、バックアップが失敗する可能性があります。この場合、Keycloakサーバーは複数回再試行します。ただし、その再試行が失敗した場合、より長いタイムアウト後、ユーザーにはエラーが表示されます。

WARN を使用すると、失敗したバックアップは、InfinispanサーバーからKeycloakサーバーに伝播されません。失敗したバックアップは無視され、ユーザーにはエラーが表示されません。バックアップのデフォルトのタイムアウトは10秒間であるため短いです。これは、 backup 要素の timeout 属性によって変更することができます。タイムアウトにおける再試行はありません。タイムアウト時は、InfinispanサーバーのログにWARNINGメッセージが表示されます。

潜在的な課題としては、いくつかのケースで、再試行（ FAIL ポリシーの使用）が役に立つサイト間で短いネットワーク停止が発生する可能性があるため、 WARN （再試行なし）では、サイト間でデータの不整合が発生します。これは、両方のサイトで同時に同じエンティティーを更新しようとする際にも発生します。

これらの不整合はどれほど悪いことなのでしょうか。通常は、ユーザーが再認証する必要があることだけを意味します。

WARN ポリシーを使用すると、 actionTokens キャッシュにより提供され、その特定のキーを処理する、使い捨てのキャッシュが実際に1回使用されますが、同じキーが2回"正常に"書き込まれる可能性があります。しかし、たとえば、OAuth2 仕様では、コードは使い捨てでなければならないと言及されています。 WARN ポリシーでは、これは厳密には保証されておらず、両方のサイトで同時に書き込まれる試みがあった場合、同じコードが2回書き込まれる可能性があります。

より長いネットワーク停止またはスプリット・ブレインが起きた場合、 FAIL と WARN を使用すると、サイトをオフラインおよびオンラインにするで説明したとおり、少し時間を置いて失敗した後、他のサイトはオフラインになります。デフォルトの1分のタイムアウトでは、関連するキャッシュがすべてオフラインになるまで、通常は1～3分かかります。その後、エンドユーザーの観点から、動作はすべて問題なく進みます。サイトをオフラインおよびオンラインにするで説明したとおり、オンラインに戻ったときに手動でサイトを復元する必要があります。

要約すると、サイト間で頻繁により長い停止が発生する可能性があり、データの不整合と100%正確ではない使い捨てのキャッシュについては許容されますが、エラーや長いタイムアウトがエンドユーザーに表示されないようにする場合には、 WARN に切り替えます。

WARN と IGNORE の違いは、 IGNORE では警告がJDGログに書き込まれていないことです。詳細については、Infinispanのドキュメントを参照してください。

デフォルト設定では、NON_DURABLE_XAモードでトランザクションを取得タイムアウト0で使用しています。これは、同じキーに対して進行中の別のトランザクションがある場合、トランザクションはすぐに失敗することを意味します。

デフォルトの10秒ではなく0に切り替えるのは、デッドロックの可能性を避けるためです。Keycloakでは、同じエンティティー（通常はセッション・エンティティーまたはloginFailure）が両方のサイトから同時に更新されることがあります。これにより、状況によってはデッドロックが発生し、トランザクションが10秒間ブロックされる可能性があります。 詳細については、このJIRAレポートを参照してください。

タイムアウト0の場合、トランザクションは直ちに失敗し、値 FAIL のバックアップ failure-policy が設定されていれば、Keycloakから再試行されます。2番目の同時トランザクションが終了するまで、通常は再試行が成功し、エンティティーは両方の同時トランザクションから更新を適用します。

この設定での同時トランザクションは、非常に良い一貫性と結果が得られるため、そのまま使用することをお勧めします。

唯一の（機能しない）問題は、Infinispanサーバーログの例外です。これは、ロックがすぐに利用できなくなるたびに発生します。

backup 要素の重要な部分は strategy 属性です。 SYNC と ASYNC のどちらが必要かを決める必要があります。クロスデータセンター・レプリケーションを認識できる7つのキャッシュがあり、これらは、クロスデータセンターに対する次の3つの異なるモードで設定できます。

SYNC バックアップが使用された場合、バックアップが同期され、バックアップが2番目のサイトで処理されると、呼び出し側（Keycloakサーバー）で操作が完了したとみなされます。これは ASYNC よりもパフォーマンスが劣りますが、一方で、 site2 のユーザー・セッションなど特定のエンティティーの後続の読み込みによって、 site1 からの更新が確実に確認されます。また、データの一貫性が必要な場合は、これは必須になります。 ASYNC の場合と同様に、他のサイトへのバックアップが失敗した場合は、呼び出し側には全く通知されません。

キャッシュによっては、バックアップをまったく取らず、Infinispanサーバーへのデータ書き込みを完全にスキップすることも可能です。これを設定するために、 Keycloak側（ KEYCLOAK_HOME/standalone/configuration/standalone-ha.xml ファイル）の特定のキャッシュに remote-store 要素を使用しないでください。また、特定の replicated-cache 要素もInfinispanサーバー側では必要ありません。

デフォルトでは、7つのキャッシュすべてが最も安全なオプションである SYNC バックアップで設定されています。考慮すべき点は次のとおりです。

データセンター間のネットワークが遅く、DoSの確率が高い環境では、 loginFailures キャッシュをまったくバックアップしないことが推奨されます。

一般的に、懸念があり、パフォーマンスがブロッカーではない場合は、キャッシュを SYNC 方式に保持する方が安全です。

cache-configuration要素の mode 属性に注意してください。

以下のヒントは、トラブルシューティングが必要な場合に役立ちます。

VARCHAR フィールドと CHAR フィールド内でユニコード・サポートを使用してデータベースを作成した場合は、ユニコード文字は適切に処理されます（例： AL32UTF8 文字セットがデータベース文字セットとして使用された場合）。JDBCドライバーに特別な設定は必要ありません。

データベース文字セットがユニコードではない場合、ユニコード文字を特別なフィールド内で使用するために、JDBCドライバーを設定して接続プロパティー oracle.jdbc.defaultNChar を true に設定する必要があります。厳密には必須ではないのですが、 oracle.jdbc.convertNcharLiterals 接続プロパティーも true にしておいた方が賢明です。これらのプロパティーは、システム・プロパティーまたは接続プロパティーとして設定することができます。しかし oracle.jdbc.defaultNChar の設定はパフォーマンスに悪影響を与える可能性がありますので、この点は注意してください。詳しくは、Oracle JDBCドライバーの設定ドキュメントを参照してください。

ユニコード文字は、特別なフィールドに対してのみ適切に処理されます。JDBCドライバーやデータベースの特別な設定は必要ありません。

CREATE DATABASE コマンドで、 VARCHAR と CHAR のフィールド内のユニコード・サポートを使用してデータベースが作成される場合は、ユニコード文字は適切に処理されます（例：MySQL 5.5でデフォルトのデータベース文字セットとして utf8 文字セットを使用する場合。 utf8 文字セットに求められるさまざまなストレージ要件により、 utf8mb4 文字セットは動作しませんので注意してください^[1]）。この場合、バイト数ではなく文字数に合わせて列が作成されるため、通常のフィールドには長さ制限は適用されないことに注意が必要です。データベースのデフォルト文字セットでユニコードの保存が許可されていない場合、特別なフィールドでのみユニコード値の保存が許可されることになります。

JDBCドライバー設定については、JDBC接続設定に接続プロパティー characterEncoding=UTF-8 を追加する必要があります。

データベース文字セットが UTF8 である場合、ユニコードはサポートされます。この場合、ユニコード文字はどのフィールドでも使用することができますが、通常フィールドではフィールド長は短縮されません。JDBCドライバーの特別な設定は必要ありません。

HTTPSトラフィックを処理するためにリバース・プロキシーまたはロードバランサーを使用していない場合、Keycloakサーバー用にHTTPSを有効にする必要があります。これには下記が含まれます。

Keycloakによって送信された送信HTTPリクエストは、プロキシー・マッピングのカンマで区切られたリストに基づいて、オプションでプロキシー・サーバーを使用できます。プロキシー・マッピングは、正規表現ベースのホスト名パターンと hostnamePattern;proxyUri 形式のproxy-uriの組み合わせを示します。例：

送信するHTTPリクエストのプロキシーを判別するために、ターゲットホスト名が、設定されたホスト名パターンと照合されます。最初に一致するパターンで、使用するproxy-uriが決定します。指定されたホスト名と一致する設定済みのパターンが無い場合、プロキシーは使用されません。

proxy-uriに対する特別な値 NO_PROXY は、関連するホスト名パターンと一致するホストに対して、プロキシーを使用しないことを示すために使用できます。プロキシー・マッピングの終わりにcatch-allパターンを指定して、送信するすべてのリクエストのデフォルト・プロキシーを定義することが可能です。

次の例は、プロキシー・マッピングの設定を示しています。

これは、以下の jboss-cli コマンドで設定できます。以下に示す正規表現パターンを適切にエスケープする必要があることに注意してください。

jboss-cli コマンドの結果、以下のサブシステム設定になります。 " で " 文字をエンコードする必要があることに注意してください。

KeycloakがリモートのHTTPSエンドポイントを呼び出す場合、信頼できるサーバーへの接続かどうかを確認するために、リモートサーバーの証明書を検証する必要があります。これは、中間者攻撃を防ぐために必要です。リモートサーバーや署名した認証局の証明書は、トラストストアに保存されている必要があります。このトラストストアは、Keycloakサーバーによって管理されます。

トラストストアは、アイデンティティー・ブローカーやLDAPアイデンティティー・プロバイダーに安全に接続する場合、電子メールを送信する場合、およびクライアント・アプリケーションとのバックチャネル通信をする場合に使用されます。

keytool を使用し、新しいトラストストア・ファイルを作成、または信頼できるホスト証明書を既存のトラストストア・ファイルに追加することができます。

トラストストアは、配布物内の standalone.xml 、 standalone-ha.xml または domain.xml で設定されます。このファイルの場所は、動作モードによって異なります。以下のテンプレートを使用して、トラストストア設定を追加することができます。

設定可能なオプションは以下のとおりです。

Keycloakのいくつかの機能は、認証サーバーに接続するHTTPクライアントのリモート・アドレスがクライアント・マシンの実際のIPアドレスであることを前提としています。例は、以下のとおりです。

Keycloak認証サーバーの前にリバース・プロキシーまたはロードバランサーが置いてある場合、問題になる可能性があります。通常の設定では、パブリック・ネットワーク上にフロントエンドのプロキシーを置いています。このプロキシーはプライベート・ネットワーク内のバックエンドのKeycloakサーバー・インスタンスに負荷を分散してリクエストを転送するものです。実際のクライアントIPアドレスが転送され、Keycloakサーバー・インスタンスによって処理されるように、追加設定する必要があります。具体的には以下のとおりです。

X-Forwarded-For 、 X-Forwarded-Proto HTTPヘッダーを生成するためにプロキシーを設定し、オリジナルの Host HTTPヘッダーを保持する方法については、このガイドの説明範囲を超えています。 X-Forwarded-For ヘッダーがプロキシーによって設定されているか、特に注意して確認してください。プロキシーが正しく設定されていない場合、不正な クライアントがこのヘッダーを自身で設定して、クライアントが実際とは異なるIPアドレスから接続しているとKeycloakに認識させることができてしまいます。IPアドレスのブラックリストまたはホワイトリストを作成している場合、この設定は非常に重要です。

プロキシーの他にも、いくつかKeycloak側で設定する必要があります。プロキシーがHTTPプロトコル経由でリクエストを転送している場合、クライアントのIPアドレスをネットワーク・パケットからではなく X-Forwarded-For ヘッダーから取得するように、Keycloakを設定する必要があります。これを行うには、プロファイル設定ファイル（動作モードに応じて standalone.xml 、 standalone-ha.xml または domain.xml ）を開き、 urn:jboss:domain:undertow:9.0 XMLブロックを検索します。

http-listener 要素に proxy-address-forwarding 属性を追加します。値を true に設定します。

プロキシーがリクエストを転送するためにHTTPの代わりにAJPプロトコルを使用している場合（サンプルとしては、Apache HTTPD + mod-clusterなど）、少し異なる設定が必要になります。 http-listener を変更する代わりに、AJPパケットからこの情報を取得するフィルターを追加する必要があります。

リバース・プロキシーがSSL用にポート8443を使用しない場合、HTTPSトラフィックのどのポートをリダイレクトするか設定する必要があります。

http-listener 要素に redirect-socket 属性を追加します。値には proxy-https を設定しますが、これは定義が必要なソケット・バインディングを指しています。

次に、新しい socket-binding 要素を socket-binding-group 要素に追加します。以下のようになります。

リバース・プロキシー経由で /auth/realms/master/.well-known/openid-configuration のパスを開き、リバース・プロキシーまたはロードバランサーの設定を確認することができます。たとえば、リバース・プロキシーのアドレスが https://acme.com/ の場合、 https://acme.com/auth/realms/master/.well-known/openid-configuration のURLを開きます。そうすると、Keycloakのいくつかのエンドポイントを示すJSONドキュメントが表示されます。エンドポイントが、リバース・プロキシーまたはロードバランサーのアドレス（スキーム、ドメイン、ポート）で始まることを確認します。このようにして、Keycloakが正しいエンドポイントを使用しているか確認します。

また、KeycloakがリクエストのソースIPアドレスを正しく認識しているか確認する必要があります。無効なユーザー名とパスワードの両方またはいずれかで管理コンソールにログインし、確認してください。これを行うと、サーバーログに以下のような警告が表示されます。

ipAddress の値はログインしようとしているマシンのIPアドレスで、リバース・プロキシーまたはロードバランサーのIPアドレスではないということを確認してください。

このセクションでは、クラスター構成ドメインのサンプルで説明している組み込みのロードバランサーの設定方法について説明します。

クラスター構成ドメインのサンプルは1台のマシンで実行するためにのみ作られています。他のホストでスレーブを起動するには、次の操作が必要です。

その他のソフトウェア・ベースのロードバランサーの使用方法については、 WildFly 17 Documentation 内のロードバランシングのセクションを参照してください。

いくつかのロードバランサーは、バックエンドのKeycloakノードに頼るのではなく、経路情報を自身で追加するように設定できます。ただし、前述のとおり、Keycloakによる経路の追加が推奨されます。これは、Keycloakが特定のセッションの所有者であり、必ずしもローカルノードではないノードにルーティングできるエンティティーを認識しているため、このようにパフォーマンスが向上するためです。

必要に応じて、Keycloakサブシステム設定の RHSSO_HOME/standalone/configuration/standalone-ha.xml ファイルに以下を追加することにより、AUTH_SESSION_ID Cookieへの経路情報の追加を無効にすることができます。