リリースノート

このリリースで、新しいバージョンの Fine-Grained Admin Permissions がサポートされるようになりました。バージョン 2 (V2) では、レルム内の管理アクセスに対する柔軟性と制御が強化されています。この機能を使用すると、管理者は広範な管理ロールに依存せずに、ユーザー、グループ、クライアント、およびロールを管理するための権限を定義できます。V2 は、以前のバージョンと同じレベルのレルムリソースへのアクセス制御を提供し、今後のバージョンでその機能を拡張する予定です。重要なポイントは次のとおりです。

詳細は、Fine-Grained Admin Permissions を参照してください。移行の詳細は、アップグレードガイド を参照してください。

このリリースでは、標準トークン交換の基本サポートが導入されています。この機能は現在 Token exchange specification に準拠した内部トークン間の交換に限定されています。アイデンティティーブローカーまたは主体の偽装に関連するその他のユースケースに対応する計画が進められています。

詳細は、標準トークン交換 を参照してください。

以前の Red Hat build of Keycloak バージョンで使用されていた従来のトークン交換からアップグレードする方法については、アップグレードガイド を参照してください。

OpenID Connect Core Specification の最新バージョンでは、クライアント認証方法 private_key_jwt および client_secret_jwt の JWT クライアントアサーションにおけるオーディエンス検証のルールが厳格化されました。Red Hat build of Keycloak では、デフォルトで、クライアント認証に使用される JWT トークンに単一のオーディエンスが存在することが強制されるようになりました。

JWT クライアント認証 Red Hat build of Keycloak バージョンで変更されたオーディエンス検証の詳細は、アップグレードガイド を参照してください。

これらの更新は、Operator ガイドで取り上げられているトピックに関連しています。

これらの更新は、このリリースの新しいガイドである 可観測性ガイド で取り上げられているトピックに関連しています。

Red Hat build of Keycloak は、データベースを使用して同じクラスターの他のノードを検出するようになったため、特にクラウドプロバイダーの場合、追加のネットワーク関連の設定が不要になります。これは、デフォルト設定で、クラウド環境でも変更せずに動作します。以前の Red Hat build of Keycloak バージョンでは、クラスターを形成する他のノードを検出し、Red Hat build of Keycloak の複製されたキャッシュを同期するために、デフォルトで UDP マルチキャストが使用されていました。これにはマルチキャストが利用可能であり、正しく設定されている必要がありましたが、これはクラウド環境では通常当てはまりません。

このバージョンから、デフォルトは jdbc-ping 設定に変更され、この設定では他のノードを検出するために Red Hat build of Keycloak データベースが使用されます。この変更により、マルチキャストネットワーク機能と UDP が不要になり、TCP ベースの障害検出に動的ポートが使用されなくなります。この簡素化は、以前のデフォルトを使用していた環境の後継となります。以前の動作を有効にするには、現在非推奨となっているトランスポートスタック udp を選択します。

Red Hat build of Keycloak Operator は、引き続き kubernetes をトランスポートスタックとして設定します。

詳細は、分散キャッシュの設定 を参照してください。

このリリースから、Red Hat build of Keycloak は、少なくとも 2 つの CPU コアが利用可能な環境で OpenJDK 21 を実行するときに、組み込み Infinispan と JGroups の両方で仮想スレッドプールのサポートを自動的に有効にします。この変更により、JGroups スレッドプールを設定する必要がなくなり、JGroups スレッドプールを HTTP ワーカースレッドプールに合わせる必要がなくなります。また、全体的なメモリーフットプリントも削減されます。

以前のリリースでは --cache-config-file オプションが指定されていない場合、conf/cache-ispn.xml への変更はすべて無視されていました。

このリリースから、--cache-config-file が設定されていない場合、デフォルトの Infinispan XML 設定ファイルは conf/cache-ispn.xml になります。これは、現行および過去のリリースのドキュメントから見ても、想定される動作および暗黙的な動作であるためです。

カテゴリー固有のログレベルを個別の log-level-category オプションとして設定できるようになりました。

詳細は、レベルを個別のオプションとして設定する を参照してください。

利用可能なすべてのログハンドラーは、ECS (Elastic Common Schema) JSON 形式をサポートするようになりました。これは、Red Hat build of Keycloak の可観測性ストーリーと集中ログの改善に役立ちます。

詳細は、ロギング を参照してください。

オプション 最小 ACR 値 が、レルム OIDC クライアントの設定オプションとして追加されます。この追加はステップアップ認証に関連する機能拡張であり、特定のクライアントにログインするときに最小 ACR レベルを有効にできます。

