2023年7月11日
リリースをダウンロードするには、Keycloak ダウンロード にアクセスしてください。
Keycloak サーバーを Java 11 で実行することはサポートされなくなりました。Java 11 は Keycloak 21 で非推奨となり、Keycloak 22 で削除される計画が発表されていました。
Keycloak は Quarkus Java フレームワークのバージョン 3.2.0.Final にアップグレードしました。Quarkus 3.x は、最新技術を迅速に取り入れ、最先端のユーザーエクスペリエンスを提供することで、Java 開発を推進するという伝統を継承しています。
Quarkus 3.x へのアップグレードの一環として、Keycloak はコードベースを Java EE (Enterprise Edition) から後継の Jakarta EE に移行しました。これにより、Keycloak にさまざまな変更がもたらされます。Jakarta EE 10 をサポートするために、すべての Jakarta EE 仕様をアップグレードしました。
より優れたランタイムを提供し、基盤となるスタックを最大限に活用するために、javax.ws.rs.core.Context アノテーションを使用したコンテキストデータのすべてのインジェクションポイントが削除されました。期待されるパフォーマンスの向上には、リクエストライフサイクル中にプロキシインスタンスを複数回作成しないこと、およびランタイム時のリフレクションコードの量を大幅に削減することが含まれます。
Keycloak は Hibernate ORM 6.2 へのアップグレードの恩恵を受けるようになりました。これには、パフォーマンスの向上、より優れた SQL、最新の JDK サポート、および最新の RDBMS 機能のサポートが含まれます。
以前の、そして現在削除された WildFly ディストリビューションは、キーストアにバックアップされた Elytron クレデンシャルストアからシークレットを読み取る組み込みの Vault プロバイダーを提供していました。これが利用できなくなったため、Keycloak Vault SPI の新しい実装である Keycloak KeyStore Vault を追加しました。名前が示すように、この実装は Java キーストアファイルからシークレットを読み取ります。このようなシークレットは、管理コンソールの複数の場所で使用できます。詳細については、ガイド と最新の ドキュメント を参照してください。
KeyStore Vault のニュースに関連して、Quarkus が最近リリースした KeyStore Config Source という機能も統合しました。これは、既存の設定ソース（CLI パラメーター、環境変数、ファイル）に加えて、Java キーストアファイルに保存された設定プロパティを介して Keycloak サーバーを設定できるようになったことを意味します。この機能の詳細については、設定ガイド を参照してください。
多くのユーザーがサーバーのホスト名の正しい設定に問題を抱えていたため、設定をデバッグするための新しいヘルパーツールが追加されました。
モード passthrough で Keycloak の --proxy 設定を使用するインストール環境は、このモードの動作が変更されたため、ドキュメントを確認する必要があります。
以前のリリースでは、export および import コマンドは、最初に build コマンドを実行する必要がありました。このリリース以降、export および import コマンドは、ビルド時の設定が変更された場合、Keycloak の自動リビルドを実行します。
古いアカウントコンソール (v1) は完全に削除されました。このバージョンのアカウントコンソールは、Keycloak 12 で非推奨とされていました。
Keycloak のバージョン 21.1.0 で、新しいアカウントコンソール (バージョン 3) が実験的な機能として導入されました。このバージョンから、プレビュー機能に昇格しました。
アカウントコンソール V2 および V3 テンプレートに公開されていた 2 つの変数 (isEventsEnabled および isTotpConfigured) は未使用のまま残されており、このリリースで削除されました。
開発者がアカウントコンソールのテーマを拡張した場合、これらの変数を使用している可能性があります。基本テーマを拡張する場合は、これらの変数が使用されていないことを確認してください。
管理コンソール（および間もなく新しいアカウントコンソールも）は、国際化されたメッセージのキーがどのように解析されるかに関して、Keycloak の他の部分とはわずかに異なる動作をします。これは、国際化に i18next ライブラリを使用しているためです。したがって、「レルム設定」➡「ローカライゼーション」の下で管理コンソール用のカスタムメッセージを定義する場合は、i18next のベストプラクティスを考慮に入れる必要があります。具体的には、管理コンソール用のメッセージを定義する際には、メッセージのキーに 名前空間 を指定することが重要です。
たとえば、新しいレルムが作成されたときにユーザーに表示される welcome メッセージを上書きしたいとしましょう。このメッセージは、メッセージを保持する元のファイルの名前 (dashboard.json) と同じ dashboard 名前空間にあります。このメッセージを上書きしたい場合は、名前空間をプレフィックスとして使用し、その後にコロンで区切られたメッセージのキーを使用する必要があります。この場合、dashboard:welcome になります。
このリリースで、Keycloak JS アダプターからレガシー Promise API メソッドを削除しました。これは、アダプターから返された Promise で .success() および .error() を呼び出すことができなくなったことを意味します。
new 演算子でインスタンス化する必要がある以前のリリースでは、Keycloak JS アダプターが new 演算子なしで構築された場合に、非推奨警告を積極的にログに記録し始めました。このリリース以降、そうすると代わりに例外がスローされます。これは、JavaScript クラス の期待される動作に合わせるためであり、これにより、将来のアダプターのリファクタリングが容易になります。
Jakarta EE へのアップグレード後、Keycloak Admin クライアントのアーティファクトは、長期的な保守性を考慮して、より説明的な名前に変更されました。Jakarta EE をサポートするものと Java EE をサポートするものの、2 つの個別の Keycloak Admin クライアントを依然として提供しています。
User API は、カスタム属性に基づいたユーザー数のクエリをサポートするようになりました。そのため、新しい q パラメーターが /{realm}/users/count エンドポイントに追加されました。
q パラメーターは、次の形式 q=<name>:<value> <name>:<value> を想定しています。ここで、<name> と <value> は、それぞれ属性名と値を表します。
keycloak がスケーラブルなリソースになるのを容易にするために、keycloak.status に追加のフィールドが追加されました。また、status をより解釈しやすくするための追加フィールド（observedGeneration、condition observedGeneration、lastTransitionTime フィールドなど）もあります。
condition status フィールドは、標準の Kubernetes conditions に準拠するために、boolean から string に変更されました。CRD では、一時的に任意の内容を受け入れるように表現されますが、常に string になります。このフィールドの使用箇所を、true または false ではなく、値 "True"、"False"、または "Unknown" を想定するように更新してください。
高度な管理が必要なシナリオでは、オペレーターによって直接設定されていないオペレーター管理リソースのほとんどのフィールドを直接更新できるようになりました。これは、Keycloak 仕様のサポートされていないスタンザの代替として使用できます。サポートされていないスタンザと同様に、これらの直接的な変更はサポート対象とは見なされません。変更によってオペレーターがリソースを管理できなくなった場合、Keycloak CR にこのエラー状態が表示され、オペレーターがログに記録します。
OpenID Connect ID プロバイダーは、ID プロバイダーによって発行された ID トークンに特定のクレームが含まれている必要があることを指定する新しい構成をサポートしています。そうでない場合、ユーザーはこのブローカーを介して認証できません。
このオプションはデフォルトで無効になっています。有効にすると、フィルター処理する JWT トークンクレームの名前と、一致させる値を指定できます (正規表現形式をサポート)。
OpenID Connect プロバイダーは、ID トークンと UserInfo レスポンスに対して Json Web Encryption (JWE) をサポートするようになりました。プロバイダーは、選択された暗号化アルゴリズムに対して定義されたレルムキーを使用して復号化を実行します。
新しいハードコードされたグループマッパーを使用すると、ID プロバイダーから連携されたユーザーに特定のグループを追加できます。
新しいユーザーセッションノートマッパーを使用すると、クレームをユーザーセッションノートにマッピングできます。
トラストストア SPI Only for ldaps を使用する LDAP オプションが削除されました。このパラメーターは、TLS で保護された LDAP 接続のトラストストアを選択するために使用されます。内部 Keycloak トラストストアが選択される (Always) か、グローバル JVM トラストストアが選択される (Never) かのいずれかです。
Only for ldaps が使用されていたデプロイメントは、TLS で保護された LDAP 接続に対して Always オプションが選択された場合と同様に自動的に動作します。
OpenShift 3.x の内部 IdP を Keycloak に置き換えることを可能にした openshift-integration プレビュー機能は、Keycloak コードベースから個別の拡張プロジェクトに移動されました。
アップグレードする前に、変更点の完全なリストについては、移行ガイド を参照してください。