1.6. 新機能および機能拡張

Red Hat build of Keycloak は OpenJDK 21 をサポートするようになりました。OpenJDK 17 のサポートは非推奨となり、次のリリースでは削除され、代わりに OpenJDK 21 が採用される予定です。

Keycloak JavaScript アダプターはスタンドアロンライブラリーになったため、Red Hat build of Keycloak サーバーから静的に提供されなくなりました。目標は、ライブラリーを Red Hat build of Keycloak サーバーから切り離し、独立してリファクタリングできるようにし、コードを簡素化し、今後のメンテナンスを容易にすることです。さらに、ライブラリーはサードパーティーの依存関係がなくなったため、より軽量になり、さまざまな環境で使いやすくなりました。

変更点の詳細は、アップグレードガイド を参照してください。

このリリースでは組織が導入されています。この機能は、Red Hat build of Keycloak の既存のアイデンティティーおよびアクセス管理 (IAM) 機能を活用して、Business-to-Business (B2B) や Business-to-Business-to-Consumer (B2B2C) の統合などの顧客アイデンティティーおよびアクセス管理 (CIAM) ユースケースに対応します。この機能の最初のリリースでは、レルムの既存の機能を使用することで、レルムがビジネスパートナーや顧客と統合できるようにするコア機能が提供されます。

詳細は、組織の管理 を参照してください。

レルム内に同じソーシャルブローカーのインスタンスを複数指定できるようになりました。

通常、レルムには同じソーシャルブローカーに複数のインスタンスは必要ありません。ただし、organization 機能を使用すると、ソーシャルブローカーが同じでインスタンスが異なる場合に、異なる組織にリンクできます。

ソーシャルブローカーを作成するときは、Alias を指定し、必要に応じて他のブローカーと同様に Display name を指定します。

アイデンティティープロバイダーが多数あるレルムと組織のスケーリングを支援するために、レルム表現にはアイデンティティープロバイダーのリストが保持されなくなりました。ただし、レルムをエクスポートするときには、レルム表現から引き続き使用できます。

詳細は、アイデンティティープロバイダー を参照してください。

以前のバージョンの Red Hat build of Keycloak では、オフラインユーザーとオフラインクライアントセッションのみがデータベースに保存されていました。新しい機能である persistent-user-sessions は、オンラインユーザーセッションとオンラインクライアントセッションをメモリーとデータベースの両方に保存します。その結果、Red Hat build of Keycloak のすべてのインスタンスが再起動またはアップグレードされた場合でも、ユーザーはログインしたままになります。

詳細は、永続的なユーザーセッション を参照してください。

この機能はデフォルトで有効化されています。無効にする場合は、分散キャッシュの設定 の章の 揮発性ユーザーセッション の手順を参照してください。

このリリースでは、base/login および keycloak.v2/login テーマのログインページにカスタムフッターを簡単に追加できる機能が導入されました。新しい footer.ftl テンプレートは、"ログインボックス" の下部に表示される content マクロを提供します。カスタムフッターを使用するには、カスタムログインテーマに必要なコンテンツを含む footer.ftl ファイルを作成します。

詳細は、ログインテーマへのカスタムフッターの追加 を参照してください。

Red Hat build of Keycloak 24 リリースでは、ユーザーが複数のブラウザータブで並行して認証する機能が改善されました。ただし、この機能の改善は認証セッションの有効期限が切れたときに対応していませんでした。このリリースでは、ユーザーがすでに 1 つのブラウザータブにログインしていて、別のブラウザータブで認証セッションの有効期限が切れた場合、Red Hat build of Keycloak では OIDC/SAML エラーによりクライアントアプリケーションにリダイレクトされます。その結果、クライアントアプリケーションはすぐに認証を再試行することができ、通常は SSO セッションによりアプリケーションに自動的にログインするはずです。

認証セッションの有効期限が切れ、ユーザーがすでにログインしている場合は You are already logged in というメッセージがエンドユーザーに表示されないことに注意してください。このエラーを処理するには、アプリケーションを更新することを検討してください。

詳細は、認証セッション を参照してください。

ユーザー属性でユーザーを検索する場合、Red Hat build of Keycloak は、強制的に小文字の比較がされるようにし、ユーザー属性名が検索されなくなりました。この変更の目的は、ユーザー属性テーブルで Red Hat build of Keycloak ネイティブインデックスを使用して検索を高速化することでした。データベースの照合で大文字と小文字が区別されない場合は、検索結果は同じままになります。データベースの照合で大文字と小文字が区別される場合、以前よりも検索結果が少なくなる可能性があります。