Initiating user registration standard のサポートが追加されました。これにより、OIDC クライアントは prompt=create パラメーターを使用してログイン要求を開始できるようになり、既存のユーザーを認証するのではなく、新しいユーザーを登録する必要があることを Red Hat build of Keycloak に通知できます。ユーザー登録の開始は、専用のエンドポイント /realms/<realm>/protocol/openid-connect/registrations を使用した Red Hat build of Keycloak ですでにサポートされていました。ただし、このエンドポイントは Red Hat build of Keycloak に固有のプロプライエタリーソリューションであるため、標準の方法が推奨されています。

EC-DSA および Ed-DSA 鍵プロバイダーには、新しいオプション Generate certificate が追加されました。レルム管理者によって生成鍵が作成されると、この鍵に対して証明書が生成される場合があります。証明書情報は、管理コンソールと、この鍵の JWK 式で確認できます。この JWK は、レルム鍵が含まれる JWKS エンドポイントから入手できます。

Pushed Authorization Requests を含む DPoP のサポートなどの Authorization Code Binding to a DPoP Key のサポートが追加されました。

OIDC 認証リクエストは、最大長のカスタムパラメーターを追加で少数サポートします。追加のパラメーターは、カスタム目的 (たとえば、プロトコルマッパーを使用してトークンにクレームを追加するなど) に使用できます。以前のバージョンでは、パラメーターの最大数は 5 にハードコードされ、パラメーターの最大長は 2000 にハードコードされていました。これで、両方の値が設定可能になりました。さらに、追加のパラメーターにより、リクエストが失敗するか、パラメーターが無視されるかを設定することもできます。

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

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

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

詳細は、管理インターフェイスの設定 を参照してください。

複数のノードをクラスター化するために、Red Hat build of Keycloak は分散キャッシュを使用します。このリリース以降、すべての TCP ベースのトランスポートスタックでは、ノード間の通信は TLS で暗号化され、自動生成された一時キーと証明書で保護されます。

これにより、セキュアバイデフォルト (secure-by-default) の設定を強化し、新規セットアップの設定ステップを最小限に抑えます。

TCP ベースのトランスポートスタックを使用していない場合は、簡素化された設定と強化されたセキュリティーのメリットを享受するために、jdbc-ping トランスポートスタックに移行することを推奨します。

以前のリリースで TCP トランスポートスタック通信を保護するために独自のキーストアとトラストストアを指定していた場合は、設定の簡素化を最大限に活かせるように、自動生成される一時キーと証明書に移行することを推奨します。

カスタムトランスポートスタックを使用している場合は、cache-embedded-mtls-enabled オプションを false に設定することで、このデフォルトの動作を無効にできます。

詳細は、トランスポートスタックのセキュリティー保護 を参照してください。

X.509 オーセンティケーターで証明書を検証するために使用される証明書失効リスト (CRL) は、crl と呼ばれる新しい Infinispan キャッシュ内にキャッシュされるようになりました。キャッシュにより、ソースごとに 1 つの CRL のみが維持されるため、検証パフォーマンスが向上し、メモリー消費量が削減されます。

新しいキャッシュプロバイダーのオプションを確認するには、すべてのプロバイダー設定 の章の crl-storage セクションを確認してください。

Condition - sub-flow executed および Condition - client scope は、Red Hat build of Keycloak における新しい条件付きオーセンティケーターです。Condition - sub-flow executed の条件は、認証フロー実行中に前のサブフローが正常に実行されたかどうか (または実行されなかったかどうか) を確認します。Condition - client scope の条件は、設定されたクライアントスコープが、認証を要求するクライアントのクライアントスコープとして存在するかどうかを確認します。詳細は、条件フローの条件 を参照してください。

Red Hat build of Keycloak の拡張機能を開発する場合、開発者は ProviderFactory インターフェイスに dependsOn() メソッドを実装することで、プロバイダーファクトリークラス間の依存関係を指定できるようになりました。詳細な説明については、Javadoc を参照してください。

すべての Keycloak テーマでダークモードのサポートが有効になりました。この機能は以前は管理コンソール、アカウントコンソール、ログインページにありましたが、現在はウェルカムページでも利用できます。ユーザーがオペレーティングシステムの設定 (ライトモードやダークモードなど) またはユーザーエージェントの設定でオプションを指定した場合は、テーマは自動的にそのオプションを使用します。

Keycloak テーマを拡張したカスタムテーマを使用しており、ダークモードをサポートする準備ができていない場合、またはスタイルの競合によりダークモードを実装できない場合は、次のプロパティーをテーマに追加してサポートを無効にできます。

darkMode=false

darkMode=false

または、レルム設定の Theme タブで Dark mode 設定をオフにして、レルムごとに組み込み Keycloak テーマのダークモードサポートを無効にすることもできます。

以前のバージョンでは、管理コンソールで Sign out all active sessions をクリックすると、通常のセッションのみが削除されました。オフラインセッションは、事実上無効になっているにもかかわらず、引き続き表示されます。

