アップグレードガイド

セキュリティーを向上させるため、権限チケットの管理に関するアクセス制御が厳格化され、特定のリソースサーバーの権限チケットを管理できるのは 、uma-protection ロールが付与されたユーザー (またはサービスアカウント) のみとなりました。唯一の例外はリソースサーバー自体であり、これは uma-protection ロールなしで権限チケットを管理できます。

セキュリティーを向上させるため、レルムとクライアントロールのリスト表示に対するアクセス制御が厳格化され、管理者に対して クエリー -* ロールのみを付与するだけではロールのリスト表示はできなくなりました。

その代わりに、管理者は、ロールをリスト表示したいレルムまたはクライアントを表示または管理するための明示的な権限を持っている必要があります。レルムロールの場合は view- レルム または manage- レルム ロール、クライアントロールの場合は view-clients または manage-clients ロールが必要です。

セキュリティーを強化するため、レルムからユーザープロファイルの設定とメタデータを取得するためのアクセス制御が厳格化され、管理者に何らかの管理権限が付与されている場合は、これらの情報を取得できなくなりました。

その代わりに、管理者はユーザーを表示または管理するための明示的な権限を持っているか、または view- レルム、manage- レルム、view-users、manage-users、query-users の いずれかのロールを持っている必要があります。

Red Hat build of Keycloak は、アイデンティティーブローカーまたはアダプターで SAML サービスプロバイダー (SP) として動作する場合、標準で定義されているタイプ urn:oasis:names:tc:SAML:2.0:cm:bearer の SubjectConfirmationData を検証します。アサーション内に存在する要素 NotBefore、NotOnOrAfter、 および Recipient は、それぞれ有効な時間範囲内であること、および正しい宛先 URI であることがチェックされます。以前は、SAML レスポンスの他の部分 (たとえば、Conditions 要素や destination 属性) についても同様の値がチェックされていました。

アップグレードに備えるため、アイデンティティープロバイダーまたはアダプターの設定で、時間属性に対して十分なクロックスキューが許容されていることを確認してください。

アップグレード後にこの要素に関連する問題が発生した場合は、外部 IdP を設定して、対象確認要素に正しい値を設定してください。

