アップグレードガイド

古いホスト名オプションが削除されたため、ホスト名 v2 オプションがデフォルトでサポートされます。

必要な移行のリスト:

ご覧のとおり、hostname および hostname-admin オプションの *-url 接尾辞は削除されました。オプション hostname は、ホスト名と URL の両方を受け入れますが、hostname-admin は現在完全な URL のみを受け入れます。

また、path や port を個別に設定する方法はありません。これは、hostname と hostname-admin オプションの完全な URL を指定することで実現できます。

ポートが URL の一部でない場合は、受信リクエストヘッダーから動的に解決されます。

HTTPS は、hostname および hostname-admin URL の一部でない限り、強制されなくなりました。指定されていない場合、使用されるプロトコル (http/https) は受信リクエストから動的に解決されます。hostname-strict-https オプションは削除されました。

# Hostname v1
bin/kc.[sh|bat] start --hostname=mykeycloak.org --https-port=8543 --hostname-path=/auth --hostname-strict-https=true

# Hostname v2
bin/kc.[sh|bat] start --hostname=https://mykeycloak.org:8543/auth

# Hostname v1
bin/kc.[sh|bat] start --hostname=mykeycloak.org --https-port=8543 --hostname-path=/auth --hostname-strict-https=true

# Hostname v2
bin/kc.[sh|bat] start --hostname=https://mykeycloak.org:8543/auth

# Hostname v1
bin/kc.[sh|bat] start --hostname=mykeycloak.org --hostname-strict-backchannel=true

# Hostname v2
bin/kc.[sh|bat] start --hostname=mykeycloak.org --hostname-backchannel-dynamic=false

# Hostname v1
bin/kc.[sh|bat] start --hostname=mykeycloak.org --hostname-strict-backchannel=true

# Hostname v2
bin/kc.[sh|bat] start --hostname=mykeycloak.org --hostname-backchannel-dynamic=false

kcadm と kcreg がオプションとパラメーターを解析して処理する方法が変更されました。使用方法エラー、間違ったオプションまたはパラメーターからのエラーメッセージは、以前のバージョンとは若干異なる場合があります。また、使用方法エラーの場合、終了コードは 1 ではなく 2 になります。

Red Hat build of Keycloak はグループパス内のスラッシュをエスケープしたことはありません。そのため、top の子である group/slash という名前のグループは、完全なパス /top/group/slash を使用しますが、これは明らかに誤解を招きます。このバージョンから、サーバーを起動して名前内のスラッシュをエスケープできるようになりました。

bin/kc.[sh|bat] start --spi-group-jpa-escape-slashes-in-group-path=true

bin/kc.[sh|bat] start --spi-group-jpa-escape-slashes-in-group-path=true

エスケープ文字はチルダ文字 ~ です。前の例では、パスは /top/group~/slash になります。エスケープは、最後のスラッシュを階層区切りではなく、名前の一部としてマークします。

エスケープは動作の変更を表すため、現在デフォルトでは無効になっています。ただし、エスケープを有効にすることが推奨されており、今後のバージョンではこれがデフォルトになる可能性があります。

マスターレルムが存在する前に、--import-realm オプションを指定して start または start-dev コマンドを実行すると、インポートマテリアルにマスターレルムが存在する場合はインポートされます。以前の動作では、マスターレルムが最初に作成され、その後そのインポートがスキップされていました。

--optimized 起動オプションでは、最初に最適化されたサーバーイメージをビルドすることが必要になりました。これは、最初に kc.sh|bat build を実行するか、--optimized フラグなしで他の任意のサーバーコマンド (start、export、import など) を実行することによって実現できます。

オプション cache、cache-stack、cache-config-file はビルドオプションではなくなり、ランタイム時のみ指定できます。これにより、ビルドフェーズを実行してイメージを再ビルドする必要がなくなります。これらは build フェーズでは認識されないため、build フェーズから削除して runtime フェーズに追加する必要があることに注意してください。現在のキャッシュオプションを runtime フェーズに追加しない場合、Red Hat build of Keycloak はデフォルトのキャッシュ設定に戻ります。