Red Hat build of Keycloak は、ユーザー名を含むユーザーパスワードを拒否できる新しいパスワードポリシーをサポートしています。

Admin Console では、特定のレルムの Required actions タブでいくつかのアクションを設定できるようになりました。現在、Update password は唯一、設定可能で、組み込まれている必須アクションです。Maximum Age of Authentication の設定をサポートしています。これは、ユーザーが再認証なしで kc_action パラメーター (Account Console でのパスワード更新などに使用) でパスワードを更新できる最大時間です。

必要なアクションの並べ替えも改善されました。認証中に複数のアクションが必要な場合、認証中に設定されたアクション (たとえば、kc_action パラメーターによって) であるか、管理者によってユーザーアカウントに手動で追加されたアクションであるかに関係なく、すべてのアクションが一緒にソートされます。

セキュアな SAML クライアントのデフォルトのクライアントプロファイルが追加されました。Admin Console でレルムのクライアントポリシーを参照すると、新しいクライアントプロファイル saml-security-profile が表示されます。これを使用する場合、SAML クライアントにセキュリティーのベストプラクティスが適用されます。たとえば、署名が強制され、SAML リダイレクトバインディングが無効になり、ワイルドカードリダイレクト URL が禁止されます。

クライアントスコープまたは完全なレルムが削除されると、関連付けられているユーザーの同意も削除される必要があります。パフォーマンスを向上させるために、テーブル USER_CONSENT_CLIENT_SCOPE に新しいインデックスが追加されました。

テーブルに 300,000 を超えるエントリーが含まれている場合、Red Hat build of Keycloak は自動スキーマ移行中にインデックスの作成をスキップし、代わりに SQL ステートメントをコンソールに記録することに注意してください。Red Hat build of Keycloak 起動後に、データベースでステートメントを手動で実行する必要があります。

認証情報の更新 (UPDATE_CREDENTIAL) および削除 (REMOVE_CREDENTIAL) 向けに、一般化されたイベントが存在するようになりました。認証情報の種類は、イベントの credential_type 属性に記述されます。新しいイベントタイプは、Email Event Listener によってサポートされます。

UPDATE_PASSWORD、UPDATE_PASSWORD_ERROR、UPDATE_TOTP、UPDATE_TOTP_ERROR、REMOVE_TOTP、REMOVE_TOTP_ERROR のイベントタイプは現在非推奨であり、今後のバージョンで削除される予定です。

メトリクスとヘルスチェックのエンドポイントは、標準の Red Hat build of Keycloak サーバーポート経由ではアクセスできなくなりました。これらのエンドポイントは外部には公開されるべきではないため、別のデフォルト管理ポート 9000 からアクセスできます。

別のポートを使用すると、Kubernetes 環境での Red Hat build of Keycloak のエンドポイントとして、ユーザーに公開されないようになります。新しい管理インターフェイスでは、設定可能な新しいオプションセットが提供されます。

Red Hat build of Keycloak Operator では、管理インターフェイスがデフォルトで有効になっていると想定されています。詳細は、管理インターフェイスの設定 を参照してください。

http_server_active_requests 1.0
http_server_requests_seconds_count{method="GET",outcome="SUCCESS",status="200",uri="/realms/{realm}/protocol/{protocol}/auth"} 1.0
http_server_requests_seconds_sum{method="GET",outcome="SUCCESS",status="200",uri="/realms/{realm}/protocol/{protocol}/auth"} 0.048717142

トークンイントロスペクションエンドポイントを呼び出す際に、HTTP Header Accept: application/jwt を使用できます。特定のクライアントに対して有効にすると、完全な JWT アクセストークンを含むトークンイントロスペクションエンドポイントからクレーム jwt が返されます。これは、イントロスペクションエンドポイントを呼び出すクライアントが軽量アクセストークンを使用した場合に特に便利です。

Passkeys 条件付き UI のサポートが追加されました。このプレビュー機能を有効にすると、専用のオーセンティケーターが利用可能になります。利用可能なパスキーアカウントのリストから選択し、それに基づいてユーザーを認証できます。

新しいオーセンティケーター Confirm override existing link が存在します。このオーセンティケーターを使用すると、以前は別の IDP アイデンティティーにリンクされていた Red Hat build of Keycloak ユーザーのリンクされた IDP ユーザー名を上書きできます。詳細は、既存のブローカーの上書きリンク を参照してください。

