2.5. バージョン 26.4.2 での主な変更点

ディストリビューションをダウンロードして 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:

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

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

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

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

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 オプションを使用します。

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