ブローカリングなどの一部のシナリオでは、Red Hat build of Keycloak は HTTP を使用して外部サーバーと通信します。これらのプロバイダーが大量のデータを送信した場合にサービス拒否が発生するのを回避するために、Red Hat build of Keycloak では、デフォルトで応答が 10 MB に制限されるようになりました。

ユーザーは、プロバイダー設定オプション spi-connections-http-client-default-max-consumed-response-size を設定することでこの制限を設定できます。

bin/kc.[sh|bat] --spi-connections-http-client-default-max-consumed-response-size=1000000

bin/kc.[sh|bat] --spi-connections-http-client-default-max-consumed-response-size=1000000

kc.[sh|bat] import コマンドでプレースホルダーの置換が有効になりました。以前は、プレースホルダーの置換は起動時のレルムのインポートに対してのみ有効になっていました。

import コマンドのプレースホルダー置換を無効にする場合は、システムプロパティー -Dkeycloak.migration.replace-placeholders=false を追加します。

Red Hat build of Keycloak 26 では、すべてのユーザーセッションがデフォルトでデータベースに保存されます。この機能を無効にすると、この動作を以前の状態に戻すことができます。分散キャッシュの設定 ガイドの 揮発性ユーザーセッション の手順を使用します。

永続セッションを有効にすると、オンラインユーザーセッション、オフラインユーザーセッション、オンラインクライアントセッション、オフラインクライアントセッションのメモリー内キャッシュは、デフォルトでノードあたり 10000 エントリーに制限されるため、大規模なインストールでの Keycloak の全体的なメモリー使用量が削減されます。メモリーから削除されたアイテムは、必要に応じてデータベースからオンデマンドでロードされます。この機能を有効にすると、ログイン、ログアウト、トークン更新リクエストごとにメモリー使用量が削減され、データベース使用率が増加することが期待できます。

Red Hat build of Keycloak マルチサイトセットアップで外部 Data Grid のキャッシュサイズを設定するには、Data Grid Operator を使用して HA 用に Data Grid をデプロイする を参照してください。

この機能を有効にすると、spi-user-sessions-infinispan-offline-session-cache-entry-lifespan-override オプションおよび spi-user-sessions-infinispan-offline-client-session-cache-entry-lifespan-override オプションは使用できなくなります。これは、以前にオフラインセッションがメモリー内に保持される時間をオーバーライドするために、これらのオプションが使用されていたためです。

persistent-user-sessions が有効な場合に、レルムのすべてのオンラインユーザーセッションからサインアウトするには、次の手順を実行します。

データベースがユーザーセッションの信頼できる情報源になったため、セッションキャッシュのサイズを制限してメモリー使用量を削減することが可能になりました。デフォルトの conf/cache-ispn.xml ファイルを使用する場合、ユーザーおよびクライアントセッションを保存するためのキャッシュは、デフォルトでエントリーごとに 10000 セッションと 1 人の所有者のみ保存するように設定されます。

オプション cache-embedded-sessions-max-count、cache-embedded-client-sessions-max-count、cache-embedded-offline-sessions-max-count、および cache-embedded-offline-client-sessions-max-count を使用して、キャッシュのサイズを更新します。

更新されたリソース要件の詳細は、CPU およびメモリーリソースのサイズ設定の概念 を参照してください。

埋め込みキャッシュのメトリクスがデフォルトで有効になりました。レイテンシーのヒストグラムを有効にするには、cache-metrics-histograms-enabled オプションを true に設定します。

Red Hat build of Keycloak によって提供されるメトリクスに、http_server で始まる HTTP サーバーメトリクスが含まれるようになりました。以下に例を示します。

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-metrics-histograms-enabled と http-metrics-slos を使用して、デフォルトのヒストグラムバケットまたはサービスレベル目標 (SLO) の特定のバケットを有効にします。http_server_requests_seconds_bucket で提供される追加のメトリクスシリーズの使用方法に関するヒストグラムの詳細は Prometheus ドキュメント を参照してください。