グループのスケーラビリティーを改善することを目的として、レルムを削除するときにグループがデータベースから直接削除されるようになりました。その結果、レルムを削除するときに、GroupRemovedEvent などのグループ関連のイベントは発生しなくなりました。

詳細は、グループ関連のイベント を参照してください。

このリリースでは、LDAP 接続プールの設定はシステムプロパティーのみに依存します。

詳細は、接続プールの設定 を参照してください。

Microsoft AD を使用しており、管理インターフェイスを通じてユーザーを作成している場合、ユーザーはデフォルトで有効な状態で作成されます。

以前のバージョンでは、ユーザーに (一時的ではない) パスワードを設定した後にのみ、ユーザーのステータスを更新できました。この動作は、他の組み込みユーザーストレージとも、LDAP プロバイダーによってサポートされている他の LDAP ベンダーとも一致していませんでした。

外部 Java キーストアファイルからレルムキーをロードできるようにする java-keystore キープロバイダーは、すべての Red Hat build of Keycloak アルゴリズムを管理するように変更されました。また、ストアから実際のキーを取得するために必要なキーストアとキーシークレットは、vault を使用して設定できます。したがって、Red Hat build of Keycloak レルムは、データベースに機密データを保存せずに、暗号化されたファイルの任意のキーを外部化できます。

このサブジェクトに関する詳細は、レルムキーの設定 を参照してください。

以前のバージョンでは、セッションがまだ有効かどうかを検証する場合のセッションの最大存続期間とアイドルタイムアウトの計算が若干異なっていました。このバージョンで、検証ではプロジェクトの他の部分と同じコードが使用されるようになりました。

セッションが Remember Me 機能を使用している場合、アイドルタイムアウトと最大有効期間は、共通の SSO の設定値と、Remember me の設定値のどちらか大きい方が適用されます。

ホスト名の設定は複雑なため、このリリースにはホスト名 v2 オプションが含まれています。元のホスト名オプションは削除されました。カスタムホスト名設定がある場合は、新しいオプションに移行する必要があります。これらのオプションの動作も変更されていることに注意してください。

詳細は、新しいホスト名オプション を参照してください。

ランタイムに cache、cache-stack、cache-config-file オプションを指定できるようになりました。この変更により、ビルドフェーズを実行し、これらのオプションを使用してイメージを再構築する必要がなくなります。

詳細は、ランタイムでのキャッシュオプションの指定 を参照してください。

Red Hat build of Keycloak 26 では、推奨される高可用性マルチサイトアーキテクチャーが大幅に改善されました。主な改善点は次のとおりです。

実装の詳細は、高可用性のマルチサイトデプロイメント を参照してください。

AccessToken、IDToken、および JsonWebToken から非推奨のメソッドが削除された結果、有効期限値に関連するメソッド名との一貫性を保つために SingleUseObjectKeyModel も変更されました。

詳細は、SingleUseObjectKeyModel を参照してください。

PostgreSQL 16 にサポート対象およびテスト済みのデータベースが追加される

マーシャリングは、Java オブジェクトをバイトに変換し、Red Hat build of Keycloak サーバー間でネットワーク経由で送信するプロセスです。Red Hat build of Keycloak 26 では、マーシャリング形式が JBoss Marshalling から Infinispan Protostream に変更されます。

Infinispan Protostream は、下位互換性と上位互換性の利点を持つ プロトコルバッファー (proto 3) に基づいています。

以前のリリースでは、すべての管理ユーザーがロックアウトされたときに、Red Hat build of Keycloak インスタンスへのアクセスを回復するプロセスは困難でした。ただし、Red Hat build of Keycloak では、一時的な管理者アカウントをブートストラップし、失われた管理者アクセスを回復するための新しい方法が提供されるようになりました。

これで、特定のオプションを指定して start または start-dev コマンドを実行し、一時的な管理者アカウントを作成できるようになりました。また、新しい専用コマンドが導入され、ユーザーは管理者アクセスをすぐに取得し直すことができます。

その結果、環境変数 KEYCLOAK_ADMIN および KEYCLOAK_ADMIN_PASSWORD は非推奨になりました。代わりに、KC_BOOTSTRAP_ADMIN_USERNAME および KC_BOOTSTRAP_ADMIN_PASSWORD を使用する必要があります。これらも一般的なオプションなので、--bootstrap-admin-username=admin のように CLI またはその他の設定ソース経由で指定できます。

