分散キャッシュの設定

Keycloak は、データベースへの不要なラウンドトリップを避けるために、永続データをローカルにキャッシュします。

次のデータは、ローカルキャッシュを使用してクラスタ内の各ノードにローカルに保持されます。

realms、users、authorization のローカルキャッシュは、デフォルトで最大 10,000 エントリを保持するように構成されています。ローカルキーキャッシュは、デフォルトで最大 1,000 エントリを保持でき、デフォルトで 1 時間ごとに期限切れになります。したがって、キーは外部クライアントまたはアイデンティティプロバイダーから定期的にダウンロードされる必要があります。

最適なランタイムを実現し、データベースへの追加のラウンドトリップを避けるために、各キャッシュの構成を確認して、エントリの最大数がデータベースのサイズと一致していることを確認する必要があります。キャッシュできるエントリが多いほど、サーバーがデータベースからデータをフェッチする必要が少なくなります。メモリ使用量とパフォーマンスのトレードオフを評価する必要があります。

ローカルキャッシュはパフォーマンスを向上させますが、マルチノード構成では課題が追加されます。

1 つの Keycloak ノードが共有データベース内のデータを更新すると、他のすべてのノードはそれを認識し、キャッシュからそのデータを無効にする必要があります。

work キャッシュはレプリケートされたキャッシュであり、これらの無効化メッセージを送信するために使用されます。このキャッシュのエントリ/メッセージは非常に短命であり、このキャッシュのサイズが時間の経過とともに大きくなることは想定されていません。

ユーザーが認証を試みるたびに、認証セッションが作成されます。認証プロセスが完了するか、有効期限に達すると、自動的に破棄されます。

authenticationSessions 分散キャッシュは、認証セッションと、認証プロセス中に関連付けられたその他のデータを格納するために使用されます。

分散キャッシュに依存することで、認証セッションはクラスタ内の任意のノードで使用できるようになり、ユーザーは認証状態を失うことなく任意のノードにリダイレクトできます。ただし、本番環境対応のデプロイメントでは、常にセッションアフィニティを考慮し、ユーザーをセッションが最初に作成されたノードにリダイレクトすることを優先する必要があります。そうすることで、ノード間の不要な状態転送を回避し、CPU、メモリ、ネットワークの使用率を向上させることができます。

ユーザーが認証されると、ユーザーセッションが作成されます。ユーザーセッションは、アクティブなユーザーとその状態を追跡するため、ユーザーは資格情報を再度求められることなく、任意のアプリケーションにシームレスに認証できます。アプリケーションごとに、ユーザーはクライアントセッションで認証するため、サーバーはユーザーが認証されているアプリケーションとその状態をアプリケーションごとに追跡できます。

ユーザーおよびクライアントセッションは、ユーザーがログアウトを実行した場合、クライアントがトークン失効を実行した場合、または有効期限に達した場合に自動的に破棄されます。

セッションデータは、デフォルトでデータベースに格納され、オンデマンドで次のキャッシュにロードされます。

分散キャッシュに依存することで、キャッシュされたユーザーおよびクライアントセッションはクラスタ内の任意のノードで使用できるようになり、ユーザーはデータベースからセッションデータをロードする必要なく、任意のノードにリダイレクトできます。ただし、本番環境対応のデプロイメントでは、常にセッションアフィニティを考慮し、ユーザーをセッションが最初に作成されたノードにリダイレクトすることを優先する必要があります。そうすることで、ノード間の不要な状態転送を回避し、CPU、メモリ、ネットワークの使用率を向上させることができます。

ユーザーセッションおよびクライアントセッションのこれらのインメモリキャッシュは、デフォルトでノードあたり 10000 エントリに制限されており、大規模なインストールにおける Keycloak の全体的なメモリ使用量を削減します。内部キャッシュは、各キャッシュエントリに対して単一のオーナーのみで実行されます。メモリ消費量とデータベース使用率のトレードオフを考慮し、キャッシュのサイズを異ならせて設定し、Keycloak のキャッシュ構成ファイル (conf/cache-ispn.xml) を編集して、これらのキャッシュに <memory max-count="..."/> を設定します。

デフォルトでは、ユーザーセッションはデータベースに格納され、オンデマンドでキャッシュにロードされます。ユーザーセッションをキャッシュのみに格納し、データベースの使用率を最小限に抑えるように Keycloak を構成することができます。

この設定ではすべてのセッションがインメモリに格納されるため、これに関連する 2 つの副作用があります。

この設定を有効にするには、次の手順に従います。