このアプローチは変更されました。すべてのアクティブなセッションからサインアウトすると、すべてのセッション (通常セッションとオフラインセッション) が削除されるようになりました。

このリリース以降、Red Hat build of Keycloak JavaScript アダプターおよび Red Hat build of Keycloak Node.js アダプターは、Red Hat build of Keycloak サーバーのリリースサイクルとは独立するようになりました。26.2.0 リリースは、これらのアダプターが Red Hat build of Keycloak サーバーとともにリリースされる最後のリリースになる可能性がありますが、今後は、これらのアダプターは Red Hat build of Keycloak サーバーとは異なるタイミングでリリースされる可能性があります。

KEYCLOAK_SESSION Cookie の形式が更新され、プレーンテキスト内のプライベートデータが省略されるようになりました。これまで、クッキーの形式は realmName/userId/userSessionId でした。これで、Cookie には SHA-256 でハッシュされ URL エンコードされたユーザーセッション ID が含まれるようになりました。

AUTH_SESSION_ID Cookie の形式が更新され、認証セッション ID の署名が含まれるようになりました。これにより、署名を検証することで整合性が確保されます。新しい形式は base64 (auth_session_id.auth_session_id_signature) です。この更新により、古い形式は受け入れられなくなり、古い認証セッションは有効ではなくなります。この変更はユーザーセッションには影響しません。

これらの変更は、独自のプロバイダーを実装し、内部 Keycloak Cookie の形式に依存している場合に影響を及ぼす可能性があります。

外部で生成されたキー (rsa および java-keystore ファクトリー) をインポートできるキープロバイダーは、関連付けられている証明書が存在する場合はその有効性をチェックするようになりました。したがって、期限切れの証明書を持つキーは、Red Hat build of Keycloak にインポートできなくなります。実行時に証明書の有効期限が切れると、キーはパッシブキー (有効だがアクティブではない) に変換されます。パッシブキーは新しいトークンに使用されませんが、以前に発行されたトークンの検証には引き続き有効です。

デフォルトの 生成 キープロバイダー (証明書が関連付けられているか、関連付けられる可能性があるキープロバイダー) は、10 年間有効な証明書を生成します。有効期間が長く、キーを頻繁にローテーションすることが推奨されているため、生成されたプロバイダーはこのチェックを実行しません。

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

Admin Events API では、以前の yyyy-MM-dd 形式に加えて、Epoc タイムスタンプに基づくイベントのフィルタリングがサポートされるようになりました。これにより、取得するイベントのウィンドウをより詳細に制御できます。

direction クエリーパラメーターも追加され、返されるアイテムの順序を asc または `desc` として制御できるようになりました。以前のバージョンでは、イベントは常に desc (最新のイベントが最初) で返されていました。

最後に、返されるイベント表現には、イベントの一意の識別子を提供する id も含まれるようになりました。

X.509 オーセンティケーターには、新しいオプション x509-cert-auth-crl-abort-if-non-updated (管理コンソールで CRL abort if non updated) が追加されました。このオプションは、証明書を検証するために CRL が設定されており、次回更新フィールドで指定された時間内に CRL が更新されない場合にログインを中止します。管理コンソールで新しいオプションは、デフォルトで true に設定されます。CRL の次の更新フィールドの詳細は、RFC5280, Section-5.1.2.5 を参照してください。

以前の動作との互換性を保つために、false の値が維持されます。既存の設定には新しいオプションがなく、このオプションが false に設定されているかのように動作しますが、管理コンソールは編集時にデフォルト値 true を追加することに注意してください。

reset-credential-email (Send Reset Email) は、reset credentials フロー (forgot password 機能) で使用されるオーセンティケーターで、リセット認証情報トークンリンクを含むメールをユーザーに送信します。このオーセンティケーターには、新しいオプション force-login (Force login after reset) が追加されました。このオプションを true に設定すると、オーセンティケーターはセッションを終了し、新しいログインを強制します。

デフォルト値は only-federated であり、これは secure-by-default ポリシーをサポートします。この値は、フェデレーションユーザーの場合は強制ログインが true であり、内部データベースユーザーの場合は false であることを意味します。したがって、実装が Red Hat build of Keycloak とそれほど緊密に統合されていないユーザーフェデレーションプロバイダーによって管理されるすべてのユーザーは、問題を回避するために、認証情報リセットフローの後に再度ログインする必要があります。

詳細は、forgot password の有効化 を参照してください。

要求されたスコープ、ACR (認証コンテキストクラス参照) などの条件に基づいて、認証フローを動的に選択できるようになりました。これは、新しい AuthenticationFlowSelectorExecutor と新しい ACRCondition などの条件を組み合わせることで、クライアントポリシー を使用して実現できます。詳細は、サーバー管理ガイド を参照してください。