/health および /metrics エンドポイントは、デフォルトでオンになっている管理ポート 9000 でアクセスできます。つまり、これらのエンドポイントは標準の Red Hat build of Keycloak ポート 8080 および 8443 に公開されなくなります。

古い動作を反映するには、プロパティー --legacy-observability-interface=true を使用します。これにより、管理ポートでこれらのエンドポイントは公開されません。ただし、このプロパティーは非推奨であり、今後のリリースでは削除される予定であるため、使用しないことを推奨します。

管理インターフェイスは、デフォルトの Red Hat build of Keycloak とは異なる HTTP サーバーを使用するため、個別に設定することができます。管理インターフェイスのプロパティーに値が指定されていない場合は、デフォルトの Red Hat build of Keycloak HTTP サーバーから値が継承されることに注意してください。

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

Red Hat build of Keycloak はデフォルトでは XA データソースを使用しません。ただし、複数のデータソースが使用されている場合、これは安全ではないと見なされます。このリリース以降、Red Hat build of Keycloak にデータソースをさらに追加する場合は、XA データソースを使用する必要があります。デフォルトのデータソースが XA をサポートしている場合は、--transaction-xa-enabled=true オプションを設定することでこれを実行できます。追加のデータソースの場合は、quarkus.properties ファイルで quarkus.datasource.<your-datasource-name>.jdbc.transactions=xa オプションを使用する必要があります。最大 1 つのデータソースが非 XA になることができます。トランザクションストア用の永続ストレージがない場合、回復はサポートされません。

プロキシーオプションがサーバーから削除されました。

Red Hat build of Keycloak Pod には、同じ CR からの複数のインスタンスが同じノードにデプロイされるのを防ぐためのデフォルトのアフィニティーが設定されるようになりました。また、ストレッチキャッシュクラスターを防ぐために、同じ CR からのすべての Pod が同じゾーンに配置されることが優先されます。

ベストプラクティスに従うために、Operator のデフォルトの CPU およびメモリー制限/要求が導入されました。これは、非 OLM インストールと OLM インストールの両方に影響します。OLM インストールのデフォルト値をオーバーライドするには、Operator の サブスクリプション の resources セクションを編集します。

org.keycloak.cluster.ClusterProvider に次のメソッドが追加されました。

複数のイベントが同じ taskKey に送信されると、このメソッドはイベントをバッチ処理し、単一のネットワーク呼び出しを実行します。これは、トラフィックとネットワーク関連のリソースを削減するための最適化です。

Red Hat build of Keycloak 26 では、カスタム実装との下位互換性を維持するために、新しいメソッドにデフォルトの実装があります。デフォルトの実装では、イベントごとに 1 つのネットワーク呼び出しが実行され、Red Hat build of Keycloak の今後のバージョンでは削除される予定です。

RealmProvider Java API に、名前でレルムを検索できる新しいメソッド Stream<RealmModel> getRealmsStream(String search) が追加されました。デフォルト実装では、プロバイダーからストリームをロードした後にフィルタリングを行いますが、より効率的な実装を提供することが推奨されています。

グループのスケーラビリティーを改善する目的で、レルムを削除するときにグループがデータベースから直接削除されるようになりました。その結果、レルムを削除するときに、GroupRemovedEvent などのグループ関連のイベントは発生しなくなりました。

レルムが削除されたときにグループ関連のイベントを処理するエクステンションがある場合は、レルムとそのグループが削除されたときにクリーンアップまたはカスタム処理を実行する代わりに、RealmRemovedEvent を使用するようにしてください。

GroupProvider インターフェイスも新しい preRemove(RealmModel) メソッドで更新され、レルムが削除されたときに実装がグループの削除を適切に処理するように強制します。

REFRESH_TOKEN イベントの userId は、リフレッシュトークンの sub クレームではなく、常にユーザーセッションから取得されるようになりました。REFRESH_TOKEN_ERROR イベントの userId は常に null になります。この変更の理由は、オプションの sub クレームが導入されると、リフレッシュトークンの sub クレームの値が null になる可能性があり、pairwise subject identifier を使用したり、sub クレームをオーバーライドする他の方法を使用したりすると、実際のユーザー ID と異なる場合もあるためです。