OpenID Connect プロバイダーとして、サーバーはユーザーを認証し、オフライン トークンを発行することもできます。通常のユーザーセッションおよびクライアントセッションと同様に、オフライン トークンが認証成功時にサーバーによって発行されると、サーバーはオフラインユーザーセッションおよびオフラインクライアントセッションも作成します。

次のキャッシュは、オフラインセッションを格納するために使用されます。

通常のユーザーセッションおよびクライアントセッションキャッシュと同様に、オフラインユーザーセッションキャッシュおよびクライアントセッションキャッシュも、デフォルトでノードあたり 10000 エントリに制限されています。メモリから削除された項目は、必要に応じてデータベースからオンデマンドでロードされます。メモリ消費量とデータベース使用率のトレードオフを考慮し、キャッシュのサイズを異ならせて設定し、Keycloak のキャッシュ構成ファイル (conf/cache-ispn.xml) を編集して、これらのキャッシュに <memory max-count="..."/> を設定します。

loginFailures 分散キャッシュは、失敗したログイン試行に関するデータを追跡するために使用されます。このキャッシュは、マルチノード Keycloak セットアップでブルートフォース保護機能を動作させるために必要です。

アクション トークンは、ユーザーがアクションを非同期的に確認する必要があるシナリオ (たとえば、パスワード忘れフローによって送信される電子メールなど) で使用されます。actionTokens 分散キャッシュは、アクション トークンに関するメタデータを追跡するために使用されます。

メモリ使用量を削減するために、特定のキャッシュに格納されるエントリ数に上限を設定することができます。キャッシュの上限を指定するには、次のコマンドライン引数 --cache-embedded-${CACHE_NAME}-max-count= を指定する必要があります。${CACHE_NAME} は、上限を適用するキャッシュの名前に置き換えます。たとえば、offlineSessions キャッシュに 1000 の上限を適用するには、--cache-embedded-offline-sessions-max-count=1000 を構成します。上限は、actionToken、authenticationSessions、loginFailures、work キャッシュには定義できません。

分散キャッシュは、クラスタ内のノードのサブセットにキャッシュエントリをレプリケートし、エントリを固定オーナーノードに割り当てます。

データの主要なソースである各分散キャッシュ (authenticationSessions、loginFailures、actionTokens) には、デフォルトで 2 つのオーナーがあります。つまり、2 つのノードが特定のキャッシュエントリのコピーを持っています。オーナーノードではないノードは、特定のキャッシュのオーナーにクエリを実行してデータを取得します。両方のオーナーノードがオフラインの場合、すべてのデータが失われます。

デフォルトのオーナー数は、少なくとも 3 つのノードを持つクラスタ構成で 1 つのノード (オーナー) の障害を乗り切るのに十分です。可用性の要件に合わせてオーナー数を自由に変更できます。オーナー数を変更するには、conf/cache-ispn.xml を開き、分散キャッシュの owners=<value> の値を目的の値に変更します。

独自のキャッシュ構成ファイルを指定するには、次のコマンドを入力します。

構成ファイルは conf/ ディレクトリからの相対パスです。

高可用性とマルチノードクラスタ構成のための Keycloak サーバーの構成のために、XML ファイル内の構成を簡素化する次の CLI オプション cache-remote-host、cache-remote-port、cache-remote-username、および cache-remote-password が導入されました。宣言された CLI パラメータのいずれかが存在する場合、XML ファイルにリモートストアに関連する構成が存在しないことが想定されます。

次の表は、--cache-stack ランタイムオプションを使用する以外に、追加の構成なしで利用できるトランスポートスタックを示しています。

次の表は、--cache-stack ランタイムオプションと最小限の構成を使用して利用できるトランスポートスタックを示しています。

tcp、udp、または jdbc-ping-udp スタックを使用する場合、各クラスタは、ノードが個別のクラスタを形成するように、異なるマルチキャストアドレスおよび/またはポートを使用する必要があります。デフォルトでは、Keycloak は jgroups.mcast_addr のマルチキャストアドレスとして 239.6.7.8 を、jgroups.mcast_port のマルチキャストポートとして 46655 を使用します。

標準的なセットアップには推奨されませんが、特定のセットアップで不可欠な場合は、トランスポートスタックの証明書を使用してキーストアを手動で構成できます。cache-embedded-mtls-key-store-file はキーストアへのパスを設定し、cache-embedded-mtls-key-store-password はそれを復号化するためのパスワードを設定します。トラストストアには、接続を受け入れるための有効な証明書が含まれており、cache-embedded-mtls-trust-store-file (トラストストアへのパス) および cache-embedded-mtls-trust-store-password (それを復号化するためのパスワード) で構成できます。不正アクセスを制限するには、常に各 Keycloak デプロイメントに自己署名証明書を使用してください。