以前のリリースでは、Red Hat build of Keycloak は、パスにダブルドット (..) またはダブルスラッシュ (//) を含むパスを持つ HTTP リクエストを受け入れていました。これらのリクエストを処理すると、RFC3986 に従ってダブルスラッシュが折りたたまれた正規化されたパスが生成されました。このアプローチにより、URL フィルタリングの設定が難しくなりました。たとえば、リバースプロキシーでは正規化が無効になり、Red Hat build of Keycloak は HTTP 400 応答コードで応答します。

サーバーログで拒否されたリクエストを分析するには org.keycloak.quarkus.runtime.services.RejectNonNormalizedPathFilter のデバッグログを有効にします。

以前の動作に戻して、正規化されていない URL を受け入れるには、http-accept-non-normalized-paths を true に設定します。この設定では、HTTP アクセスログを有効にして確認し、問題のあるリクエストを特定します。

acr_values リクエストパラメーターは、認証中に OpenID Connect アイデンティティープロバイダーに自動的に転送されなくなりました。この変更により、認証コンテキスト情報が外部 IDP に意図せず公開されることを防ぎ、セキュリティーが強化されます。

acr_values パラメーターがアイデンティティープロバイダーに伝播されることに依存している場合は、アイデンティティープロバイダー設定の Forwarded query parameters 設定に acr_values リクエストパラメーターを明示的に設定する必要があります。

Red Hat build of Keycloak の以前のバージョンの一部では、EnterpriseDB (EDB) はサポートされていないとみなされていました。これは変更され、このリリース以降、EDB Advanced がサポートされるようになりました。以前のバージョンで EDB への接続に EDB JDBC ドライバーが使用されていた場合、一部の無効なスキーマ変更がデータベースに適用されていました。これを軽減するために、このバージョンへのスキーマ移行中に一部のインデックスが自動的に再作成されます。これは、以前のリリースで EDB を使用していたかどうかに関係なく、PostreSQL データベース (EDB を含む) を使用している場合に影響します。

これは、CLIENT_ATTRIBUTES と GROUP_ATTRIBUTE テーブルのインデックスに影響します。これらのテーブルに 300,000 を超えるエントリーが含まれている場合、Red Hat build of Keycloak は、デフォルトで自動スキーマ移行中にインデックスの作成をスキップし、Red Hat build of Keycloak の起動後に手動で適用できるように、代わりに移行中にコンソールに SQL ステートメントを記録します。異なる制限を設定する方法の詳細は、アップグレードガイド を参照してください。

以前のリリースでは、追加のデータソースを設定する唯一の方法は、一般的にサポートされていないと考えられている raw の Quarkus プロパティーを使用することでした。同時に、追加のデータソースの追加がサポートされていたため、状況が不明確になっていました。

追加のデータソースを設定するためのサポートされたユーザーフレンドリーな方法を提供するために、専用の新しいサーバーオプションを導入しました。このリリース以降、Quarkus プロパティーを介した元のアプローチを使用して追加のデータソースを設定することは、サポート対象外 とみなされます。

設定を移行する方法については、次の例を確認してください。

以前のリリースでは、ユーザーの取得 (GET /admin/realms/{realm}/users/{user-id}) とユーザーの検索 (GET /admin/realms/{realm}/users) の REST エンドポイント結果に不一致がありました。BruteForce が有効になっていて、ユーザーが一時的にロックアウトされている場合、前者のエンドポイントは enabled=false を返し、後者のエンドポイントは enabled=true を返します。ユーザーが更新された際、一時的なロックアウトによって enabled の値が false になっていた場合、そのユーザーは永続的に無効化されます。ユーザーが一時的にロックアウトされている場合、両方のエンドポイントは enabled=true を返すようになりました。ユーザーが一時的にロックアウトされているかどうかを確認するには、BruteForceUserResource エンドポイントを利用する必要があります (GET /admin/realms/{realm}/attack-detection/brute-force/users/{userId})。

User API を通じてユーザーをクエリーする場合、ユーザー表現とその属性では、レルムに定義されたユーザープロファイル設定が考慮されるようになりました。

過去に返された情報が多すぎる場合、ユーザープロファイルの設定によっては、ユーザー表現内の属性が利用できなくなる可能性があります。

Red Hat build of Keycloak がブローカーとして機能し、OpenID Connect によって別のアイデンティティープロバイダーに接続するシナリオでは、RFC6749 で指定されている正しいエンコードで、Basic 認証によってクライアント認証情報が送信されるようになりました。Red Hat build of Keycloak をリクエスト本文で認証情報を送信するように設定していた場合は、影響を受けません。

これにより、コロンやパーセント記号などが含まれるクライアント ID やパスワードの問題を回避できます。

古い動作に戻すには、クライアント認証を非推奨のオプションである Client secret sent as HTTP Basic authentication without URL encoding (client_secret_basic_unencoded) に変更します。

OIDC トークンエンドポイントリクエスト (または OAuth2 トークンエンドポイントリクエスト) が送信される際、すべての OIDC/OAuth2 パラメーターの最大長に新たな制限が設けられます。各パラメーターの最大長は 4,000 文字であり、これは OIDC/OAuth 認証リクエストに送信されるパラメーターにすでに存在する制限と同じです。

これらの数値を増減させたい場合は、OIDC/OAuth2 パラメーターのデフォルトの最大長を指定するオプション req-params-default-max-size を指定してサーバーを起動するか、特定のパラメーターに対して req-params-max-size などを指定することもできます。詳細は、すべてのプロバイダー設定ガイド の ログインプロトコル プロバイダー設定を参照してください。

このリリース以降、Red Hat build of Keycloak SAML 実装では、REDIRECT バインディングを通じて送信できるデータ量が制限されています。デフォルトの最大サイズは 128KB で、この値を超えると展開処理が停止し、エラーが返されます。オプション spi-login-protocol—saml—max-inflating-size を 使用すると、デフォルトの制限値を増やすことができます。

bin/kc.[sh|bat] --spi-login-protocol--saml--max-inflating-size=524288

SAML Galleon 機能パックにも同様の制限が適用されます。ただし、この場合は、デフォルトの最大サイズを変更するために、EAP サーバーにシステムプロパティーを追加する必要があります: -Dorg.keycloak.adapters.saml.maxInflatingSize=524288。

以前は、少なくとも 2 つの CPU コアが利用可能な場合に仮想スレッドが使用されていました。このバージョン以降、仮想スレッドは少なくとも 4 つの CPU コアが利用可能な場合にのみ使用されます。この変更により、固定された仮想スレッドによるデッドロックを防ぐことができるはずです。

Red Hat build of Keycloak のデータベースとして PostgreSQL を使用している場合は、効率的なアップグレードを確実にするために、データベースユーザーが次のテーブルに対する SELECT 権限を持っていることを確認してください: pg_class、pg_namespace。

これは、Red Hat build of Keycloak のアップグレード時に、テーブル内の行数を推定するために使用されます。Red Hat build of Keycloak がこれらのテーブルにアクセスする権限を持っていない場合、警告をログに記録し、スキーマ変更の影響を受けるテーブルの行数を判断するために、アップグレード中に効率の低い SELECT COUNT(*) ... 操作を実行します。

以前の Red Hat build of Keycloak は、セミコロン (;) を含むパスを持つ HTTP リクエストを受け入れていました。これらを処理する際、RFC 3986 に従って行列パラメーターの区切り文字として扱い、基本的にこれらの部分は無視されました。これにより、たとえばリバースプロキシーにおいて、設定が困難な URL フィルタリングが発生することがあったため、この機能は現在無効になっており、Red Hat build of Keycloak は HTTP 400 応答コードを返します。

サーバーログで拒否されたリクエストを分析するには org.keycloak.quarkus.runtime.services.RejectNonNormalizedPathFilter のデバッグログを有効にします。

以前の動作に戻してマトリックスパラメーターを受け入れるには、オプション http-accept-non-normalized-paths をtrue に設定します。この設定では、HTTP アクセスログを有効にして確認し、問題のあるリクエストを特定します。

BROKER_LINK テーブルに、パフォーマンス向上のため、IDX_BROKER_LINK_USER_ID と IDX_BROKER_LINK_IDENTITY_PROVIDER という 2 つのインデックスが追加されました。

テーブルに 30 万件を超えるエントリーが含まれている場合、Red Hat build of Keycloak はデフォルトで自動スキーマ移行中にインデックス作成をスキップし、代わりに移行中に SQL ステートメントをコンソールにログ出力して、Red Hat build of Keycloak の起動後に手動で適用します。異なる制限を設定する方法の詳細は、データベースの移行 を参照してください。

LDAP リフェラルには、デフォルトで LDAP URL のみを含むことが許可されるようになりました。この変更により、セキュリティーが強化され、LDAP 設定のベストプラクティスに準拠するようになります。

この変更により、カスタム拡張を記述した場合に他の JDNI 参照が使用されなくなります。元の動作に戻すには、オプション spi-storage—​ldap—​secure-referral を false に設定します。このアクションと組み合わせて、すべての LDAP プロバイダーで LDAP 参照を無効にすることが推奨されます。

以前のバージョンでは、realm-admin ロールを付与されたレルム管理者は、委任されたレルム管理者に管理者ロールを付与できませんでした。この権限は、マスターレルムユーザーに admin ロールを付与した場合にのみ可能でしたが、その結果、そのユーザーはサーバー管理者となっていました。

このリリースでは、realm-admin ロールを持つレルム管理者は、レルム内のユーザーに管理者ロールを割り当てることができるため、サーバー管理者特権を必要とせずに管理タスクを委任できます。

FGAP を使用してマスターレルム以外のレルムのユーザーに管理を委任する場合は、特権エスカレーションを回避するために、realm-admin ロールが付与されたユーザーにこのロールが付与されることを確認してください。

さまざまなタイプのレルム管理者の詳細は、権限を使用したレルム管理の委任 を参照してください。

この変更により、OFFLINE_CLIENT_SESSION テーブルに新しいインデックスが追加され、クライアントセッションを取得または削除する際のパフォーマンスが向上します。

これらのテーブルに 300,000 を超えるエントリーが含まれている場合、Red Hat build of Keycloak は自動スキーマ移行中にインデックスの作成をスキップします。代わりに、移行時に、Red Hat build of Keycloak の起動後に手動で適用する必要がある SQL ステートメントが表示されます。異なる制限を設定する方法の詳細は、データベースの移行 を参照してください。

ディストリビューションをダウンロードして Red Hat build of Keycloak をアップグレードする場合、アップグレード手順が変更されました。以前は、conf/ フォルダーの内容を古いインストールから新しいインストールにコピーすることが推奨されていました。新しい手順では、新しいバージョンに含まれるファイルに基づいて、cache-ispn.xml またはカスタムキャッシュ設定への変更を再度適用することが推奨されます。

これにより、たとえば以前のバージョンの古い cache-ispn.xml ファイルを使用することによって、誤って機能がダウングレードされることが防止されます。

データベースごとにサポートされているバージョンは、データベースの設定 に記載されるようになりました。ただし、基礎となるデータベース固有の Hibernate 方言が、記載されているバージョンと異なるバージョンの使用を許可していたとしても、それはサポートされる構成にはなりません。

User API を介して属性でユーザーをクエリーし、特定の属性キー (値に関係なく) に一致するユーザーを取得する場合は、GET メソッドを使用して /admin/realms/{realm}/users を呼び出すときに、exact リクエストパラメーターを false に設定することを検討してください。

たとえば、myattribute 属性が設定されているすべてのユーザーを検索する場合は、次のように実行する必要があります。

GET /admin/realms/{realm}/users?exact=false&q=myattribute:

Red Hat build of Keycloak Admin Client もまた、exact リクエストパラメータを使用して属性でユーザーを検索するための新しいメソッドで更新されました。

レルム設定で "Remember Me" オプションが無効になっている場合、"Remember Me" フラグを使用して以前に作成されたすべてのユーザーセッションは無効とみなされます。ユーザーは再度ログインする必要があり、関連付けられているリフレッシュトークンは使用できなくなります。"Remember Me" を選択せずに作成されたユーザーセッションは影響を受けません。

PostgreSQL のリーダーインスタンスとライターインスタンスを実行する場合、Red Hat build of Keycloak は作業を実行するために常にライターインスタンスに接続する必要があります。

このリリース以降、元の PostgreSQL ドライバーを使用する場合、Red Hat build of Keycloak は PostgreSQL JDBC ドライバーの targetServerType プロパティーを primary に設定して、常に書き込み可能なプライマリーインスタンスに接続し、フェイルオーバーまたはスイッチオーバーのシナリオでセカンダリーリーダーインスタンスに接続しないようにします。

DB URL または追加のプロパティーで targetServerType に独自の値を設定することで、この動作をオーバーライドできます。

EVENT_ENTITY テーブルの USER_ID、TYPE、EVENT_TIME 列にインデックス IDX_EVENT_ENTITY_USER_ID_TYPE が追加されました。これにより、管理コンソールで特定のユーザーおよびイベントタイプのイベントをより高速に検索できるようになりました。

テーブルに 300,000 を超えるエントリーが含まれている場合、Red Hat build of Keycloak は、自動スキーマ移行中にインデックスの作成をスキップします。ただし、移行中に SQL ステートメントがコンソールに表示されるので、Red Hat build of Keycloak の起動後に手動で適用できます。異なる制限を設定する方法の詳細は、データベースの移行 を参照してください。

Red Hat build of Keycloak を FIPS 140-2 モードで実行している場合は、Bouncy Castle ライブラリーをリリースドキュメントに記載されているバージョンに更新します。

Bouncy Castle 2.1.x へのアップグレードにより、EdDSA が FIPS 140-2 モードでサポートされるようになりました。

リモートキャッシュを使用する場合、Red Hat build of Keycloak は、Data Grid サーバー上にまだ存在しない場合、起動時に必要なキャッシュを自動的に作成するようになりました。

マルチクラスターセットアップの場合でも、キャッシュの初期化が正しいことを確認し、キャッシュがサイトの 1 つにのみ存在する場合の起動エラーを回避するために、事前に Cache CR を使用してキャッシュを作成することが推奨されます。

以前のバージョンの Red Hat build of Keycloak では、揮発性ユーザーセッションを有効にするときに、所有者の数が間違って設定されていたり、キャッシュサイズが設定すべきでないのに設定されていたりするなど、問題のある設定について警告が出されていました。ドキュメントには、揮発性ユーザーセッションの cache-ispn.xml 設定ファイルを更新することも記載されています。

現行バージョンでは、影響を受けるユーザーおよびクライアントセッションキャッシュの所有者の数と最大キャッシュサイズに対して常に安全な設定が使用され、INFO メッセージのみがログに記録されます。この動作により、cache-ispn.xml 設定ファイルを更新する必要がなくなります。以前に揮発性ユーザーセッションを使用するためにカスタムの cache-ispn.xml を使用していた場合は、それらの変更を元に戻し、標準の設定ファイルを使用することが推奨されます。

conf/cache-ispn.xml ファイルには、デフォルトのキャッシュ設定が含まれなくなりました。このファイルでは、Red Hat build of Keycloak で使用されるキャッシュ設定を引き続き上書きできますが、--cache-config-mutate=true オプションが設定されていない場合、Red Hat build of Keycloak は警告を記録します。このオプションを設定せずに、カスタムキャッシュを追加することは引き続き可能です。

既存のデプロイメントをアップグレードする場合は、既存の conf/cache-ispn.xml からすべてのデフォルトのキャッシュ設定を削除し、--cache-... オプションを使用して、たとえばキャッシュサイズなどに変更を加えます。

データベースサーバーによって接続が予期せず閉じられるのを防ぐには、サーバーの wait_timeout 設定に関して Red Hat build of Keycloak 接続プールが正しく設定されていることを確認する必要があります。

このリリース以降、Red Hat build of Keycloak は、デフォルトの wait_timeout が 8 時間であるため、MySQL および MariaDB データベースのデフォルトの db-pool-max-lifetime を 7 時間 50 分に定義します。

サーバーがデフォルトまたは指定された db-pool-max-lifetime 値よりも大きい wait_timeout を定義した場合、Red Hat build of Keycloak の起動時に警告が記録されます。

Red Hat build of Keycloak は、ルート URL レベル /.well-known/ で RFC8414 準拠のエンドポイントを公開し、クライアントが発行者 URL によって OAuth 2.0 Authorization Server Metadata やその他の既知のプロバイダーを検出できるようになりました。

たとえば、OAuth 2.0 Authorization Server Metadata 情報は、次の URL によって公開されました。

https://keycloak.example.com/realms/{realm}/.well-known/oauth-authorization-server

この URL でも利用できるようになりました:

https://keycloak.example.com/.well-known/oauth-authorization-server/realms/{realm}

このメリットを享受するには、リバースプロキシー設定で /.well-known/ パスを公開します。

デフォルトのスケジューリングストラテジーが更新され、障害発生時の可用性を高めるために、ゾーンとノードの両方にトポロジー拡散制約が作成されるようになりました。以前は、デフォルトのストラテジーでは、すべてのノードが同じアベイラビリティーゾーンにデプロイされることが推奨されていました。詳細は、高可用性ガイド を参照してください。

以前は、JGroups ネットワークアドレスとポートを設定するには、jgroups.bind.* と jgroups.external_* システムプロパティーを使用する必要がありました。このリリースでは、これらのアドレスとポートを Red Hat build of Keycloak で直接設定できるように、次の CLI オプションが導入されています。

古いプロパティーを使用してポートを設定する方法は変更されていませんが、以前の方法は非推奨となる可能性があるため、CLI オプションを使用することが推奨されます。

埋め込み Infinispan の認証済みクライアントセッションのキャッシュキーは変更されましたが、パブリック API は変更されていません。このため、バージョン 26.4.1 を以前のバージョンと同時にクラスター内で実行しないでください。

OAuth 2.0 IDP がリフレッシュトークンと JSON 応答を提供する場合、または OIDC IDP の場合に、/realms/{realm-name}/broker/{provider_alias}/token エンドポイントを使用すると、アクセストークンが期限切れであり、かつ IDP がリフレッシュトークンを提供している場合、トークンがそのエンドポイント経由で取得されるたびに自動的に更新されます。

GitHub を IDP として使用する場合、JSON 応答を有効にして、このエンドポイントのトークン更新を活用できるようになりました。

永続的なユーザーセッション更新のバッチ処理は、一部のデータベースベンダーのパフォーマンスに悪影響を与え、他のデータベースベンダーの利点を相殺するため、デフォルトでオフになっています。CLI オプション --spi-user-sessions—​infinispan—​use-batches=true を使用してバッチ処理を有効化できますが、パフォーマンスの向上を確認するために、ユーザーには環境の負荷テストを行うことが推奨されます。

セッションノートの名前が、管理コンソールの必須フィールドとして表示されるようになりました。

トークンクレームの名前が、管理コンソールの必須フィールドとして表示されるようになりました。

このリリース以降、揮発性ユーザーセッションが有効になっている場合、Red Hat build of Keycloak は、デフォルトでオフラインユーザーおよびクライアントセッションの 10,000 エントリーのみをメモリーにキャッシュします。この変更により、メモリー使用量が大幅に削減されます。

オフラインセッションキャッシュのサイズを変更するには、cache-embedded-offline-sessions-max-count および cache-embedded-offline-client-sessions-max-count オプションを使用します。

クラスローダーおよびフォルダーベースのテーマ内のリソースバンドルの命名が、Java ResourceBundle#getBundle ファイル名と一致するようになりました。de や pt-BR など、含まれるすべてのコミュニティー言語の場合、ファイルの名前は引き続き messages_de.properties または messages_pt_BR.properties になります。カスタム言語コードを追加した場合は、ファイル名が引き続き同じであるかどうかを確認します。

Red Hat build of Keycloak のコミュニティテーマにおいて、「中国語 (繁体字)」と「中国語 (簡体字)」は、歴史的な理由から zh-TW と zh-CN という名前で識別されています。新しい言語コードである zh-Hant および zh-Hans への移行の第一歩として、クラスローダーベースとフォルダーベースのテーマは、古い言語コードの zh-TW と zh-CN に加えて、messages_zh_Hant.properties と messages_zh_Hant.properties のファイルも認識するようになりました。messages_zh_Hant.properties 内のエントリーは、messages_zh_TW.properties 内のエントリーよりも優先され、messages_zh_Hans.properties 内のエントリーは、messages_zh_CN.properties 内のエントリーよりも優先されます。

Update Email はサポート対象機能になったため、サーバーの起動時に有効になります。レルム内で Update Email 必須アクションが有効になっている場合、この機能はレルムに対して有効になります。この機能により、認証フロー中にプロファイルを更新する際 (UPDATE_PROFILE 必須アクションを実行する際など) に、以前のバージョンから動作をわずかに変更します。認証フロー中にプロファイルを更新するときにユーザーにメールが設定されている場合、メール属性は使用できません。

SAML クライアントで Encrypt Assertions が有効化されていた場合、SAML 応答に含まれるアサーションは XML Encryption Syntax and Processing 仕様に従って暗号化されていました。暗号化に使用されていたアルゴリズムは、固定されており、かつ古くなっていました。このリリース以降、デフォルトの暗号化オプションは最新となり、セキュリティーの面でより適したものになっています。さらに、特定のクライアントに異なるアルゴリズムが必要な場合は、暗号化の詳細を設定できます。暗号化に使用される正確なアルゴリズムを指定するには、クライアントで新しい属性を定義します。管理コンソールの Keys タブで Encrypt Assertions が有効になっている場合、これらの属性はクライアントの Settings タブの Signature and Encryption セクションに表示されます。

下位互換性を維持するために、Red Hat build of Keycloak アップグレードでは、既存の SAML クライアントを変更して、暗号化属性が以前と同じように機能するように設定します。その結果、既存のクライアントは、以前と同じアルゴリズムを使用して同じ暗号化されたアサーションを受け取ります。クライアントが新しいデフォルト設定をサポートしている場合は、属性を削除することが推奨されます。

クライアント設定の詳細は、SAML クライアントの作成 を参照してください。

必須アクションまたはアプリケーションによって開始されるアクションとしてメールアドレスを検証する場合、ユーザーはデフォルトで 30 秒ごとにのみ確認メールを再送信できますが、以前のバージョンではメールの再送信に制限はありませんでした。

管理者は、レルムの Authentication セクションにある Verify Email 必須アクションで、レルムごとの間隔を設定できます。

トレーシングが有効化されると、Red Hat build of Keycloak クラスターの他のノードへの呼び出しによって、トレースにスパンが作成されるようになりました。

この種のトレーシングを無効にするには、オプション tracing-infinispan-enabled を false に設定します。

LDAP 設定で connectionTimeout として、または com.sun.jndi.ldap.connect.timeout システムプロパティーによって値が指定されていない場合、デフォルトのタイムアウトは 5 秒になります。このタイムアウトにより、プールから LDAP 接続を取得する際、または LDAP サーバーに接続する際に、リクエストに対して無期限の待機ではなくエラーが表示されるようになります。

OTP およびリカバリーコード用のログインテーマの入力フィールドが最適化されました。

OIDC 認証リクエスト (または OAuth2 認可リクエスト) が送信される際、すべての標準 OIDC/OAuth2 パラメーターの最大長に対して、新しい制限が設けられました。各標準パラメーターの最大長は 4,000 文字ですが、これは非常に大きな数値であり、今後のリリースで短縮される可能性があります。現時点では、下位互換性のために大きいままになっています。唯一の例外は login_hint パラメーターで、最大長は 255 文字です。この値は、デフォルトのユーザープロファイル設定で設定された username と email 属性の最大長と一致します。

これらの数値を増減したい場合は、標準 OIDC/OAuth2 パラメーターのデフォルトの最大長を指定する req-params-default-max-size オプションを指定してサーバーを起動するか、特定のパラメーターに req-params-max-size などを使用することもできます。詳細は、すべてのプロバイダー設定 の login-protocol プロバイダー設定を参照してください。

このリリースから、Red Hat build of Keycloak はレルム SMTP 設定に新しいオプション allowutf8 を追加します (管理コンソールの Realm settings セクションの Email タブ内の Allow UTF-8 フィールド)。メールの設定の詳細は、レルムのメールの設定 を参照してください。

このオプションを有効にすると、メールを送信する際にメールアドレスが UTF-8 でエンコードされますが、SMTP サーバー側が SMTPUTF8 拡張によって UTF-8 をサポートしている必要があります。Allow UTF-8 が無効な場合、Red Hat build of Keycloak は、非 ASCII 文字が使用されている場合に、メールアドレスのドメイン部分 (@ の後に続く 2 番目の部分) を punycode を使用してエンコードし、ローカル部分に非 ASCII 文字が使用されているメールアドレスを拒否します。このオプションが無効になっている場合、組み込みのユーザープロファイルメールバリデーターは、アドレスのローカル部分に ASCII 文字のみが含まれていることも確認し、SMTP 設定で使用できないメールの登録を回避します。

レルムに SMTP サーバーが設定されている場合は、アップグレード後に次の移行を実行してください。

管理コンソールまたは User API でユーザーを検索する場合、/admin/realms/{realm}/users/count エンドポイントから返されるユーザー数は、/admin/realms/{realm}/users で検索を実行したときに返される実際のユーザー数と一致するようになりました。

ユーザー数エンドポイントに依存している場合は、ユーザー数が検索から返される実際のユーザー数と一致することをクライアントが期待するように必ず確認してください。

OTP、WebAuthn、またはその他の 2FA 認証情報を追加する場合、ユーザーがこの認証情報に割り当てる名前は、特定のユーザーに対して一意である必要があります。これにより、ユーザーはそれらの認証情報を区別できるようになり、後で更新したり削除したりできます。ユーザーがすでに存在する名前で認証情報を作成しようとすると、エラーメッセージが表示され、ユーザーは新しい認証情報の名前を変更するように求められます。

セキュリティーを強化するために、master レルムで admin ロールを持つユーザー (サーバー管理者) のみが管理者ロールを割り当てることができます。これにより、重要な権限がレルムレベルの管理者によって委任されなくなります。

これまで、OpenID Connect ブローカーは、OpenID Connect プロバイダーによって発行された ID トークンから利用できる標準の email_verified クレームをサポートしていませんでした。

このリリースでは、ブローカーが更新されてこのクレームの値が考慮され、フェデレーションされた (ローカル) ユーザーアカウントのメール検証ステータスが設定されるようになりました。ユーザーが初めてフェデレーションされるか再認証されるたびに、Trust email 設定が有効になっていて、Sync Mode が FORCE に設定されている場合は、ユーザーアカウントが更新され、メールが検証済みとしてマークされます (またはマーク解除されます)。プロバイダーがクレームを送信しない場合は、デフォルトで元の動作に戻り、メールは検証済みとして設定されます。

将来的には、ユースケースやコミュニティーからの需要に応じて、フェデレーションされたユーザーアカウントのメール検証ステータスの自動更新を回避するために、この特定の設定を変更することを検討する可能性があります。

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 のステップを無効化できます。

詳細は、初回ログインフロー を参照してください。

以前は、ユーザーがパスワードを変更したり、OTP やパスキーなどの別の要素を追加したりするなど、認証情報を更新すると、Sign out from other devices チェックボックスがデフォルトでオンになっていました。このリリース以降、Red Hat build of Keycloak では、Sign out from other devices のチェックボックスをデフォルトではチェックされていない状態で表示します。同じユーザーに関連付けられている他のすべての関連セッションをログアウトするには、ユーザーがこのチェックボックスを意図的に有効にする必要があります。

前の点に関連して、以前のバージョンでは、Sign out from other devices のチェックボックスは、通常のセッションのみをログアウトさせていました。このリリース以降、現在の画面デザインからユーザーが期待する動作となるよう、この機能はオフラインセッションもログアウトさせるようになりました。

古い動作に戻すには、非推奨の機能 logout-all-sessions:v1 を有効にします。この非推奨の機能は、今後のバージョンで削除される予定です。

Welcome Page では、一時的な管理者ユーザーではなく、通常の管理者ユーザーが作成されます。

Fine-Grained Admin Permissions (FGAP) 機能に、新しいスコープ reset-password が含まれるようになりました。このスコープでは、管理者に、より広範な manage スコープを付与せずにユーザーのパスワードをリセットするための特定の権限を付与できます。

デフォルトでは、USERS リソースタイプに対する既存のより広範な manage スコープを持つユーザーには、ユーザーのパスワードをリセットする権限が暗黙的に与えられます。システムは最初に明示的な reset-password スコープをチェックします。その権限が見つからない場合は、管理者が manage スコープを持っているかを確認するという方法にフォールバックします。これにより、manage スコープを持つ既存の管理者は、権限を変更することなく、引き続きパスワードをリセットできるようになります。

この暗黙的なフォールバックメカニズムにより、きめ細かな権限をすでに使用しているデプロイメントのアップグレードプロセスがスムーズになります。フォールバックは今後のリリースでは非推奨となり削除される予定なので、必要に応じて新しい reset-password スコープを使用するために管理者権限を確認して更新することが推奨されます。

詳細は、Fine-Grained Admin Permissions を参照してください。

これまでは、LDAP ユーザーフェデレーションプロバイダーからユーザーを検索するときに失敗すると、リクエスト全体が失敗し、ユーザーが返されませんでした。このリリースでは、検索中にエラーが発生した場合でも、ローカルユーザーが返され、エラーが ERROR レベルで記録されるため、管理者は問題の根本原因を調査し、LDAP 設定または LDAP サーバーとの接続に関する問題を修正できます。

この変更により、LDAP サーバーに一時的な問題が発生した場合のシステムの回復力が向上し、LDAP 検索が失敗した場合でもローカルユーザーに引き続きアクセスできるようになります。ローカルユーザーが障害の発生した LDAP プロバイダーにリンクされている場合、LDAP サーバーが再び使用可能になるまで、そのユーザーは無効化され、読み取り専用としてマークされます。

このバージョン以降、管理コンソールが Red Hat build of Keycloak インストールの一般情報を取得するために使用する serverinfo エンドポイントは、管理 (マスター) レルムの管理者のシステム情報のみを返すようになります。この変更は、セキュリティー上の理由で行われました。

何らかの理由で、共通レルムの管理者が serverinfo 応答の systemInfo、cpuInfo、または memoryInfo フィールドにアクセスする必要がある場合は、新しい view-system ロールを作成してその管理者ユーザーに割り当てる必要があります。

以前の回避策は非推奨とマークされており、Red Hat build of Keycloak の今後のバージョンでは削除される可能性があります。

server-spi-private モジュール内の SimpleHttp ユーティリティーがリファクタリングされ、org.keycloak.http.simple パッケージに移動されました。

ローカリゼーションのサポートを改善するために、user-profile-commons.ftl が変更されました。その結果、このテンプレートを拡張する場合、ページに locale フィールドが表示されるようになる可能性があります。これを回避するには、前述の変更を加えてテーマテンプレートを更新します。

グループのサブグループを返す場合、グループの各サブグループのサブグループの数はキャッシュされなくなりました。Fine-Grained Admin Permissions の導入により、結果セットはレルムに定義された権限に基づいてデータベースレベルでフィルタリングされ、カウントがこれらの権限に応じて変更されるようになります。

カウントをキャッシュする代わりに、管理者がアクセスできるグループの期待される数を取得するために、毎回クエリーが実行されるようになります。

ほとんどの場合、この変更は、API をクエリーしてあるグループのサブグループを取得するクライアントには影響を与えません。しかし、もし影響がある場合のために、以下のエンドポイントに新しいパラメーター subGroupsCount が導入されました。

このパラメーターを使用すると、クライアントは返される個々のグループごとにカウントを返すかどうかを決定できます。既存のデプロイメントを壊さないように、このパラメーターはデフォルトで true に設定され、パラメーターが設定されていない場合はカウントが返されます。

以前のデフォルトの browser フローには、ワンタイムパスワード (OTP) を第 2 要素認証 (2FA) として有効にするための Browser - Conditional OTP という条件付きサブフローが含まれていました。このバージョン以降、サブフローの名前が Browser - Conditional 2FA に変更され、OTP Form は Alternative になり、WebAuthn Authenticator と Recovery Authentication Code Form というさらに 2 つの 2FA 方式が追加されました。両方の新しい実行はデフォルトでは Disabled になっていますが、Alternative に設定してフローに含めることができます。

アップグレードされたレルムは変更されません。更新されたフローは新しいレルムでのみ利用可能になります。レルムの作成を自動化している場合は、この変更を考慮してください。

tcp (または ssl-tcp) プロトコル経由で送信される Syslog メッセージでは、デフォルトでカウントフレーミングが使用されるようになり、一部の Syslog サーバーで必要なサイズがメッセージの先頭に付加されるようになりました。

この動作を変更するには、protocol-dependent (デフォルト)、true、または false のいずれかの値を持つ --log-syslog-counting-framing オプションを使用します。

以前のリリースでは、kc.realmName や kc.clientId などの特定の OpenTelemetry スパン属性が親 HTTP リクエストスパンに表示されていました。スパン属性は、情報が実際に判明している子スパンにのみ設定されるようになりました。これらの属性に基づいて親 HTTP スパンをフィルタリングしていた監視ツールは、代わりに適切な子スパンを照会する必要があります。

バージョン 26.4.1 では、特定の機能が削除され、その他の機能は今後のリリースで削除される予定で非推奨としてマークされています。これらの変更の詳細は、リリースノート を参照してください。

自動移行を実行するには、目的のデータベースに接続されているサーバーを起動します。新しいサーバーバージョンでデータベーススキーマが変更すると、データベースのレコード数が多すぎない限り、移行が自動的に開始されます。

たとえば、数百万件のレコードを含むテーブルにインデックスを作成すると、時間がかかり、サービスの大きな中断を引き起こす可能性があります。したがって、自動移行には 300000 レコードのしきい値が存在します。レコード数がこのしきい値を超えると、インデックスは作成されません。代わりに、手動で適用できる SQL コマンドを含む警告がサーバーログに表示されます。

しきい値を変更するには、connections-liquibase プロバイダーの値である index-creation-threshold プロパティーを設定します。

kc.[sh|bat] start --spi-connections-liquibase--quarkus--index-creation-threshold=300000

この機能を無効にするには、値をゼロまたは負の数に設定してください。

kc.[sh|bat] start --spi-connections-liquibase--quarkus--index-creation-threshold=0

データベーススキーマを手動でアップグレードするには、デフォルトの connections-jpa プロバイダーの migration-strategy プロパティー値を "manual" に設定します。

kc.[sh|bat] start --spi-connections-jpa--quarkus--migration-strategy=manual

この設定でサーバーを起動すると、サーバーはデータベースを移行する必要があるか確認します。移行が必要な場合、必要な変更は bin/keycloak-database-update.sql SQL ファイルに書き込まれます。これらのコマンドを確認し、データベースに対して手動で実行できます。

エクスポートされた SQL ファイルのパスと名前を変更するには、デフォルトの connections-jpa プロバイダーの migration-export プロパティーを設定します。

kc.[sh|bat] start --spi-connections-jpa--quarkus--migration-export=<path>/<file.sql>

このファイルをデータベースに適用する方法の詳細は、使用しているリレーショナルデータベースのドキュメントを参照してください。変更がファイルに書き込まれると、サーバーは終了します。

テンプレートをカスタマイズした場合は、そのテンプレートの新しいバージョンと比較します。この比較により、カスタマイズしたテンプレートに適用する必要がある変更が示されます。差分ツールを使用してテンプレートを比較できます。次のスクリーンショットは、Login テーマの info.ftl テンプレートとカスタムテーマの例を比較したものです。

この比較から、1 つ目の変更点 (Hello world!!) はカスタマイズであり、2 つ目の変更点 (if pageRedirectUri) はベーステーマの変更点であることがわかります。2 つ目の変更点をカスタムテンプレートにコピーすると、カスタマイズしたテンプレートが正常に更新されます。

別の方法として、次のスクリーンショットは、古いインストールの info.ftl テンプレートと新しいインストールの更新された info.ftl テンプレートを比較したものです。

この比較から、ベーステンプレートの変更点がわかります。これをもとに、変更したテンプレートに同じ変更を手動で加えることができます。この方法はより複雑であるため、最初の方法が実行不可能な場合にのみ使用してください。

別の言語のサポートを追加した場合は、上記の変更点をすべて適用する必要があります。別の言語のサポートを追加していない場合は、何も変更する必要がない可能性があります。テーマ内の影響を受けるメッセージを変更した場合にのみ、変更を加える必要があります。

組み込みテーマのスタイルに加えた変更を反映するには、カスタムスタイルを更新する必要がある場合があります。差分ツールを使用して、古いサーバーインストールと新しいサーバーインストール間のスタイルシートの変更を比較することを検討してください。

以下に例を示します。

$ diff RHSSO_HOME_OLD/themes/keycloak/login/resources/css/login.css \
RHSSO_HOME_NEW/themes/keycloak/login/resources/css/login.css

変更を確認し、それらがカスタムスタイルに影響するかどうかを判断します。