リリースノート

Verify Existing Account By Email という実行は、First Login Flow がブローカー経由のアカウントを既存の Red Hat build of Keycloak ユーザーにリンクさせるために提供する、選択肢の 1 つです。このステップは、ユーザーが初めてブローカー経由で Red Hat build of Keycloak にログインし、かつそのアイデンティティープロバイダーのアカウントが Red Hat build of Keycloak 内にすでに存在する場合に実行されます。この実行では、ユーザーがそのアカウントを管理していることを確認するため、Red Hat build of Keycloak の現在のアドレスにメールが送信されます。

このリリース以降、外部アイデンティティープロバイダーによって送信されたリンク属性 (メールとユーザー名) がレビュープロセス中にユーザーによって変更されていない場合にのみ、First Login Flow で Verify Existing Account By Email という実行が試行されます。この新しい動作により、誤ってリンクを受け入れる可能性のある既存の Red Hat build of Keycloak アカウントに検証メールが送信されることが回避されます。

プロバイダーがアイデンティティープロバイダーから送信された情報を変更する必要がある場合 (ブローカー内のメールまたはユーザー名が異なるため)、新しいアカウントを既存の Red Hat build of Keycloak ユーザーにリンクするには、他の選択肢である Verify Existing Account By Re-authentication のみを使用できます。

アイデンティティープロバイダーから受信したデータが必須であり、変更できない場合は、ユーザーの介入を防ぐために First Login Flow の Review Profile ステップを無効にすることができます。

詳細は、サーバー 管理ガイド の 最初のログインフロー セクションを参照してください。

クライアントが 署名済み JWT または クライアントシークレット付きの署名済み JWT タイプを使用して認証するように設定されている場合、Red Hat build of Keycloak はトークンの最大有効期限を強制するようになりました。その結果、トークンの exp (有効期限) クレームがかなり後になる可能性があるにもかかわらず、Red Hat build of Keycloak はその最大有効期限前に発行されたトークンを受け入れません。デフォルト値は、60 秒です。

JWT トークンは認証のために送信される直前に発行される必要があることに注意してください。これにより、ログイン用のトークンを送信するための 1 分間の時間がクライアントに与えられます。この有効期限は、クライアントの Credentials タブにある Max expiration 設定オプションを使用して調整できます。詳細は、機密クライアント認証情報 を参照してください。

以前のリリースでは、同じ認証セッション (同じブラウザー) が使用された場合、認証情報リセットフロー (forgot password 機能) により、認証情報のリセット後もユーザーはログインしたままになりました。フェデレーションユーザープロバイダーの場合、この動作はセキュリティー上の問題になる可能性があります。ユーザーを 有効である と検出し、パスワードの変更は正常に実行されるが、ユーザーパスワードの検証が何らかの理由で失敗するプロバイダー実装を想像してください。このシナリオでは、通常のブラウザフローではログインが許可されないはずのユーザーが、認証情報リセットフローによってパスワードを正常に変更した後、ログインできていました。このシナリオはまれなケースですが、デフォルトで回避する必要があります。

現在のリリースでは、オーセンティケーター reset-credential-email (Send Reset Email) に、force-login (リセット後のログインの強制) という新しい設定オプションが追加され、次の 3 つの値を指定できます。

このオプションの変更の詳細は、forgot password の有効化 を参照してください。

よりセキュアなサーバーランタイムを優先し、システム変数が誤って公開されることを回避するために、サーバーの起動時に spi-admin-allowed-system-variables 設定オプションを使用して、公開するシステム変数を指定することが必須になりました。

今後のリリースでは、レルム設定でのシステム変数の使用を防止するために、この機能は削除されます。

このリリースでは、コンテナーイメージは OpenJDK 21 を使用し、OpenJDK 17 よりもパフォーマンスが向上しました。

Organizations および OrganizationMembers API の getAll() メソッドは非推奨となり、次のメジャーリリースで削除される予定です。代わりに、Organizations および OrganizationMembers API の対応する list(first, max) メソッドを使用します。