詳細は、一時管理者アカウント を参照してください。

OpenTelemetry Tracing の基礎となる Quarkus サポートが Red Hat build of Keycloak に公開され、アプリケーショントレースを取得して監視性を向上させることができます。この機能には、パフォーマンスのボトルネックを特定し、アプリケーション障害の原因を特定し、分散システムを通じて要求をトレースする機能が含まれます。

詳細は、トレースの有効化 を参照してください。

DPoP (OAuth 2.0 Demonstrating Proof-of-Possession) プレビュー機能が改善されました。DPoP は現在、すべての付与タイプでサポートされています。以前のリリースでは、この機能は authorization_code 付与タイプに対してのみサポートされていました。UserInfo エンドポイントでは DPoP トークンタイプもサポートされています。

現在、Red Hat build of Keycloak では、クライアントの暗号鍵管理アルゴリズムとして ECDH-ES、ECDH-ES+A128KW、ECDH-ES+A192KW、または ECDH-ES+A256KW を設定できます。Elliptic Curve Diffie-Hellman Ephemeral Static (ECDH-ES) 仕様による鍵合意では、JWT に epk、apu、apv という 3 つの新しいヘッダーパラメーターが導入されています。現在、Red Hat build of Keycloak 実装は、必須の epk のみを管理し、他の 2 つ (オプション) はヘッダーに追加されません。これらのアルゴリズムの詳細は JSON Web Algorithms (JWA) を参照してください。

また、レルムキーを生成するための新しいキープロバイダー ecdh-generated が利用可能になり、Java KeyStore プロバイダーに ECDH アルゴリズムのサポートが追加されました。

このリリースでは、埋め込みキャッシュを使用する場合、取り消されたアクセストークンはデータベースに書き込まれ、クラスターが再起動されたときにデフォルトで再ロードされます。

詳細は、削除されたアクセストークンの保持 を参照してください。

client-attribute に基づく条件がクライアントポリシーに追加されました。この条件を使用して、特定のクライアント属性に特定の値を持つクライアントを指定できます。クライアントポリシーのドキュメントに記載されているように、この条件を評価するときは AND 条件または OR 条件のいずれかを使用します。

現在、Red Hat build of Keycloak では、クライアントの暗号鍵管理アルゴリズムとして ECDH-ES、ECDH-ES+A128KW、ECDH-ES+A192KW、または ECDH-ES+A256KW を設定できます。Elliptic Curve Diffie-Hellman Ephemeral Static (ECDH-ES) 仕様による鍵合意では、JWT に epk、apu、apv という 3 つの新しいヘッダーパラメーターが導入されています。現在、Red Hat build of Keycloak 実装では必須の epk のみが管理され、他の 2 つ (オプション) はヘッダーに追加されません。これらのアルゴリズムの詳細は、JSON Web Algorithms (JWA) を参照してください。

また、レルムキーを生成するための新しいキープロバイダー ecdh-generated が利用可能になり、Java KeyStore プロバイダーに ECDH アルゴリズムのサポートが追加されました。

proxy-trusted-addresses は proxy-headers オプションが設定されていて、信頼できるプロキシーアドレスの許可リストを指定する場合に使用できます。特定のリクエストのプロキシーアドレスが信頼されていない場合、それぞれのプロキシーヘッダー値は使用されません。詳細は、信頼できるプロキシー を参照してください。

proxy-protocol-enabled オプションは、プロキシーの背後からの要求を処理するときにサーバーが HA PROXY プロトコルを使用するかどうかを制御します。true に設定すると、返されるリモートアドレスは実際の接続クライアントからのアドレスになります。詳細は、プロキシープロトコル を参照してください。

https-certificates-reload-period オプションを設定すると、https-* オプションによって参照されるキーストア、トラストストア、および証明書ファイルの再読み込み期間を定義できます。再読み込みを無効にするには -1 を使用します。デフォルトは 1h (1 時間) です。詳細は、証明書とキーの再読み込み を参照してください。

--cache-embedded-${CACHE_NAME}-max-count= を設定すると、指定されたキャッシュ内のキャッシュエントリーの数の上限を定義できます。

コミュニティーからのフィードバックに基づいて、信頼できる証明書の粒度を向上させるために、https-trust-store-* オプションを非推奨にしないことを決定しました。