ただし、REFRESH_TOKEN_ERROR イベントで userId が見つからない場合にユーザーに関する情報を取得できるように、下位互換性として refresh_token_sub の詳細が追加されました。

Keycloak JS ライブラリーは、Red Hat build of Keycloak サーバーから静的に提供されなくなりました。つまり、次の URL は利用できなくなります。

さらに、これらの URL のライブラリーにリンクされていた keycloakJsUrl プロパティーは、管理コンソールのテーマから削除されました。カスタムテーマでこのプロパティーを使用してライブラリーを組み込んでいた場合は、別の方法を使用してライブラリーを組み込むようにテーマを更新する必要があります。

ここで、NPM などのパッケージマネージャーを使用して、ライブラリーをプロジェクトに含める必要があります。このライブラリーは、NPM レジストリーで keycloak-js として入手できます。これは、以下のコマンドを使用してインストールできます。

npm install keycloak-js

npm install keycloak-js

または、サーバーのディストリビューションには、keycloak-js-26.0.0.tgz アーカイブ内のライブラリーのコピーが含まれています。そこからライブラリーをプロジェクトにコピーできます。ビルドせずにブラウザーで直接ライブラリーを使用している場合は、自分でライブラリーをホストする必要があります。将来的にライブラリーの更新が容易になるため、プロジェクトにライブラリーを含めるにはパッケージマネージャーを使用することを推奨します。

以前は、設定を渡さずに Keycloak インスタンスを構築することができました。続いてその設定は、含まれている keycloak.js スクリプトのパスに基づき、サーバーから keycloak.json ファイルとして自動的にロードされます。ライブラリーがサーバーから静的に提供されなくなったため、この機能は削除されました。Keycloak インスタンスを構築するときに、設定を明示的に渡す必要があります。

// Before
const keycloak = new Keycloak();

// After
const keycloak = new Keycloak({
    url: "http://keycloak-server",
    realm: "my-realm",
    clientId: "my-app"
});

// Alternatively, you can pass a URL to a `keycloak.json` file.
// Note this is not reccomended as it creates additional network requests, and is prone to change in the future.
const keycloak = new Keycloak('http://keycloak-server/path/to/keycloak.json');

// Before
const keycloak = new Keycloak();

// After
const keycloak = new Keycloak({
    url: "http://keycloak-server",
    realm: "my-realm",
    clientId: "my-app"
});

// Alternatively, you can pass a URL to a `keycloak.json` file.
// Note this is not reccomended as it creates additional network requests, and is prone to change in the future.
const keycloak = new Keycloak('http://keycloak-server/path/to/keycloak.json');

Keycloak JS は、Web Crypto API を使用して、PKCE をサポートするために必要な SHA-256 ダイジェストを計算するようになりました。この API の非同期性により、次のパブリックメソッドは常に Promise を返すようになりました。

これらのメソッドを await とするようにコードを更新してください。

// Before
keycloak.login();
const loginUrl = keycloak.createLoginUrl();
const registerUrl = keycloak.createRegisterUrl();

// After
await keycloak.login();
const loginUrl = await keycloak.createLoginUrl();
const registerUrl = await keycloak.createRegisterUrl();

// Before
keycloak.login();
const loginUrl = keycloak.createLoginUrl();
const registerUrl = keycloak.createRegisterUrl();

// After
await keycloak.login();
const loginUrl = await keycloak.createLoginUrl();
const registerUrl = await keycloak.createRegisterUrl();

これらのメソッドを await とするようにコードを更新してください。

提供されたビルド時のオプションが、前回の最適化された Red Hat build of Keycloak のビルド時にサーバーイメージに保存された値と異なる場合、Red Hat build of Keycloak は起動に失敗するようになりました。以前は、このような場合には警告メッセージが表示されていました。