リバースプロキシーを使用する場合、X.509 クライアント証明書の検索で潜在的に脆弱な設定が特定されました。プロキシーヘッダーによるクライアント証明書の検索を設定している場合は、追加の設定手順が必要になることがあります。詳細は、クライアント証明書の検索を有効にする を参照してください。

このリリースでは、管理イベントには、イベントが発生したときのコンテキストに関する追加の詳細が保持される可能性があります。アップグレード後、データベーススキーマの ADMIN_EVENT_ENTITY テーブルに新しい列 DETAILS_JSON があることがわかります。

Red Hat build of Keycloak では REALM_FILESEPARATOR_KEY キーリゾルバーを使用しますが、レルム外の FileVault シークレットへのアクセスが制限されるようになりました。管理コンソールで式プレースホルダーを指定するときにパストラバーサルを引き起こす可能性のある文字は禁止されます。

さらに、KEY_ONLY キーリゾルバーは、REALM_UNDERSCORE_KEY リゾルバーが使用されている場合に別のレルムにリンクされる可能性のあるシークレットの読み取りを回避するために、_ 文字をエスケープします。この場合のエスケープとは、_ を __ に置き換えるだけです。たとえば、${vault.my_secret} は my__secret という名前のファイルを検索します。これは互換性を損なう可能性のある変更であるため、移行を容易にするために警告が記録されます。

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_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-* オプションを非推奨にしないことを決定しました。

org.keycloak.common.util.Resteasy が非推奨になりました。代わりに org.keycloak.util.KeycloakSessionUtil を使用して KeycloakSession を取得する必要があります。

カスタムプロバイダーを作成するとき以外は、KeycloakSession を取得しないようにすることを強く推奨します。

UserRepresentation の origin プロパティーは非推奨であり、今後のリリースで削除される予定です。

代わりに、federationLink プロパティーを使用して、ユーザーがリンクされているプロバイダーを取得することを推奨します。

以下の項目は、今後の Red Hat build of Keycloak バージョンで削除される予定であり、後継はありません。

UserSessionCrossDCManager クラスは非推奨であり、Red Hat build of Keycloak の今後のバージョンで削除される予定です。代わりに使用するメソッドは、UserSessionCrossDCManager Javadoc を参照してください。

ユーザーの認証情報を削除するためのアカウント REST エンドポイントは非推奨です。このバージョン以降、Account Console はこのエンドポイントを使用しなくなりました。これは、アプリケーションが開始する Delete Credential に置き換えられます。

keycloak ログインテーマは、新しい keycloak.v2 に置き換えられて非推奨となり、今後のバージョンでは削除される予定です。互換性の理由から新しいレルムのデフォルトのままですが、すべてのレルムテーマを keycloak.v2 に切り替えることが強く推奨されます。

org.keycloak.credential.hash.PasswordHashProvider インターフェイスの String encode(String rawPassword, int iterations) メソッドが非推奨になりました。このメソッドは、今後の Red Hat build of Keycloak リリースの 1 つで削除される予定です。

次の変数は Admin テーマでは非推奨となり、今後のバージョンでは削除される予定です。

次の変数は Account テーマでは非推奨となり、今後のバージョンでは削除される予定です。

org.keycloak.models.AuthenticatedClientSessionModel インターフェイスのメソッド String getCurrentRefreshToken()、void setCurrentRefreshToken (String currentRefreshToken)、int getCurrentRefreshTokenUseCount()、および void setCurrentRefreshTokenUseCount (int currentRefreshTokenUseCount) は非推奨です。これらは、クライアントセッション内で複数のリフレッシュトークンを管理するために getRefreshToken (String reuseId) などのパラメーターとして識別子を必要とする同様のメソッドに置き換えられました。このメソッドは、今後の Red Hat build of Keycloak リリースで削除される予定です。

Keycloak JS ライブラリーの UMD ディストリビューションの ユニバーサルモジュール定義 が削除されました。つまり、ライブラリーはグローバル変数として公開されなくなり、代わりに モジュール としてインポートする必要があります。この変更は、最新の JavaScript 開発手法に沿ったものであり、ブラウザーとビルドツール間のエクスペリエンスの一貫性が向上し、一般的に副次的な影響が少なく予測可能なコードになります。