これまで、ユーザー API を使用してユーザー認証情報を照会しても、ユーザーストレージプロバイダーによって管理されている認証情報は返されず、その結果、認証情報が最後に更新されたときのように、フェデレーション認証情報に関連付けられた追加のメタデータを取得できなくなります。

このリリースでは、ユーザーストレージプロバイダーがレルム内の特定のユーザーに対して管理している認証情報を返すことができるように、org.keycloak.credential.CredentialInputUpdater インターフェイスに新しいメソッド getCredentials (RealmModel、UserModel) が追加されました。これにより、ユーザーストレージプロバイダーは、認証情報がリンクされているかどうかを示すことができるほか、追加のメタデータを提供して、管理コンソールを通じてユーザーを管理するときに追加情報を表示できるようになります。

LDAP の場合、標準の pwdChangedTime 属性に基づいて、または Microsoft AD を使用している場合は pwdLastSet 属性に基づいて、パスワードが最後に更新された時刻を確認できるようになりました。

認証情報がローカル (Red Hat build of Keycloak によって管理されている) かフェデレーションされているかを確認するには、CredentialRepresentation および CredentialModel タイプの両方から使用可能な federationLink プロパティーを確認します。設定されている場合、federationLink プロパティーには、特定のユーザーストレージプロバイダーに関連付けられたコンポーネントモデルの UUID が保持されます。

Red Hat build of Keycloak 送信 SMTP メール設定 で、トークン認証 (XOAUTH2) がサポートされるようになりました。Microsoft や Google などの多くのサービスプロバイダーは、Basic 認証のサポートを終了し、SMTP OAuth 認証に移行しています。トークンは、クライアント認証情報付与を使用して収集されます。

新しい管理設定が追加されました: Clients → Advanced → Fine grain OpenID Connect configuration → Use "at+jwt" as access token header type

有効にすると、アクセストークンは rfc9068#section-2.1 に準拠したヘッダータイプ at+jwt を取得します。それ以外の場合、アクセストークンのヘッダータイプは JWT になります。

この設定はデフォルトでオフになっています。

以前のリリースでは、db オプションは、実稼働 (start) モードと開発 (start-dev) モードの両方でデフォルトで dev-file に設定されていましたが、実稼働モードでは dev-file はサポートされていませんでした。このリリースでは、この動作は非推奨となり、今後のリリースでは、db オプションは実稼働モードで dev-file にデフォルト設定されなくなります。実稼働のプロファイル内の build または最適化されていない start および、サーバー以外のコマンド import、export、または bootstrap-admin の場合、値を明示的に指定する必要があります。

この変更は、実稼働環境での dev-file (H2) データベースの使用は通常、設定ミスであることが多く、この設定を意図せずに使用しないようにするためです。

JavaScript Authorization クライアントの次の API は非推奨となり、次のメジャーリリースで削除されます。

KeycloakAuthorization インスタンスのメソッドを呼び出すときに初期化がオンデマンドで自動的に実行されるため、これらの API は不要になりました。これらの API に依存するコードは安全に削除できます。

OIDC クライアントによる登録の開始に使用されていた /realms/<realm>/protocol/openid-connect/registrations エンドポイントは、OIDC クライアントから登録を開始するための標準的な方法が存在するため、非推奨になりました。この方法は現在、Red Hat build of Keycloak によってサポートされています。prompt=create のパラメーターを使用します。

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

udp、jdbc-ping-udp、tcp、azure、ec2、および google トランスポートスタックは非推奨になりました。ユーザーは、直接的な代替として TCP ベースの jdbc-ping スタックを使用する必要があります。

OpenShift v3 はサポート終了となったため、OpenShift v3 を使用したアイデンティティーブローカーのサポートは Red Hat build of Keycloak から削除されました。

以前はデフォルトで含まれていた robots.txt ファイルは削除されました。デフォルトの robots.txt ファイルはすべてのクロールをブロックし、noindex/nofollow ディレクティブに従うことができませんでした。Red Hat build of Keycloak ページが検索エンジンの結果に表示されないことがデフォルトでは望ましい動作です。これは、デフォルトで none に設定されている既存の X-Robots-Tag ヘッダーによって実現されます。異なる動作が必要な場合、このヘッダーの値はレルムごとに上書きできます。

以前にこのような状況のためにリバースプロキシー設定にルールを追加していた場合は、そのルールを削除できます。

X-XSS-Protection ヘッダー は、Red Hat build of Keycloak でサポートされているユーザーエージェントでサポートされなくなったため、削除されました。このヘッダーは、Internet Explorer、Chrome、Safari の機能で、反射型クロスサイトスクリプティング (XSS) 攻撃が検出されるとページの読み込みが停止されました。

ユーザーエージェントでのサポートが不足していること、およびこの機能が Content Security Policy (CSP) に置き換えられていることから、これがデプロイメントに影響することはないと考えられます。