basic という名前の新しいクライアントスコープが、レルムの "デフォルト" クライアントスコープとして追加され、新しく作成されたすべてのクライアントに追加されます。移行中に、クライアントスコープも既存のすべてのクライアントに自動的に追加されます。

このスコープには、次のクレームに対して事前設定されたプロトコルマッパーが含まれています。

これにより、軽量アクセストークン内のクレームの数を減らすための追加の支援が提供されるだけでなく、常に自動的に追加されるクレームを設定する機会も提供されます。

多数のアイデンティティープロバイダーが存在する場合のレルムと組織のスケーラビリティーに関する改善の一環として、レルム表現にはアイデンティティープロバイダーのリストが保持されなくなりました。ただし、レルムをエクスポートするときには、レルム表現から引き続き使用できます。

レルム内のアイデンティティープロバイダーのクエリーを取得するには、/realms/{realm}/identity-provider/instances エンドポイントを使用することを推奨します。このエンドポイントはフィルターとページネーションをサポートしています。

組織に関連付けられた IDP を取得し、ログインに使用できる IDP (enabled であり、link_only ではなく、hide_on_login としてマークされていないもの) を取得するクエリーのパフォーマンスを向上させるために、IDENTITY_PROVIDER テーブルに新しいインデックスが追加されました。

テーブルに現在 300,000 を超えるエントリーが含まれている場合、Red Hat build of Keycloak は、自動スキーマ移行中にデフォルトでインデックスの作成をスキップし、代わりに移行中にコンソールに SQL ステートメントを記録します。この場合、Red Hat build of Keycloak の起動後に、DB でステートメントを手動で実行する必要があります。

また、プロバイダーを検索するときにクエリーをより効率的に実行できるように、kc.org および hideOnLoginPage 設定属性がアイデンティティープロバイダー自体に移行されました。そのため、API クライアントは、IdentityProviderRepresentation の getOrganizationId/setOrganizationId メソッドおよび isHideOnLogin/setHideOnLogin メソッドを使用し、現在非推奨となっている従来の設定属性を使用してこれらのプロパティーを設定しないようにする必要があります。

Argon2 は現在、非 FIPS 環境での Red Hat build of Keycloak で使用されるデフォルトのパスワードハッシュアルゴリズムです。

Argon2 は 2015 年のパスワードハッシュコンテスト で優勝し、OWASP によって推奨されるハッシュアルゴリズムです。

Red Hat build of Keycloak 24 では、PBKDF2 のデフォルトのハッシュイテレーションが 27.5K から 210K に増加し、パスワードハッシュの生成に必要な CPU 時間が 10 倍以上増加しました。Argon2 を使用すると、以前のリリースの Red Hat build of Keycloak とほぼ同じ CPU 時間で、より優れたセキュリティーを実現できます。1 つの欠点として、Argon2 ではメモリーがより多く必要になりますが、これは GPU 攻撃に耐えるためには必要です。Red Hat build of Keycloak の Argon2 のデフォルトでは、ハッシュ要求ごとに 7MB が必要です。

メモリーと CPU の過剰な使用を防ぐため、デフォルトでは、Argon2 によるハッシュの並列計算において、JVM で利用可能なコア数が上限となっています。Argon2 のメモリー集約型の性質をサポートするために、ヒープの使用率を向上させるために、デフォルトの GC を ParallelGC から G1GC に更新しました。

Argon2 は FIPS 140-2 に準拠していないことに注意してください。したがって、FIPS 環境の場合、デフォルトのアルゴリズムは引き続き PBKDF2 になります。また、FIPS 以外の環境で使用しており、FIPS 環境に移行する予定がある場合は、最初にパスワードポリシーを pbkdf2-sha512 などの FIPS 準拠アルゴリズムに変更することを検討してください。そうしないと、ユーザーは FIPS 環境に切り替えた後にログインできなくなります。