Vite や Webpack などのバンドラーを使用している場合は何も変更されず、以前と同じ使用感が得られます。ブラウザーでライブラリーを直接使用している場合は、コードを更新してライブラリーをモジュールとしてインポートする必要があります。

<!-- Before -->
<script src="/path/to/keycloak.js"></script>
<script>
    const keycloak = new Keycloak();
</script>

<!-- After -->
<script type="module">
    import Keycloak from '/path/to/keycloak.js';
    const keycloak = new Keycloak();
</script>

<!-- Before -->
<script src="/path/to/keycloak.js"></script>
<script>
    const keycloak = new Keycloak();
</script>

<!-- After -->
<script type="module">
    import Keycloak from '/path/to/keycloak.js';
    const keycloak = new Keycloak();
</script>

ライブラリーのインポートを簡潔にするために、インポートマップ を使用することもできます。

<script type="importmap">
    {
        "imports": {
            "keycloak-js": "/path/to/keycloak.js"
        }
    }
</script>
<script type="module">
    // The library can now be imported without specifying the full path, providing a similar experience as with a bundler.
    import Keycloak from 'keycloak-js';
    const keycloak = new Keycloak();
</script>

<script type="importmap">
    {
        "imports": {
            "keycloak-js": "/path/to/keycloak.js"
        }
    }
</script>
<script type="module">
    // The library can now be imported without specifying the full path, providing a similar experience as with a bundler.
    import Keycloak from 'keycloak-js';
    const keycloak = new Keycloak();
</script>

TypeScript を使用している場合は、ライブラリーを解決できるように tsconfig.json を更新する必要がある場合があります。

{
    "compilerOptions": {
        "moduleResolution": "Bundler"
    }
}

{
    "compilerOptions": {
        "moduleResolution": "Bundler"
    }
}

org.keycloak.common.util.CollectionUtil.intersection メソッドが削除されました。既存のコレクションでは代わりに 'java.util.Collection.retainAll' を使用する必要があります。

Account Console v2 テーマは、Red Hat build of Keycloak から削除されました。このテーマは Red Hat build of Keycloak 24 で非推奨となり、Account Console v3 テーマに置き換えられました。このテーマをまだ使用している場合は、Account Console v3 テーマに移行する必要があります。

これらのオプションは、Hostname v2 と呼ばれる新しいオプションに置き換えられました。詳細は、ホスト名の設定 (v2) および 新しいホスト名のオプション を参照してください。

proxy オプションは Red Hat build of Keycloak 24 では非推奨となり、必要に応じてホスト名オプションと組み合わせた proxy-headers オプションに置き換えられました。詳細は、リバースプロキシーの使用 を参照してください。

ほとんどの Java アダプターは、Red Hat build of Keycloak コードベースとダウンロードページから削除されました。

OSGi メタデータを使用していたすべての Java アダプターが削除されたため、jar に対して OSGi メタデータは生成されなくなりました。

Red Hat build of Keycloak では、_LEGACY Cookie が送信されなくなりました。この Cookie は、Cookie の SameSite フラグをサポートしていない古いブラウザーへの回避策として導入されました。

_LEGACY Cookie は、安全でないコンテキストからのログインを許可する別の目的でも使用できます。Red Hat build of Keycloak の実稼働環境では安全でないコンテキストは決して推奨されませんが、localhost の外部から http 経由で Red Hat build of Keycloak にアクセスすることは比較的頻繁に行われます。_LEGACY Cookie の代わりとして、Red Hat build of Keycloak では secure フラグが設定されなくなりました。ただし、安全でないコンテキストが使用されていることを検出すると、SameSite=None ではなく SameSite=Lax が設定されます。

EnvironmentDependentProviderFactory.isSupported() メソッドは、ふくすのリリースで非推奨となり、現在は削除されています。

代わりに、isSupported (Config.Scope config) を実装します。

