bin/kc.[sh|bat] [start-dev|build|start] --features="persistent-user-sessions"
2024年6月12日 アレクサンダー・シュワルツ 著
以前のバージョンの Keycloak では、通常のユーザーセッション (オンラインユーザーセッションとも呼ばれます) はメモリにのみ保存されていました。そのため、Keycloak クラスタをシャットダウンまたは再起動すると、すべてのユーザーがログアウトされました。
Keycloak 25 では、「永続ユーザーセッション」というプレビュー機能が導入され、ユーザーセッションがデータベースに保存されるようになりました。セッションがメモリに見つからない場合、データベースからロードされ、ユーザーは再認証なしでセッションを継続できます。
このプレビュー機能はデフォルトでは無効になっており、試してみるには persistent-user-sessions 機能フラグを有効にする必要があります。
この機能を完全にサポートするために、この GitHub ディスカッション スレッドでフィードバックを提供することでご協力いただけます。6月24日には、永続セッションに関する Ask Me Anything セッションを予定しています。
この機能を有効にすると、Keycloak のメモリ使用量は減少し、データベースの使用量が増加する可能性があります。
Keycloak のキャッシュ構成 XML ファイルで最大サイズが構成されていない場合、Keycloak はデフォルトで、セッション、clientSessions、offlineSessions、offlineClientSessions の各キャッシュに対して最大 10,000 エントリになります。より多くのセッションをメモリに保持したい場合は、異なるサイズを構成する方法について分散キャッシュの構成を参照してください。
オプション spi-user-sessions-infinispan-offline-session-cache-entry-lifespan-override および spi-user-sessions-infinispan-offline-client-session-cache-entry-lifespan-override は、代わりに最大エントリ サイズが使用されるため、無視されます。
外部 Infinispan インスタンスは、Keycloak のマルチサイト セットアップでサポートされています。このようなセットアップを使用し、永続ユーザーセッションを有効にしている場合は、外部 Infinispan のメモリ消費を制限するために、外部 Infinispan に保持するセッションの最大数を設定できます (また、設定する必要があります)。Infinispan キャッシュでのエビクションの構成方法については、Infinispan のドキュメントのエビクションの構成を参照してください。
同時ユーザーセッションの数が Keycloak の最大キャッシュ サイズを超えると、たとえばトークンが更新されたり、ユーザー情報エンドポイントが呼び出されたりした場合に、データベースからセッションをロードするためのデータベース アクティビティが増加します。これらのリクエストは、データベースの読み取りステートメントの応答時間に応じて、レイテンシの増加も発生させます。キャッシュヒット率を監視して、セットアップに最適化が必要かどうかを確認してください。
ログイン、トークン更新、ログアウトごとに、データベース内のセッションテーブルが更新され、データベース アクティビティの増加として表示されます。Keycloak は、同時セッション更新を単一のトランザクションにバンドルしようとしますが、それでもデータベースの CPU と IOPS の両方の使用率が大幅に増加します。これらのリクエストは、データベースの書き込みステートメントの応答時間に応じて、レイテンシの増加も発生させます。
環境への影響は、インフラストラクチャと使用パターンによって異なります。指標として、次のセットアップでテストを実行しました。
1秒あたり 150 ログインと 150 ログアウト
Aurora PostgreSQL リージョンデータベース 15.5
タイプ db.t4g.large サーバー (2 ARM vCPU コア、8 GB RAM)
ランタイムメトリクスに次の変更が見られました。
データベース上
1秒あたり 300 件の追加コミット
CPU 使用率は、同時セッション数に応じて 1 ～ 1.5 CPU コア増加
約 2500 追加の WriteIOPS
Keycloak 上
Keycloak の CPU 使用率は一定のまま
10,000 セッションが作成された後、メモリ使用率は一定
ログインとログアウトの 50 パーセンタイル応答時間は、シングル AZ データベースではそれぞれ 20 ms と 10 ms 増加し、2 つの AZ データベースではそれぞれ 30 ms と 20 ms 増加しました。
環境のベンチマークを実行することをお勧めします。Keycloak Benchmark Project で提供しているツールをツールボックスとして使用してください。
キャッシュと HTTP 応答時間に関する情報を監視するために Keycloak のメトリクスを有効にする方法については、Keycloak メトリクスの有効化を参照してください。
コミュニティは過去にさまざまな構成を評価しており、その一部には欠点があり、Keycloak によって公式にサポートされていませんでした。永続セッションが有効になっている場合、これらのセットアップを簡略化できます。
非常に大きな JVM ヒープ サイズでのデプロイメントの使用: 以前は、すべてのセッションをメモリに保持し、メモリ不足の状態を回避するために、大量の JVM メモリが必要でした。永続セッションがデータベースに保存され、キャッシュ用にメモリに保持されるのはサブセットのみであるため、Keycloak インスタンスに割り当てるメモリを削減できます。
一般的なアプローチの 1 つは、オフラインセッションを使用してユーザーをログイン状態に保つことでした。これは、以前からオフラインセッションがデータベースに永続化されていたためです。それでも、オフラインセッションは別の目的で使用されます。本来の目的は、ユーザーがログアウトした場合でも、アプリケーションがユーザーに代わってリソースにアクセスできるようにすることであり、通常のオンラインセッションのログアウトではこれらのセッションはログアウトされません。永続ユーザーセッションが有効になっている場合は、オンラインセッションの使用を開始する必要があります。既存のオフラインセッションは引き続き使用できますが、最終的には期限切れになります。
このセットアップでは、組み込み Infinispan はセッションをデータベースとカスタム作成されたテーブルに保存しました。これはログインとログアウトのデフォルト設定ですが、永続的でないユーザーセッションのコードはすべてのセッションがメモリにあることを前提としているため、すべてのセッションが起動時にロードされた場合にのみ実行されます。クライアントまたはレルムのセッションリストが不完全になり、たとえば特定のユーザーに対して単一のセッションのみを持つという制約が保証できなくなるため、すべてのセッションを起動時にロードする必要があります。Keycloak 25 のプレビュー機能としての永続セッションにより、この新しいアプローチは、セットアップの複雑さを軽減し、Keycloak と Infinispan の両方のメモリフットプリントを削減します。既存のセッションを移行する方法については、以下を参照してください。
このセットアップでは、Keycloak は外部 Infinispan に対してセッションを読み書きします。上記と同様に、クライアントまたはレルムのセッションリストが不完全になり、たとえば特定のユーザーに対して単一のセッションのみを持つという制約が保証できなくなるため、すべてのセッションを起動時に組み込み Infinispan と外部 Infinispan の両方にロードする必要があります。このようなセットアップは、Keycloak 24 以降のマルチサイト セットアップでのみサポートされていました。Keycloak 25 のプレビュー機能としての永続セッションにより、この新しいアプローチは、セットアップの複雑さを軽減し、Keycloak のメモリフットプリントを削減し、外部 Infinispan を実行する必要がなくなります。既存のセッションを移行する方法については、以下を参照してください。
Keycloak 24 で Keycloak オンラインセッションを保存するために、組み込み Infinispan に接続された JDBC ストア、または外部 Infinispan を使用していた場合は、Keycloak 25 を初めて起動するときに永続ユーザーセッションを有効にすると (およびその場合にのみ)、これらのセッションを移行できます。
移行が完了したら、組み込みセッションキャッシュの JDBC 永続化の構成を削除する必要があります。シングルサイトセットアップで使用している場合は、外部 Infinispan への接続も削除する必要があります。
これはプレビュー機能であるため、デフォルトでは有効になっていません。この機能が完全にサポートされていると見なされたら、将来のリリースでデフォルトで有効にする予定です。
すでに Keycloak 25 に移行している場合は、セットアップから既存のすべてのオンラインユーザーセッションをクリアすることをお勧めします。
開発環境で使用しているか、Keycloak ディストリビューションを構築しているか、または起動時に Keycloak の自動再構築に依存しているかによって、コマンドは次のようになります。
bin/kc.[sh|bat] [start-dev|build|start] --features="persistent-user-sessions"
環境変数を使用してオプションを設定する場合は、次の環境変数を設定するか、環境変数がすでに存在する場合は値を追加します。
KC_FEATURES=persistent-user-sessions
Keycloak Operator を使用している場合は、Keycloak CR の有効な機能に追加します。
apiVersion: k8s.keycloak.org/v2alpha1
kind: Keycloak
metadata:
name: example-kc
spec:
features:
enabled:
- persistent-user-sessions
...
機能の有効化方法の詳細については、機能の有効化と無効化を参照してください。
この機能を完全にサポートするために取り組んでいますが、同様の機能にも取り組んでいます。一部は Keycloak のデプロイメントを簡素化し、その他は最終的に Keycloak マルチサイト アクティブ/アクティブ セットアップを可能にするでしょう。
これらの機能のディスカッションに参加して、賛成票を投じてください。そうすれば、あなたが関心を持っていることがわかります。
アイデアとエッジケースについて議論し、コードを貢献し、中間プルリクエストとバージョンのテストを実行した Keycloak チームメンバーの Kamesh Akella、Michal Hajas、Pedro Ruivo、Anna Manukyan、Ryan Emerson に感謝します。GitHub ディスカッションに参加し、フィードバックを提供してくれたコミュニティメンバーの Tristan971、daviddelannoy、Thomas Darimont にも特別な感謝を申し上げます。
プレビュー機能を試して、この GitHub ディスカッション スレッドでフィードバックを提供することで、この機能を完全にサポートするためにご協力いただけます。
このスレッドを使用して、永続ユーザーセッションに関する質問もしてください。6月24日には、永続セッションに関する Ask Me Anything セッションを予定しています。