http-pool-max-threads が設定されていない場合、デフォルトで 50 または 4 x (使用可能なプロセッサー数) のいずれか大きい方に設定されます。以前は、200 または 8 x (使用可能なプロセッサー数) のいずれか大きい方にデフォルト設定されていました。ほとんどの使用シナリオでは、タスクスレッドの数を減らすと、アクティブなスレッド間のコンテキスト切り替えが少なくなるため、パフォーマンスがわずかに向上します。

RESOURCE_SERVER_RESOURCE と RESOURCE_SERVER_PERM_TICKET テーブルに 100,000 を超えるエントリーがあり、ユーザーに 1,000 を超えるリソースへのアクセスが許可されている場合、これらのクエリーのパフォーマンスは低下しました。クエリーが簡素化され、requester 列と owner 列の新しいインデックスが導入されました。

新しいインデックスは両方とも RESOURCE_SERVER_PERM_TICKET テーブルに適用されます。テーブルに現在 300,000 を超えるエントリーが含まれている場合、Red Hat build of Keycloak は、自動スキーマ移行中にデフォルトでインデックスの作成をスキップし、代わりに移行中にコンソールに SQL ステートメントを記録します。この場合、Red Hat build of Keycloak の起動後に、DB でステートメントを手動で実行する必要があります。

AccessToken、IDToken、および JsonWebToken から非推奨のメソッドが削除された結果、有効期限値に関連するメソッド名との一貫性を保つために SingleUseObjectKeyModel も変更されました。

以前の getExpiration メソッドは非推奨となり、2038 年以降のオーバーフローを回避するために、新しく導入された getExp メソッドを使用することを推奨します。

攻撃者が多数のログイン試行を同時に実行した場合、ブルートフォース攻撃保護の設定で許可されている回数を超えてパスワードを推測できる可能性があります。これは、ブルートフォースプロテクターがユーザーをロックする前に、ブルートフォースチェックが実行されたことが原因です。この競合を防ぐために、ブルートフォースプロテクターは、同じサーバーで別のログインが進行中に発生するすべてのログイン試行を拒否するようになりました。

この機能を無効にしたい場合は、次のコマンドを使用します。

bin/kc.[sh|bat] start --spi-brute-force-protector-default-brute-force-detector-allow-concurrent-requests=true

bin/kc.[sh|bat] start --spi-brute-force-protector-default-brute-force-detector-allow-concurrent-requests=true

セキュリティー上の懸念から、渡されたリダイレクト URI に userinfo 部分が含まれている場合、またはその path が親ディレクトリー (/../) にアクセスする場合、リダイレクト URI 検証では正確な文字列マッチング (ワイルドカードは使用しない) が実行されるようになりました。

完全なワイルドカード * は、これらの特性を持つ http (s) URI の開発において有効なリダイレクトとして引き続き使用できます。実稼働環境では、そのタイプの URI に対してワイルドカードを必要としない正確で有効なリダイレクト URI を設定します。

ワイルドカードが有効なリダイレクト URI は実稼働環境では推奨されておらず、OAuth 2.0 仕様ではカバーされていないことに注意してください。

マーシャリングは、Java オブジェクトをバイトに変換し、Red Hat build of Keycloak サーバー間でネットワーク経由で送信するプロセスです。Red Hat build of Keycloak 26 では、マーシャリングライブラリーが JBoss Marshalling から Infinispan Protostream に変更されました。ライブラリーは相互に互換性がないため、セッションデータが失われないようにするにはいくつかの手順が必要です。

http-relative-path プロパティーが指定されている場合、ユーザーは Red Hat build of Keycloak がホストされているパスに自動的にリダイレクトされます。つまり、相対パスが /auth に設定され、ユーザーが localhost:8080/ にアクセスすると、ページは localhost:8080/auth にリダイレクトされます。

http-management-relative-path または http-relative-path プロパティーが指定されている場合、同じ変更が管理インターフェイスに適用されます。この変更により、ユーザーエクスペリエンスが向上します。ユーザーは URL への相対パスを明示的に設定する必要がなくなりました。

org.keycloak.common.util.Encode は、file.encoding システムプロパティーに暗黙的に依存するのではなく、URL エンコードに常に UTF-8 charset を使用するようになりました。