以前のバージョンの Red Hat build of Keycloak は、http(s)://example-host/auth/realms/my-realm-name/protocol/openid-connect/logout?redirect_uri=encodedRedirectUri などのログアウトエンドポイント URL を開いて、ユーザーの自動ログアウトおよびアプリケーションへのリダイレクトをサポートしていました。この機能は Red Hat build of Keycloak 18 で非推奨となり、OpenID Connect 仕様への準拠が優先され、このバージョンでは削除されました。

この変更の一環として、SPI の関連する次の設定オプションが削除されました。

ログアウトにこれらのオプションまたは redirect_uri パラメーターをまだ使用している場合は、代わりに OpenID Connect RP-Initiated Logout 仕様 を実装する必要があります。

org.keycloak:keycloak-model-legacy モジュールは以前のリリースで非推奨となり、このリリースでは削除されました。代わりに org.keycloak:keycloak-model-storage モジュールを使用してください。

起動時にオフラインセッションをプリロードする古い動作は、以前のリリースで非推奨になった後に削除されました。

groups.setOrCreateChild() メソッドは、JavaScript ベースの管理クライアントから削除されました。まだこのメソッドを使用している場合は、代わりに createChildGroup() または updateChildGroup() メソッドを使用してください。

sid クレームと同じ値を含む session_state クレームは、OpenID Connect Front-Channel Logout および OpenID Connect Back-Channel Logout の仕様に準拠するようになり、不要になったため、すべてのトークンから削除されました。session_state クレームは、OpenID Connect Session Management 仕様に従って、Access Token Response 内に残ります。

なお、setSessionState() メソッドも IDToken クラスから削除され、代わりに setSessionId() メソッドが導入され、getSessionState() メソッドは非推奨になりました。

新しい セッション状態 (session_state) マッパーも含まれており、クライアントスコープ (たとえば、basic クライアントスコープ) に割り当てて、古い動作に戻すことができます。

古いバージョンの JS アダプターを使用する場合は、上記のようにクライアントスコープを使用して セッション状態 (session_state) マッパーも使用する必要があります。

以前のバージョンの Red Hat build of Keycloak では、ユーザーおよびクライアントセッションのアイドル時間に 2 分間の猶予期間が追加されました。以前のアーキテクチャーで、セッションの更新時間がクラスターで非同期に複製されていたため、この猶予期間が追加されました。永続的なユーザーセッションでは、これは不要になり、猶予期間が削除されました。

以前の動作を維持するには、レルム設定を更新し、セッションとクライアントのアイドル時間を 2 分延長します。

org.keycloak.bom:keycloak-adapter-bom および org.keycloak.bom:keycloak-misc-bom BOM ファイルは削除されます。ほとんどの Java アダプターが削除されたため、アダプター BOM は役に立たなくなりました。misc BOM には、keycloak-test-helper というアーティファクトが 1 つだけ含まれていましたが、このリリースではそのアーティファクトも削除されます。

このリリースでは、maven アーティファクト org.keycloak:keycloak-test-helper が削除されました。このアーティファクトは、Java 管理クライアントを処理するためのヘルパーメソッドをいくつか提供しました。ヘルパーメソッドを使用する場合は、必要に応じてそれらをアプリケーションにフォークすることが可能です。

このリリースでは JEE admin-client は削除されていますが、Jakarta admin-client は引き続きサポートされます。

以下のメソッドが AccessToken クラスから削除されました。

以下のメソッドは IDToken クラスから削除されました。

以下のメソッドは JsonWebToken クラスから削除されました。

また、exp と nbf のクレームはオプションであるため、トークンに設定されないことも想定する必要があります。以前は、これらのクレームの値は有効な NumericDate である必要があるため、0 の値に設定されていましたが、これはまったく意味がありません。

カスタム Cookie を設定するための次の API は削除されました。

バージョン 22.0 では、LinkedIn の OAuh 2.0 ソーシャルプロバイダーが新しい OpenId Connect 実装に置き換えられました。レガシープロバイダーは非推奨になりましたが、既存のレルムでまだ機能している場合に備えて削除されませんでした。Red Hat build of Keycloak 26 では、古いプロバイダーとそれに関連する linkedin-oauth 機能が削除されます。今後は、デフォルトの LinkedIn ソーシャルプロバイダーのみが利用可能なオプションです。