8.2. キャッシュを設定する
Red Hat build of Keycloak は、conf/cache-ispn.xml に置かれた適切なデフォルトを含むキャッシュ設定ファイルを提供します。
キャッシュ設定は、通常の nfinispan configuration file です。
次の表は、Red Hat build of Keycloak が使用する特定のキャッシュの概要を示しています。これらのキャッシュは、conf/cache-ispn.xml で設定します。
| キャッシュ名 | キャッシュタイプ | 説明 |
|---|---|---|
| realms | Local | 永続化されたレルムデータをキャッシュします |
| users | Local | 永続化されたユーザーデータをキャッシュします |
| authorization | Local | 永続化された認可データをキャッシュします |
| keys | Local | 外部公開鍵をキャッシュします |
| work | Replicated (レプリケート) | 無効化メッセージをノード間で伝播します |
| authenticationSessions | Distributed (分散) | 認証プロセス中に作成/破棄された、または期限切れになった認証セッションをキャッシュします。 |
| sessions | Distributed (分散) | 認証の成功時に作成され、ログアウト、トークンの失効中、または有効期限切れが原因で破棄されたユーザーセッションをキャッシュします。 |
| clientSessions | Distributed (分散) | 特定のクライアントに対する認証の成功時に作成され、ログアウト、トークンの失効中、または有効期限切れが原因で破棄されたクライアントセッションをキャッシュします。 |
| offlineSessions | Distributed (分散) | 認証の成功時に作成され、ログアウト、トークンの失効中、または有効期限切れが原因で破棄されたオフラインユーザーセッションをキャッシュします。 |
| offlineClientSessions | Distributed (分散) | 特定のクライアントに対する認証の成功時に作成され、ログアウト、トークンの失効中、または有効期限切れが原因で破棄されたクライアントセッションをキャッシュします。 |
| loginFailures | Distributed (分散) | 失敗したログイン (不正の検知) を追跡します |
| actionTokens | Distributed (分散) | アクショントークンをキャッシュします |
8.2.1. キャッシュタイプとデフォルト
ローカルキャッシュ
Red Hat build of Keycloak は、データベースへの不必要なラウンドトリップを回避するために、永続データをローカルにキャッシュします。
次のデータは、ローカルキャッシュを使用して、クラスター内の各ノードのローカルに保持されます。
- レルム と、クライアント、ロール、グループなどの関連データ。
- ユーザー と、付与されたロールやグループメンバーシップなどの関連データ。
- 認可 と、リソース、権限、ポリシーなどの関連データ。
- keys
レルム、ユーザー、認可のローカルキャッシュは、デフォルトで最大 10,000 エントリーを保持するように設定されています。デフォルトで、ローカルキーキャッシュは最大 1,000 エントリーを保持でき、1 時間ごとに期限切れになります。したがって、外部クライアントまたはアイデンティティープロバイダーからキーを定期的にダウンロードする必要があります。
最適な実行時間を実現し、データベースへの追加のラウンドトリップを回避するには、各キャッシュの設定で、エントリーの最大数がデータベースのサイズと一致していることを確認する必要があります。キャッシュできるエントリーが増えると、サーバーがデータベースからデータを取得しなければならない回数が少なくなります。メモリーの使用率とパフォーマンスの間で何が犠牲になるかを評価する必要があります。
ローカルキャッシュの無効化
ローカルキャッシュによりパフォーマンスは向上しますが、マルチノードセットアップでは課題が発生します。
1 つの Red Hat build of Keycloak ノードが共有データベース内のデータを更新すると、他のすべてのノードはそれを認識する必要があるため、キャッシュからそのデータを無効にします。
work キャッシュはレプリケートされたキャッシュであり、これらの無効化メッセージの送信に使用されます。このキャッシュのエントリー/メッセージは有効期限が非常に短いため、このキャッシュのサイズが時間の経過とともに増加することを想定する必要はありません。
認証セッション
ユーザーが認証を試みるたびに、認証セッションが作成されます。これらは、認証プロセスが完了するか、有効期限に達すると自動的に破棄されます。
authenticationSessions 分散キャッシュは、認証プロセス中に、認証セッションとそれに関連する他のデータを保存するために使用されます。
分散可能キャッシュに依存すると、クラスター内のどのノードでも認証セッションを利用できるため、ユーザーは認証状態を失うことなく任意のノードにリダイレクトできます。ただし、実稼働環境に対応したデプロイメントでは、常にセッションアフィニティーを考慮し、セッションが最初に作成されたノードにユーザーをリダイレクトすることを優先する必要があります。これにより、ノード間の不要な状態遷移が回避され、CPU、メモリー、ネットワークの使用率が向上します。
ユーザーセッション
ユーザーが認証されると、ユーザーセッションが作成されます。ユーザーセッションはアクティブユーザーとその状態を追跡するため、認証情報を再度要求されることなく、あらゆるアプリケーションに対してシームレスに認証できるようになります。アプリケーションごとに、ユーザーは作成されたクライアントセッションでも認証されるため、サーバーは、ユーザーが認証されたアプリケーションとその状態をアプリケーションごとに追跡できます。
ユーザーセッションとクライアントセッションは、ユーザーがログアウトを実行するとき、クライアントがトークンの取り消しを実行するとき、または有効期限に達したときに自動的に破棄されます。
次のキャッシュは、ユーザーセッションおよびクライアントセッションを保存するために使用されます。
- sessions
- clientSessions
分散可能キャッシュに依存すると、クラスター内のどのノードでもユーザーセッションとクライアントセッションを利用できるため、状態遷移を発生させることなくユーザーを任意のノードにリダイレクトできます。ただし、実稼働環境に対応したデプロイメントでは、常にセッションアフィニティーを考慮し、セッションが最初に作成されたノードにユーザーをリダイレクトすることを優先する必要があります。これにより、ノード間の不要な状態遷移が回避され、CPU、メモリー、ネットワークの使用率が向上します。
サーバーは、OpenID Connect プロバイダーとしてユーザーを認証し、オフライントークンを発行することもできます。通常のユーザーセッションやクライアントセッションと同様に、サーバーは認証成功時にオフライントークンを発行すると、オフラインユーザーセッションとオフラインクライアントセッションも作成します。ただし、オフライントークンの性質上、オフラインセッションの有効期間は長く、クラスターを完全にシャットダウンしても存続するため、オフラインセッションの処理は異なります。そのため、データベースでも永続化されます。
次のキャッシュは、オフラインセッションを保存するために使用されます。
- offlineSessions
- offlineClientSessions
クラスターを再起動すると、オフラインセッションはデータベースから遅延してロードされ、上記の 2 つのキャッシュを使用して共有キャッシュに保持されます。
パスワードのブルートフォース検出
loginFailures 分散キャッシュは、失敗したログイン試行に関するデータを追跡するために使用されます。このキャッシュは、マルチノード Red Hat build of Keycloak セットアップでブルートフォース保護機能が動作するために必要です。
アクショントークン
アクショントークンは、たとえばパスワードを忘れた場合のフローで送信されるメールなど、アクションを非同期で確認する必要がある場合に使用されます。actionTokens 分散キャッシュは、アクショントークンに関するメタデータを追跡するために使用されます。
8.2.2. 可用性のためのキャッシュ設定
分散キャッシュは、クラスター内のノードのサブセットでキャッシュエントリーをレプリケートし、エントリーを固定所有者ノードに割り当てます。
デフォルトでは、各分散キャッシュには 2 人の所有者がいます。これは、2 つのノードが特定のキャッシュエントリーのコピーを持つことを意味します。非所有者ノードは、データを取得するために、特定のキャッシュの所有者にクエリーを実行します。両方の所有者ノードがオフラインになると、すべてのデータが失われます。通常この状況では、次の要求時にユーザーはログアウトされ、再度ログインする必要があります。
デフォルトの所有者数は、3 つ以上のノードを持つクラスターセットアップで 1 つのノード (所有者) で障害が発生しても継続できる数です。所有者の数は、可用性要件に合わせて自由に変更できます。所有者の数を変更するには、conf/cache-ispn.xml を開き、分散キャッシュの owner=<value> 値を任意の値に変更します。
8.2.3. 独自のキャッシュ設定ファイルを指定する
独自のキャッシュ設定ファイルを指定するには、次のコマンドを入力します。
bin/kc.[sh|bat] build --cache-config-file=my-cache-file.xml
設定ファイルは conf/ ディレクトリーに相対的です。
8.2.4. リモートサーバーの CLI オプション
高可用性用およびマルチノードのクラスター化セットアップ用に Red Hat build of Keycloak サーバーを設定するために、CLI オプション cache-remote-host、cache-remote-port、cache-remote-username、cache-remote-password が導入され、XML ファイル内の設定が簡素化されました。上記の CLI パラメーターのいずれかが存在する場合、XML ファイル内にリモートストアに関連する設定が存在しないしないものと想定されます。