このリリースでは、LDAP 接続プールの設定はシステムプロパティーのみに依存します。主な理由は、LDAP 接続プールの設定が、個々のレルムまたは LDAP プロバイダーインスタンスに固有のものではなく、JVM レベルの設定であるためです。

以前のリリースと比較して、LDAP 接続プールに関連するすべてのレルム設定は無視されます。次のいずれかの設定が LDAP プロバイダーに設定されている以前のバージョンから移行する場合は、代わりにシステムプロパティーを使用することを検討してください。

詳細は、接続プールの設定 を参照してください。

このリリースでは、埋め込みキャッシュを使用する場合、取り消されたアクセストークンはデータベースに書き込まれ、クラスターが再起動されたときにデフォルトで再ロードされます。

この動作を無効にするには、すべてのプロバイダー設定 で説明されているように、SPI オプション spi-single-use-object-infinispan-persist-revoked-tokens を使用します。

SingleUseObjectProvider の SPI 動作が変更され、取り消されたトークンに対しては put メソッドと contains メソッドのみを使用する必要があります。これはデフォルトで強制され、SPI オプション spi-single-use-object-infinispan-persist-revoked-tokens を使用して無効にできます。

Red Hat build of Keycloak 26 では、推奨される高可用性マルチサイトアーキテクチャーが大幅に改善されました。主な改善点は次のとおりです。

上記の変更の結果として、既存の Red Hat build of Keycloak デプロイメントに次の変更が必要になります。

アプリケーションによって開始された必須アクションの実行からリダイレクトされるときに、必要なアクションプロバイダー名が kc_action パラメーターを介して返されるようになりました。これにより、クライアントに対して実行された必要なアクションの検出が容易になります。実行の結果は、kc_action_status パラメーターによって決定できます。

注意: この機能では Keycloak JS アダプターへの変更が必要でした。そのため、この機能を利用する場合は、アダプターを最新バージョンにアップグレードすることを推奨します。

Red Hat build of Keycloak は、ファイル拡張子に基づいてキーストアとトラストストアの形式を決定するようになりました。ファイル拡張子が .p12、.pkcs12、または .pfx の場合、形式は PKCS12 になります。ファイル拡張子が .jks、.keystore、または .truststore の場合、形式は JKS になります。ファイル拡張子が .pem、.crt、または .key の場合、形式は PEM になります。

https-key-store-type と https-trust-store-type を明示的に指定することで、自動検出をオーバーライドすることもできます。同じことが管理インターフェイスとその https-management-key-store-type にも当てはまります。FIPS 厳密モードの制限は変更されません。

keycloak テーマの common リソース、具体的にはサードパーティーライブラリーのリソースへのパスの一部が変更されました。それに応じてカスタムテーマを更新してください。

さらに、次のリソースが common テーマから削除されました。

削除されたリソースを以前にテーマで使用していた場合は、代わりに独自のテーマリソースに追加してください。

当社の FIPS 140-2 インテグレーションは現在、BouncyCastle FIPS ライブラリーのバージョン 2 でテストされ、サポートされています。このバージョンは Java 21 で認定されています。FIPS 140-2 インテグレーションを使用する場合は、BouncyCastle FIPS ライブラリーを最新のドキュメントに記載されているバージョンにアップグレードすることを推奨します。

BouncyCastle FIPS バージョン 2 は、FIPS 140-3 認定を受けています。したがって、Red Hat build of Keycloak は、FIPS 140-3 準拠システムで使用される限り、FIPS 140-3 に準拠できます。これは、FIPS 140-3 に準拠している RHEL 9 ベースのシステムである可能性があります。ただし、RHEL 8 ベースのシステムは FIPS 140-2 のみ認定されていることに注意してください。

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

たとえば、数百万件のレコードを含むテーブルにインデックスを作成すると、時間がかかり、サービスの大きな中断を引き起こす可能性があります。したがって、自動移行には 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=300000

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

kc.[sh|bat] start --spi-connections-jpa-quarkus-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>

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

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

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