アップグレードガイド

互換性を損なう変更とは、既存のユーザーが構成を変更する必要がある変更として識別されます。

一般的な構成ミスを防ぎ、バグを修正し、Keycloakの実行を簡素化するために内部動作が変更された注目すべき変更。

一般的な構成ミスを防ぎ、バグを修正し、Keycloakの実行を簡素化するために内部動作が変更された注目すべき変更。

互換性を損なう変更とは、既存のユーザーが構成を変更する必要がある変更として識別されます。

このリリースには、パブリック API またはドキュメント化された動作に対する破壊的な変更はありません。

一般的な構成ミスを防ぎ、バグを修正し、Keycloakの実行を簡素化するために内部動作が変更された注目すべき変更。

これは、このリリースでは以前と同様に動作し続けるが、将来のメジャーリリースで削除される機能をリストしています。

REALM_FILESEPARATOR_KEY キーリゾルバーを使用している場合、Keycloak は FileVault シークレットへのアクセスをレルムの外部に制限するようになりました。管理コンソールで式プレースホルダーを指定する際にパス トラバーサルを引き起こす可能性のある文字は、禁止されるようになりました。

さらに、KEY_ONLY キーリゾルバーは、REALM_UNDERSCORE_KEY リゾルバーが使用されている場合に、別のレルムにリンクされるはずのシークレットの読み取りを防ぐために _ 文字をエスケープするようになりました。エスケープは単に _ を __ に置き換えるため、たとえば、${vault.my_secret} は my__secret という名前のファイルを検索するようになりました。これは破壊的な変更であることを認識しています。したがって、移行を容易にするために警告がログに記録されます。

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

ユーザーセッションの損失を防ぐために、まず Keycloak 25 にアップグレードし、Keycloak 25 の移行ガイドで概説されているように、永続セッション機能を有効にしてください。

Operator は、hostname v1 設定の proxy=passthrough をデフォルトとしなくなります。これにより、固定エッジ ホスト名に hostname v2 を使用するデプロイメントは、追加のオプションなしで意図したとおりに動作できます。

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

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

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

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

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

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

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

http-management-relative-path または http-relative-path プロパティが指定されている場合、管理インターフェイスにも同じことが当てはまります。

ユーザーは URL に相対パスを明示的に設定する必要がなくなるため、ユーザーエクスペリエンスが向上します。

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

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

次の項目は、今後の Keycloak バージョンで削除するために非推奨となり、代替はありません

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

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

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

詳細については、接続プールの構成 を参照してください。

このリリースでは、base/login および keycloak.v2/login テーマのログインページにカスタムフッターを簡単に追加する機能が導入されました。カスタムフッターを使用するには、目的のコンテンツを含む footer.ftl ファイルをカスタムログインテーマに作成します。

詳細については、ログインテーマへのカスタムフッターの追加 を参照してください。

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

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

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

Keycloak 26 では、推奨される HA マルチサイトアーキテクチャに大幅な改善が加えられました。最も注目すべきは次のとおりです

上記の変更の結果として、既存の Keycloak デプロイメントには次の変更が必要です。

シングルサイトセットアップで外部 Infinispan を使用している場合、これは以前のバージョンの Keycloak ではサポートされておらず、Keycloak 26 でもサポートされていません。Keycloak のキャッシュ XML または CLI オプションでの手動構成による偶発的な使用からユーザーを保護するために、これは現在フィーチャーフラグ cache-embedded-remote-store で保護されています。これは実験的としてマークされており、したがってサポートされていません。Keycloak 26 は、このような構成では起動せず、この実験的機能が有効になっていない限り、代わりにエラーを表示します。

再起動とアップグレードの間でユーザーをログイン状態に保つために外部 Infinispan を使用していた場合は、代わりにデフォルトで有効になっている persistent-user-sessions 機能を使用してください。その後、外部 Infinispan は不要になります。

実験的機能 cache-embedded-remote-store は、将来のマイナーリリースで削除されます。

すべての管理者ユーザーがロックアウトされた場合、Keycloak インスタンスへのアクセスを回復するのは困難でした。このプロセスには、データベースへの直接アクセスや手動による変更など、複数の高度な手順が必要でした。ユーザーエクスペリエンスを向上させるために、Keycloak は新しい管理者アカウントをブートストラップするための複数の方法を提供するようになり、このような状況からの回復に使用できます。

その結果、環境変数 KEYCLOAK_ADMIN および KEYCLOAK_ADMIN_PASSWORD は非推奨になりました。代わりに KC_BOOTSTRAP_ADMIN_USERNAME および KC_BOOTSTRAP_ADMIN_PASSWORD を使用する必要があります。これらは一般的なオプションでもあるため、CLI またはその他の構成ソース (たとえば --bootstrap-admin-username=admin) を介して指定できます。詳細については、新しい 管理者ブートストラップとリカバリ ガイドを参照してください。

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

注: この機能には Keycloak JS アダプターの変更が必要だったため、この機能を活用する場合は、アダプターの最新バージョンにアップグレードすることをお勧めします。

クラス UserSessionCrossDCManager は非推奨であり、Keycloak の将来のバージョンで削除される予定です。使用する代替メソッドについては、UserSessionCrossDCManager Javadoc を参照してください。

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

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

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

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

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

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 厳密モードの制限は変更されていません。

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

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

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

GELF サポートはしばらくの間非推奨となっていましたが、このリリースで Keycloak から完全に削除されました。他のログハンドラーは利用可能であり、GELF の代替として使用することが完全にサポートされています (Syslog など)。詳細については、ロギングガイド を参照してください。

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

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

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

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

非推奨となった hostname v1 機能は削除されました。この機能は Keycloak 25 で非推奨となり、hostname v2 に置き換えられました。この機能をまだ使用している場合は、hostname v2 に移行する必要があります。詳細については、ホスト名の設定 (v2) および 初期移行ガイド を参照してください。

非推奨となった proxy オプションは削除されました。このオプションは Keycloak 24 で非推奨となり、必要に応じてホスト名オプションと組み合わせて proxy-headers オプションに置き換えられました。詳細については、リバースプロキシの使用 および 初期アップグレードガイド を参照してください。

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

カスタムの組み込み Infinispan キャッシュ設定ファイルを、以下のキャッシュ sessions、clientSessions、offlineSessions、および offlineClientSessions の設定例と同様に更新してください。

詳細については、分散キャッシュの設定 ガイドに進んでください。

以前のバージョンの Keycloak では、ユーザーおよびクライアントセッションのアイドル時間に 2 分間の猶予期間が追加されていました。これは、セッション更新時間がクラスター内で非同期的にレプリケートされる以前のアーキテクチャによるものでした。永続ユーザーセッションでは、これはもはや不要となり、そのため猶予期間は削除されました。

以前の動作を維持するには、レルム構成を更新し、セッションおよびクライアントのアイドル時間を 2 分間延長してください。

以前のバージョンの Keycloak では、http(s)://example-host/auth/realms/my-realm-name/protocol/openid-connect/logout?redirect_uri=encodedRedirectUri のようなログアウトエンドポイント URL を開くことで、ユーザーの自動ログアウトとアプリケーションへのリダイレクトがサポートされていました。この機能は Keycloak 18 で非推奨となり、今回のバージョンで OpenID Connect 仕様に従うことを優先して削除されました。

この変更の一環として、SPI の以下の関連する構成オプションが削除されました。

これらのオプションまたはログアウト用の redirect_uri パラメータをまだ使用している場合は、代わりに OpenID Connect RP-Initiated Logout 仕様 を実装する必要があります。

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

org.keycloak.bom:keycloak-adapter-bom および org.keycloak.bom:keycloak-misc-bom BOM ファイルが削除されました。アダプター BOM は、ほとんどの Java アダプターが削除されたため、もはや有用ではありませんでした。misc BOM には 1 つのアーティファクト、keycloak-test-helper のみが含まれていましたが、そのアーティファクトも今回のリリースで削除されました。

maven アーティファクト org.keycloak:keycloak-test-helper が今回のリリースで削除されました。このアーティファクトは、Java 管理クライアントを扱うためのいくつかのヘルパーメソッドを提供していました。ヘルパーメソッドを使用している場合は、必要に応じてアプリケーションにフォークすることが可能です。

JEE admin-client が今回のリリースで削除されました。Jakarta admin-client のサポートは引き続き継続します。

資格情報の更新 (UPDATE_CREDENTIAL) および削除 (REMOVE_CREDENTIAL) のための汎用イベントが追加されました。資格情報のタイプは、イベントの credential_type 属性で記述されています。新しいイベントタイプは、Email Event Listener でサポートされています。

以下のイベントタイプは非推奨となり、将来のバージョンで削除される予定です: UPDATE_PASSWORD、UPDATE_PASSWORD_ERROR、UPDATE_TOTP、UPDATE_TOTP_ERROR、REMOVE_TOTP、REMOVE_TOTP_ERROR

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

FIPS 140-2 統合は、バージョン 2 の BouncyCastle FIPS ライブラリでテストされ、サポートされるようになりました。このバージョンは Java 21 で認証されています。FIPS 140-2 統合を使用する場合は、最新のドキュメントに記載されているバージョンに BouncyCastle FIPS ライブラリをアップグレードすることをお勧めします。

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

groups.setOrCreateChild() メソッドが JavaScript ベースの Admin Client から削除されました。このメソッドをまだ使用している場合は、代わりに createChildGroup() または updateChildGroup() メソッドを使用してください。

今回のリリースには、考慮すべき Keycloak JS ライブラリへのいくつかの変更が含まれています。これらの変更の主な動機は、ライブラリを Keycloak サーバーから分離し、独立してリファクタリングできるようにすることで、コードを簡素化し、将来のメンテナンスを容易にすることです。変更点は以下のとおりです。

起動時に指定されたビルド時オプションが、最後の最適化された Keycloak ビルド中にサーバーイメージに永続化された値と異なる場合、Keycloak は起動に失敗するようになりました。以前は、そのような場合に警告メッセージが表示されていました。

機能バージョンにより、機能 account3、admin2、および login2 の名前が変更されました。機能を無効にする場合、バージョンを使用する必要はありません。たとえば、管理コンソールは --features-disabled=admin で無効になります。

login の特定のバージョンを使用するには、--features=login:v1 を使用します。

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

何らかの理由で、新機能を無効にしたい場合は、起動ファクトリオプションがあります。

クライアントスコープまたはレルム全体が削除されると、関連付けられたユーザー同意も削除する必要があります。テーブル USER_CONSENT_CLIENT_SCOPE に新しいインデックスが追加され、パフォーマンスが向上しました。

テーブルに 300,000 件を超えるエントリが含まれている場合、デフォルトでは Keycloak は自動スキーマ移行中にインデックスの作成をスキップし、代わりに SQL ステートメントをコンソールに記録することに注意してください。ステートメントは、Keycloak の起動後に DB で手動で実行する必要があります。異なる制限を構成する方法の詳細については、アップグレードガイド を確認してください。

古いホスト名オプションは非推奨となり、今後のリリースで削除される予定であるため、hostname v2 オプションがデフォルトでサポートされています。新しいオプションはデフォルトで有効になっているため、Keycloak は古いオプションを認識しません。

必要な移行のリスト

ご覧のとおり、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 オプションは削除されました。

以前のバージョンの Keycloak では、オフラインユーザーセッションとオフラインクライアントセッションのみがデータベースに保存されていました。新機能 persistent-user-sessions は、オンラインユーザーセッションとオンラインクライアントセッションをメモリだけでなくデータベースにも保存します。これにより、Keycloak のすべてのインスタンスが再起動またはアップグレードされた場合でも、ユーザーはログイン状態を維持できます。

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

Keycloak によって提供されるメトリクスには、http_server で始まる HTTP サーバーメトリクスが含まれるようになりました。いくつかの例を以下に示します。

新しいオプション http-metrics-histograms-enabled および http-metrics-slos を使用して、デフォルトのヒストグラムバケットまたはサービスレベル目標 (SLO) の特定のバケットを有効にします。ヒストグラムの使用方法については、Prometheus ドキュメントのヒストグラムに関するドキュメント を参照して、http_server_requests_seconds_bucket で提供される追加のメトリクスシリーズを使用する方法を確認してください。

Keycloak 24 リリースでは、CPU 使用率の増加につながるパスワードハッシュアルゴリズムの変更がありました。それに対処するために、FIPS 以外の環境では異なるデフォルトのハッシュアルゴリズム Argon2 を選択しました。これにより、CPU 使用率が Keycloak 24 リリース前のレベルに戻ります。

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

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

spi-truststore-file-hostname-verification-policy および新しい tls-hostname-verifier オプションのデフォルトは、WILDCARD ではなく DEFAULT になりました。WILDCARD および STRICT オプション値は非推奨になりました。代わりに DEFAULT に依存する必要があります。

WILDCARD でサポートされており、DEFAULT でサポートされていない動作: * サブドメイン名 (例: *.foo.com) のワイルドカードが、複数レベル (例: a.b.foo.com) を含むすべてに一致することを許可します。* 既知のパブリックサフィックスとの一致を許可します - 例: foo.co.gl は *.co.gl と一致する可能性があります。

STRICT でサポートされており、DEFAULT でサポートされていない動作: * STRICT は、ワイルドカードが一致するかどうかを判断する際に、2 文字のトップレベル (*.XXX.YY) で終わる 2 文字または 3 文字のドメイン名の小さな除外リストを使用します。代わりに DEFAULT は、https://publicsuffix.org/list/ からのパブリックサフィックスルールと除外のより完全なリストを使用します。

WILDCARD または STRICT オプションからのこれらの動作に依存することは想定されていません。

Keycloak は、認証セッションが期限切れになり、ユーザーがすでにログインしている場合、「すでにログインしています」というメッセージをエンドユーザーに表示しなくなりました。代わりに、期限切れの認証セッションに関するエラーをクライアントアプリケーションにリダイレクトするため、クライアントは サーバー管理ガイドの認証セッションの章 で説明されているように、それに対してアクションを実行し、認証を再開できます。アプリケーションを更新してこのエラーを処理できるようにすることを検討してください。

モジュール org.keycloak:keycloak-model-legacy モジュールは以前のリリースで非推奨となり、今回のリリースで削除されました。代わりに org.keycloak:keycloak-model-storage モジュールを使用してください。

以前のリリースで非推奨となった、起動時にオフラインセッションをプリロードする古い動作が削除されました。

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

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

ユーザー属性でユーザーを検索する際、Keycloak はユーザー属性名を検索する際に小文字比較を強制しなくなりました。これは、ユーザー属性テーブルに対する Keycloak ネイティブインデックスが検索時に使用されるようになることを意味します。検索を高速化するために `lower(name)` に基づいて独自のインデックスを作成している場合は、削除できます。

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

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

これにより、軽量アクセストークン内のクレーム数を減らすための追加のヘルプが提供されますが、常に自動的に追加されていたクレームを設定する機会も得られます。

sid クレームと同じ値を含む session_state クレームは、OpenID Connect Front-Channel Logout および OpenID Connect Back-Channel Logout 仕様に従って不要になったため、すべてのトークンから削除されました。session_state クレームは、OpenID Connect Session Management 仕様に従って、アクセストークンレスポンスに残ります。

setSessionState() メソッドも IDToken クラスから削除され、setSessionId() メソッドに置き換えられ、getSessionState() メソッドは非推奨になったことに注意してください。

新しい Session State (session_state) マッパーも含まれており、クライアントスコープ (たとえば basic クライアントスコープ) に割り当てて、古い動作に戻すことができます。

古いバージョンの JS アダプターを使用している場合は、上記のクライアントスコープを使用することにより、Session State (session_state) マッパーも使用する必要があります。

常にアクセストークンに追加されていた sub クレームが、デフォルトで追加されるようになりましたが、新しい Subject (sub) プロトコルマッパーを使用しています。

Subject (sub) マッパーは、basic クライアントスコープでデフォルトで設定されています。したがって、このバージョンにアップグレードした後、追加の設定は必要ありません。

アクセストークンの sub クレームをマッピングするために Pairwise subject identifier マッパーを使用している場合は、Subject (sub) マッパーを無効にするか削除することを検討できます。ただし、Subject (sub) プロトコルマッパーが Pairwise subject identifier マッパーの前に実行されるため、厳密には必要ありません。したがって、pairwise 値は Subject (sub) マッパーによって追加された値をオーバーライドします。これは、sub クレームをオーバーライドする他のカスタムプロトコルマッパーの実装にも適用される可能性があります。Subject (sub) マッパーは現在、最初のプロトコルマッパーとして実行されるためです。

Subject (sub) マッパーを使用して、アクセストークン、軽量アクセストークン、およびイントロスペクションレスポンスに対してのみ sub クレームを設定できます。IDToken および Userinfo には常に sub クレームが含まれています。

マッパーはサービスアカウントには影響しません。ユーザーセッションが存在せず、sub クレームは常にアクセストークンに追加されるためです。

nonce クレームは、OpenID Connect Core 1.0 仕様に厳密に従って、ID トークンにのみ追加されるようになりました。仕様で示されているように、クレームは、同じパラメータが認証リクエストで送信された場合、ID トークン内で必須です。仕様では、リフレッシュリクエスト後に nonce を追加しないことも推奨しています。以前は、クレームはすべてのレスポンス (リフレッシュを含む) のすべてのトークン (アクセス、リフレッシュ、ID) に設定されていました。

新しい Nonce backwards compatible マッパーもソフトウェアに含まれており、クライアントスコープに割り当てて古い動作に戻すことができます。たとえば、JS アダプターは、バージョン 24.0.0 の #26651 の問題を修正する前に、すべてのトークンで返された nonce クレームを確認していました。したがって、古いバージョンの JS アダプターを使用している場合は、クライアントスコープを使用して、必要なクライアントにマッパーを追加する必要があります。

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

ただし、refresh_token_sub の詳細は、REFRESH_TOKEN_ERROR イベントで userId が欠落している場合にユーザーに関する情報を持つための下位互換性として追加されました。

最新の Keycloak サーバーをアプリケーションで古いバージョンの JavaScript アダプターで使用する場合、以前のバージョンの JavaScript アダプターが Keycloak によって追加されたが、OIDC 仕様ではサポートされていないクレームに依存しているため、上記のトークンの変更の影響を受ける可能性があります。これには以下が含まれます。

プロトコルマッパーを、対応するクライアントに直接追加するか、古いバージョンの Keycloak Javascript adapter に依存するクライアントアプリケーションで使用できるクライアントスコープに追加できます。session_state および nonce クレーム専用の前のセクションで詳細を確認できます。

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

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

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

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

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

Keycloak は、グループパスのスラッシュをエスケープしたことがありません。そのため、top の子である group/slash という名前のグループは、完全パス /top/group/slash を使用しますが、これは明らかに誤解を招く可能性があります。このバージョン以降、サーバーは名前のスラッシュのエスケープを実行するために起動できます。

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

エスケープは現在デフォルトで無効になっています。これは動作の変更を表すためです。それにもかかわらず、エスケープを有効にすることをお勧めします。将来のバージョンではデフォルトになる可能性があります。

メソッド EnvironmentDependentProviderFactory.isSupported() は、いくつかのリリースで非推奨になり、現在削除されました。

代わりに、isSupported(Config.Scope config) を実装します。

バージョン 22.0.2 で、LinkedIn の OAuh 2.0 ソーシャルプロバイダーは、新しい OpenId Connect 実装に置き換えられました。レガシープロバイダーは非推奨になりましたが、一部の既存のレルムでまだ機能している場合に備えて、削除はされませんでした。Keycloak 25.0.0 では、古いプロバイダーとその関連する linkedin-oauth 機能が明確に削除されます。今後は、デフォルトの LinkedIn ソーシャルプロバイダーが唯一の利用可能なオプションになります。

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

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

異なる制限を構成する方法の詳細については、アップグレードガイドを参照してください。

次のメソッドが AccessToken クラスから削除されました。

次のメソッドが IDToken クラスから削除されました。

次のメソッドが JsonWebToken クラスから削除されました。

exp および nbf クレームはオプションであるため、トークンに設定されていないことも想定する必要があります。以前は、これらのクレームは 0 の値で設定されていましたが、その値は有効な NumericDate である必要があるため、意味がありません。

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

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

インターフェース org.keycloak.credential.hash.PasswordHashProvider のメソッド String encode(String rawPassword, int iterations) は非推奨になりました。このメソッドは、今後の Keycloak リリースのいずれかで削除されます。Keycloak 27 リリースになる可能性があります。

メソッド org.keycloak.common.util.CollectionUtil.intersection が削除されました。既存のコレクションで代わりに 'java.util.Collection.retainAll' を使用する必要があります。

org.keycloak.common.util.Resteasy は非推奨になりました。代わりに org.keycloak.util.KeycloakSessionUtil を使用して KeycloakSession を取得する必要があります。

カスタムプロバイダーを作成する場合以外は、他の手段で KeycloakSession を取得することは強くお勧めしません。

以前のバージョンでは、セッションがまだ有効かどうかを検証する際に、セッションの最大寿命とアイドルタイムアウトの計算がわずかに異なっていました。現在では、その検証はプロジェクトの残りの部分と同じコードを使用しています。

セッションが Remember Me 機能を使用している場合、アイドルタイムアウトと最大寿命は、共通 SSO と Remember Me 構成値の最大値になります。

Keycloak では、外部 Infinispan デプロイメントの場合、少なくとも 15.0.0 の Infinispan サーバーバージョンが必須になりました。外部 Infinispan デプロイメントは、HA ガイドで概説されているマルチサイトセットアップでサポートされています。

Oracle Database JDBC ドライバーは、Keycloak ディストリビューションに含まれなくなりました。Oracle DB を使用する場合は、特定の環境と互換性のあるバージョンの Oracle Driver を手動でインストールする必要があります。このプロセスの手順については、データベースの構成ガイドを参照してください。

次の変数は、管理テーマで非推奨になり、将来のバージョンで削除されます。

次の変数は、アカウントテーマで非推奨になり、将来のバージョンで削除されます。

インターフェース org.keycloak.models.AuthenticatedClientSessionModel のメソッド String getCurrentRefreshToken()、void setCurrentRefreshToken(String currentRefreshToken)、int getCurrentRefreshTokenUseCount()、および void setCurrentRefreshTokenUseCount(int currentRefreshTokenUseCount) は非推奨になりました。これらは、クライアントセッション内で複数のリフレッシュトークンを管理するために、getRefreshToken(String reuseId) などのパラメータとして識別子を必要とする同様のメソッドに置き換えられました。これらのメソッドは、今後の Keycloak リリースのいずれかで削除されます。Keycloak 27 リリースになる可能性があります。

管理者ユーザー API を介してユーザー属性を更新する場合、username、email、firstName、および lastName などのルート属性を含め、ユーザー属性を更新する際に部分的な更新を実行することはできません。

管理者が書き込み権限を持つすべての属性を渡さずに管理者ユーザー API を介してユーザー属性を更新する場合、欠落している属性は削除されます。一方、属性が管理者に対して読み取り専用としてマークされている場合、属性を送信しなくても削除されません。

ユーザープロファイル設定の詳細については、ユーザープロファイルドキュメントを参照してください。

レルム内の複数のユーザー ストレージ プロバイダーを適切にサポートするために、org.keycloak.userprofile.UserProfileDecorator インターフェースが変更されました。

decorateUserProfile メソッドは、ユーザープロファイル構成を初めて解析 (およびキャッシュ) するときには呼び出されなくなりましたが、ユーザーがユーザープロファイルプロバイダーを介して管理されるたびに呼び出されるようになりました。その結果、メソッドのコントラクトが次のように変更されました。

以前のコントラクトおよび動作とは異なり、このメソッドは、ユーザーがロードされたユーザー ストレージ プロバイダーに対してのみ呼び出されます。

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

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

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

ユーザーの資格情報を削除するためのアカウント REST エンドポイントは非推奨になりました。このバージョン以降、アカウントコンソールはこのエンドポイントを使用しなくなりました。ユーザーがユーザーの資格情報を削除したい場合にアカウントコンソールによってトリガーされる、Delete Credential アプリケーション開始アクションに置き換えられました。

Keycloak 24.0.0 のリリースノートは、変更の予想されるパフォーマンスへの影響と、サイジングガイドの修正された説明で更新されました。

'welcome' テーマは、新しいレイアウトを使用するように更新され、PatternFly 3 ではなく PatternFly 5 を使用するようになりました。テーマを拡張している場合、または独自のテーマを提供している場合は、次のように更新する必要がある場合があります。

非推奨になったバージョン 2 のアカウントコンソールテーマを以前に拡張していた場合は、新しいバージョン 3 のアカウントコンソールテーマを使用するようにテーマを更新する必要があります。新しいバージョンのアカウントコンソールテーマには、カスタマイズ方法に関していくつかの変更が加えられています。クリーンな状態から始めるには、新しい カスタマイズクイックスタートに従うことができます。

カスタムテーマを移動するには、最初に parent を新しいテーマに変更します。

カスタム React コンポーネントがある場合は、相対パスを使用するのではなく、React を直接インポートします。

content.json を使用してテーマをカスタマイズしている場合、ファイルの構造にいくつかの変更があります。具体的には、

Keycloak JS を Keycloak サーバーから直接ロードしている場合、このセクションは安全に無視できます。Keycloak JS を NPM パッケージからロードし、Webpack、Vite などのバンドラーを使用している場合は、コードにいくつかの変更を加える必要がある場合があります。Keycloak JS パッケージは、package.json ファイルで exports フィールドを使用するようになりました。これは、インポートを変更する必要があるかもしれないことを意味します。

--features と --features-disabled の両方のリストに同じ機能を含めることはできなくなりました。機能は 1 つのリストにのみ表示される必要があります。

--features リストで docker などのバージョン管理されていない機能名を使用すると、最もサポートされている/最新の機能バージョンを有効にできます。リリース間でより予測可能な動作が必要な場合は、代わりに docker:v1 など、必要な特定のバージョンを参照してください。

spi-truststore-file-* オプションとトラストストア関連のオプション https-trust-store-* は非推奨になりました。したがって、トラストストアマテリアルの新しいデフォルトの場所である conf/truststores を使用するか、truststore-paths オプションを使用して目的のパスを指定してください。詳細については、関連する ガイド を参照してください。

tls-hostname-verifier プロパティは、spi-truststore-file-hostname-verification-policy プロパティの代わりに使用する必要があります。

変更の付随的な影響として、トラストストアプロバイダーは常にいくつかの証明書で構成されるようになりました（少なくともデフォルトの Java 信頼済み証明書が存在します）。この新しい動作は、Keycloak の他の部分に影響を与える可能性があります。

たとえば、webauthn 登録は、attestation conveyance が Direct バリデーションに構成されている場合に失敗する可能性があります。以前は、トラストストアプロバイダーが構成されていない場合、受信証明書は検証されませんでした。しかし、現在は常にこの検証が実行されます。ドングルから送信された証明書チェーンが Keycloak によって信頼されていないため、登録は invalid cert path エラーで失敗します。認証器の認証局は、attestation を正しく実行するためにトラストストアプロバイダーに存在する必要があります。

--proxy オプションは非推奨となり、将来のリリースで削除される予定です。次の表は、非推奨のオプションがサポートされているオプションにどのようにマッピングされるかを示しています。

Operator を使用する場合もプロキシヘッダーを設定できます

org.keycloak.representations.idm.UserRepresentation と org.keycloak.representations.account.UserRepresentation の両方の表現クラスが変更され、ルートユーザー属性（username、email、firstName、lastName、locale など）は、Admin および Account API に表現ペイロードをフェッチまたは送信するときに一貫した表現を持つようになりました。

username、email、firstName、lastName、および locale 属性は、新しい org.keycloak.representations.idm.AbstractUserRepresentation 基本クラスに移動されました。

また、getAttributes メソッドは主にカスタム属性のみを表すことを目的としているため、このメソッドによって返されるマップでルート属性を期待しないでください。このメソッドは、主に特定のユーザーのカスタム属性を更新またはフェッチするときにクライアントを対象としています。

ルート属性を含むすべての属性を解決するために、新しい getRawAttributes メソッドが追加され、結果のマップにはルート属性も含まれるようになりました。ただし、このメソッドは表現ペイロードからは利用できず、ユーザープロファイルを管理するときにサーバーで使用することを目的としています。

オプション https-client-auth は実行時オプションとして扱われていましたが、これは Quarkus ではサポートされていません。オプションは代わりにビルド時に処理する必要があります。

このリリース以降、Keycloak クラスターの最初のメンバーは、リモートセッションを並行ではなく順次ロードします。オフラインセッションのプリロードが有効になっている場合、それらも順次ロードされます。

以前のコードは、起動時にクラスター全体で高いリソース消費につながり、本番環境での分析が困難であり、ノードがロード中に再起動された場合に複雑な障害シナリオにつながる可能性がありました。したがって、順次セッションロードに変更されました。

オフラインセッションの場合、Keycloak のこのバージョンと以前のバージョンでのデフォルトは、オンデマンドでセッションをロードすることです。これは、多くのオフラインセッションがある場合に、それらを並行してプリロードしようとするよりも適切にスケールします。このデフォルト設定を使用するセットアップは、オフラインセッションのロード戦略の変更の影響を受けません。オフラインセッションのプリロードが有効になっているセットアップは、オフラインセッションのプリロードが無効になっているセットアップに移行する必要があります。

Keycloak のデフォルトの動作は、オフラインセッションをオンデマンドでロードすることです。起動時にそれらをプリロードする古い動作は非推奨になりました。これは、起動時にプリロードすると、セッション数の増加に伴って適切にスケールせず、Keycloak のメモリ使用量が増加するためです。古い動作は将来のリリースで削除される予定です。

非推奨であり、まだ削除されていない古い動作を再度有効にするには、次に示すようにフィーチャーフラグと SPI オプションを使用します。

UserSessionProvider の API は、メソッド getOfflineUserSessionByBrokerSessionId(RealmModel realm, String brokerSessionId) を非推奨にしました。このメソッドの代わりに、getOfflineUserSessionByBrokerUserIdStream(RealmModel, String brokerUserId) を使用して、最初にユーザーのセッションを取得し、必要に応じてブローカーセッション ID でフィルタリングします。

Keycloak の組み込みキャッシュのメトリクスを有効にすると、メトリクスはキャッシュマネージャーとキャッシュ名にラベルを使用するようになりました。

インストールで変更を元に戻すには、カスタム Infinispan XML 構成を使用し、次のように構成を変更します。

このリリース以降、Keycloak は以前は制限されていた 255 文字を超えるユーザー属性値の保存と検索をサポートします。

ユーザーが属性を更新できるセットアップ（アカウントコンソール経由など）では、バリデーションを追加してサービス拒否攻撃を防ぎます。管理外属性が許可されておらず、すべての編集可能な属性に入力長を制限するバリデーションがあることを確認してください。

管理外属性の場合、最大長は 2048 文字です。管理属性の場合、デフォルトの最大長は 2048 文字です。管理者は、タイプ length のバリデーターを追加することでこれを変更できます。

この変更により、テーブル USER_ATTRIBUTE および FED_USER_ATTRIBUTE に新しいインデックスが追加されます。これらのテーブルに 300000 を超えるエントリが含まれている場合、Keycloak は自動スキーマ移行中にデフォルトでインデックス作成をスキップし、代わりに移行中にコンソールに SQL ステートメントをログ出力して、Keycloak の起動後に手動で適用できるようにします。異なる制限を構成する方法の詳細については、アップグレードガイド を参照してください。

このリリースでは、API は executeActions.ftl の代わりに email-verification.ftl テンプレートを使用します。

この API を使用してユーザーがメールを検証する方法を変更するために executeActions.ftl テンプレートをカスタマイズした場合は、変更を新しいテンプレートに転送してください。

新しいパラメータ lifespan が導入され、デフォルトの有効期間値（12 時間）を上書きできるようになります。

以前の動作を優先する場合は、次のように execute-actions-email API を使用します。

バージョン 21 で導入された SAML 暗号化の互換モードは削除されました。システムプロパティ keycloak.saml.deprecated.encryption はサーバーによって管理されなくなりました。暗号化に古い署名キーをまだ使用していたクライアントは、新しい IDP 構成メタデータからそれを更新する必要があります。

このリリースでは、パスワードストレージに関する OWASP 推奨事項 に一致するように、パスワードハッシュのデフォルトを調整しました。

この変更の一環として、デフォルトのパスワードハッシュプロバイダーが pbkdf2-sha256 から pbkdf2-sha512 に変更されました。また、pbkdf2 ベースのパスワードハッシュアルゴリズムのデフォルトのハッシュ反復回数が次のように変更されました。

レルムが hashAlgorithm と hashIterations を使用してパスワードポリシーを明示的に構成していない場合、新しい構成は次回のパスワードベースのログイン時、またはユーザーパスワードが作成または更新されたときに有効になります。

Keycloak CR を介して参照される Secrets および ConfigMaps は、API サーバーを介して監視されるのではなく、変更についてポーリングされるようになりました。変更が検出されるまでに約 1 分かかる場合があります。

これは、これらのリソースでラベル操作を必要としないようにするためです。アップグレード後、operator.keycloak.org/component ラベルがまだ付いている Secret がある場合は、削除または無視される可能性があります。

Map Store の削除後、次の構成オプションの名前が変更されました。

Map Store の削除後、次のモジュールの名前が変更されました。

および org.keycloak:keycloak-model-legacy モジュールは非推奨となり、次のリリースで org.keycloak:keycloak-model-storage モジュールに置き換えられる予定です。

ブルートフォースプロテクターによってユーザーが一時的にロックアウトされた場合、新しいイベント USER_DISABLED_BY_TEMPORARY_LOCKOUT が発生するようになりました。新しいイベントは構造化された形式で情報を提供するため、ID KC-SERVICES0053 のログは削除されました。

成功イベントであるため、新しいイベントはデフォルトで DEBUG レベルでログ出力されます。すべての成功イベントのログレベルを変更するには、サーバー管理ガイドのイベントリスナーの章 で説明されているように、設定 spi-events-listener-jboss-logging-success-level を使用します。

カスタムアクションまたはカスタムログエントリをトリガーするには、サーバー開発者ガイド のイベントリスナー SPI で説明されているように、カスタムイベントリスナーを作成します。

高度な構成のために Operator によって使用されるプロパティキーが operator.keycloak から kc.operator.keycloak に変更されました。

Keycloak CR および KeycloakRealmImport CR で resources オプションが指定されていない場合、デフォルト値が使用されます。Keycloak デプロイメントおよびレルムインポートジョブのデフォルトの requests メモリは 1700MiB に設定され、limits メモリは 2GiB に設定されます。

Keycloak での Cookie 処理のリファクタリングの一環として、Cookie の設定方法にいくつかの変更があります。

カスタム拡張機能では、いくつかの変更が必要になる場合があります。

Keycloak が内部トークン（Keycloak 自体が消費する JWT、たとえばリフレッシュトークンやアクショントークン）に署名するために使用するアルゴリズムが、HS256 からより安全な HS512 に変更されました。新しいキープロバイダー hmac-generated-hs512 がレルムに追加されました。移行されたレルムでは、古い hmac-generated プロバイダーと古い HS256 キーが維持され、アップグレード前に発行されたトークンを引き続き検証することに注意してください。HS256 プロバイダーは、キーローテーションガイドライン に従って古いトークンがなくなったときに手動で削除できます。

JVM オプション -Xms および -Xmx は、コンテナ内で実行する場合は -XX:InitialRAMPercentage および -XX:MaxRAMPercentage に置き換えられました。静的な最大ヒープサイズ設定の代わりに、Keycloak は最大値をコンテナメモリの合計の 70% として指定します。

ヒープサイズはコンテナメモリの合計に基づいて動的に計算されるため、コンテナの メモリ制限を常に設定する 必要があります。

詳細については、コンテナでの Keycloak の実行 ガイドを参照してください。

基盤となるライブラリ の sunsetting により、GELF との統合を提供している Keycloak は、GELF ログハンドラーをすぐにサポートしなくなります。この機能は将来のリリースで削除される予定です。外部ログ管理が必要な場合は、ファイルログ解析の使用を検討してください。

issue #25078 のため、jboss-logging メッセージ値は引用符で囲まれ（デフォルトでは文字 "）、改行を防ぐためにサニタイズされるようになりました。プロバイダーには、新しい動作をカスタマイズできる 2 つの新しいオプション（spi-events-listener-jboss-logging-sanitize および spi-events-listener-jboss-logging-quotes）があります。たとえば、サニタイズと引用符の両方を避けるために、サーバーはこの方法で起動できます。

オプションの詳細については、すべてのプロバイダー構成ガイド を参照してください。

バージョン 23.0.0 では、Groups リソースに新しいエンドポイント getSubGroups ("children") が導入されました。ここでは、パラメータ briefRepresentation はサブグループの完全な表現の取得を意味していました。意味が変更され、簡易表現が返されるようになりました。

バージョン 1.8.0 では、クライアントの指定された有効なリダイレクトとリダイレクト URI を比較する際に、ホスト名とスキームの小文字化が導入されました。残念ながら、すべてのプロトコルで完全に機能したわけではなく、たとえば、ホストは http では小文字化されましたが、https では小文字化されませんでした。OAuth 2.0 Security Best Current Practice では、URI を完全一致文字列比較を使用して比較することを推奨しているため、Keycloak はこの推奨事項に従い、今後は有効なリダイレクトはホスト名とスキームに対しても完全一致で比較されます。

古い動作に依存しているレルムの場合、クライアントの有効なリダイレクト URI には、サーバーによって認識される必要がある各 URI の個別のエントリを含める必要があります。

クライアントを構成する際に、より多くの手順と冗長性が導入されますが、新しい動作により、パターンベースのチェックがセキュリティ問題の原因となることが多いため、より安全なデプロイメントが可能になります。これらの問題は、実装方法と構成方法が原因です。

以前のバージョンの Operator は、監視対象の Secrets を追跡するために Secret を作成していました。新しいバージョンの Operator は -secrets-store Secret を使用しなくなったため、削除してもかまいません。

23.0.0 または 23.0.1 を使用していて、Operator ログに "org.keycloak.operator.controllers.KeycloakAdminSecretDependentResource → java.lang.IllegalStateException: More than 1 secondary resource related to primary" が表示される場合は、-secrets-store Secret を削除するか、これが問題ではなくなった 23.0.2 にアップグレードしてください。

RFC 9207 OAuth 2.0 Authorization Server Issuer Identification 仕様では、安全な認証応答を実現するために、OAuth 2.0/OpenID Connect 認証応答にパラメータ iss を追加します。

過去のリリースでは、このパラメータはありませんでしたが、Keycloak は仕様で要求されているように、このパラメータをデフォルトで追加するようになりました。

ただし、一部の OpenID Connect / OAuth2 アダプター、特に古い Keycloak アダプターは、この新しいパラメータに問題がある可能性があります。

たとえば、パラメータはクライアントアプリケーションへの認証が成功した後、常にブラウザ URL に存在します。このような場合、認証応答への iss パラメータの追加を無効にすると役立つ場合があります。これは、古いアダプターとの互換性 で説明されているように、Keycloak 管理コンソールの特定のクライアントに対して、クライアントの詳細の OpenID Connect 互換モード セクションで実行できます。認証応答から Issuer を除外 する専用スイッチが存在し、これをオンにすると、認証応答に iss パラメータを追加しないようにすることができます。

JPA では、検索時にワイルドカード文字 % および _ が使用できますが、LDAP などの他のプロバイダーでは * のみ許可されています。* は LDAP では自然なワイルドカード文字であるため、すべての場所で機能しますが、JPA では検索文字列の先頭と末尾でのみ機能していました。今回のリリースから、唯一のワイルドカード文字は * となり、すべてのプロバイダーの検索文字列のすべての場所で一貫して機能します。JPA の % や _ など、特定のプロバイダーの特殊文字はすべてエスケープされます。"w*ord" のように引用符を追加した完全一致検索の場合、動作は以前のリリースと同じままです。

このリリースでは、Java 以降の標準メカニズムに従い、リソースバンドルファイルは UTF-8 でエンコードされていると見なすようになりました。

以前のバージョンの Keycloak では、# encoding: UTF-8 のようなコメントを最初の行に記述してエンコーディングを指定できましたが、これはサポートされなくなり、無視されます。

テーマのメッセージプロパティファイルは、UTF-8 エンコーディングで読み込まれるようになり、ISO-8859-1 エンコーディングへの自動フォールバックが追加されました。別のエンコーディングを使用している場合は、ファイルを UTF-8 に変換してください。

このリリースより前は、レルム (User Realm Role) とクライアント (User Client Role) の両方のプロトコルマッパーが、Multivalued 設定が無効になっている場合に、文字列化された JSON 配列をマッピングしていました。

ただし、Multivalued 設定は、クレームをリストとしてマッピングするか、無効になっている場合は、同じ値リストから単一の値のみをマッピングするかを示します。

このリリースでは、ロールおよびクライアントマッパーは、単一値 (Multivalued 無効) としてマークされている場合、ユーザーの有効なロールからの単一の値にマッピングするようになりました。

このバージョンでは、パスワード入力の表示/非表示を切り替えるトグルを導入します。

一般に、すべての <input type="password" name="password" /> は div 内にカプセル化されるようになりました。入力要素の後には、パスワード入力の表示/非表示を切り替えるボタンが続きます。

古いコード例

新しいコード例

OpenShift でイングレスを有効にして実行し、spec.ingress.classname が openshift-default に設定されている場合、Keycloak CR で spec.hostname.hostname を空のままにすることができます。オペレーターは、明示的なホストなしで OpenShift Route によって作成されるものと同様のデフォルトホスト名を CR の保存されたバージョンに割り当てます。つまり、ingress-namespace.appsDomain です。appsDomain が変更された場合、または何らかの理由で別のホスト名が必要になった場合は、Keycloak CR を更新してください。

auto-build CLI オプションは、長い間非推奨としてマークされていました。このリリースでは、完全に削除され、サポートされなくなりました。

start コマンドを実行すると、構成に基づいてサーバーが自動的にビルドされます。この動作を防止するには、--optimized フラグを設定します。

kc.sh は、パラメーターと環境変数 JAVA_OPTS_APPEND および JAVA_ADD_OPENS で追加のシェル eval を使用しなくなったため、二重エスケープ/引用符の使用を続けると、パラメーターが誤解されることになります。たとえば、代わりに

単一のエスケープを使用してください

この変更は、すべての引数の単一引用符付きの値を使用して kc.sh を呼び出すことができなくなることも意味します。たとえば、次のようには使用できなくなります。

代わりに個々の引数にする必要があります

同様に、代わりに

代わりに個々の引数にする必要があります

個々の引数の使用は、Dockerfile run コマンドでも必須です。

フォームアクション RegistrationProfile (認証フローの UI に Profile Validation として表示) がコードベースおよびすべての認証フローから削除されました。デフォルトでは、すべてのレルムの組み込み登録フローにありました。ユーザー属性の検証と、すべてのユーザー属性を含むユーザーの作成は、RegistrationUserCreation フォームアクションによって処理されるため、RegistrationProfile はもう必要ありません。独自のプロバイダーで RegistrationProfile クラスを使用した場合を除き、通常、この変更に関連して追加のアクションは必要ありません。

トップレベルグループを検索およびページングするための新しいメソッドが追加されました。このインターフェイスを実装する場合は、次のメソッドを実装する必要があります。

エンドポイント GET {keycloak server}/realms/{realm-name}/groups/{group_id}/children が、ページネーションをサポートする特定のグループのサブグループを取得する方法として追加されました。

RESTEasy Classic はもはや利用できないため、RESTEasy Classic に依存することはオプションではありません。SPI および org.jboss.resteasy.spi.* の一部である RESTEasy Classic および関連パッケージに依存しているコードには移行が必要です。

エンドポイント POST {keycloak server}/realms/{realm-name}/partial-export および管理コンソール内の対応するアクションには、view-realm の代わりに実行するための manage-realm 権限が必要になりました。このエンドポイントは、レルム構成を JSON ファイルにエクスポートし、新しい権限の方が適切です。エクスポートにレルムグループ/ロールとクライアントを含めるパラメーター exportGroupsAndRoles および exportClients は、引き続き同じ権限 (query-groups および view-clients) を管理します。

このリリース以降、Keycloak は EventEntity details 列の長い値をサポートします。したがって、イベント詳細長のトリミングオプション --spi-events-store-jpa-max-detail-length および --spi-events-store-jpa-max-field-length はサポートされなくなりました。

このリリースには、ユーザープロファイルをプレビューから正式にサポートされる機能に昇格させる作業に関連する多くの修正と更新が含まれています。UserProfileProvider インターフェイスに新しく追加されたメソッド boolean isEnabled(RealmModel realm) など、SPI には小さな変更があります。また、一部のユーザープロファイルクラスと一部のバリデーター関連クラス (ただし、組み込みバリデーター実装ではない) が keycloak-server-spi-private モジュールから keycloak-server-spi モジュールに移動されました。ただし、Java クラスのパッケージは同じままです。独自の UserProfileProvider 実装で組み込み実装をオーバーライドする場合など、一部の例外的なケースで影響を受ける可能性があります。ただし、UserProfileProvider はサポートされていない SPI であることに注意してください。

Map Store は、以前のリリースでは実験的な機能でした。このリリースから、削除され、ユーザーは引き続き現在の JPA ストアを使用する必要があります。

このリリース以降、--storage 関連の CLI オプションを使用することはできなくなりました。モジュール keycloak-model-map* は削除されました。

すべての翻訳は、管理コンソール用の 1 つのファイルに移動されました。独自の翻訳を作成した場合、または管理コンソールを拡張した場合は、それらをこの新しい形式に移行する必要があります。また、データベースに「オーバーライド」がある場合は、キーから名前空間を削除する必要があります。一部のキーは異なる名前空間でのみ同じですが、これはヘルプで最も顕著です。このような場合、キーに Help を後置しました。

必要に応じて、この node スクリプトを使用して移行を支援できます。すべての単一ファイルを新しいファイルにまとめ、マッピングの一部も処理します。

これを public/locale/<language> フォルダーの transform.mjs というファイルに保存し、次のように実行します。

下位互換性を考慮して、メールローカルパートの最大長を設定するための新しいパラメーター --spi-user-profile-declarative-user-profile-max-email-local-part-length が追加されました。デフォルト値は 64 です。使用例

[有効期限なし] オプションが、[詳細設定] クライアントタブのすべてのコンボから削除されました。このオプションは、さまざまな有効期間またはアイドルタイムアウトが無限ではなく、一般的なユーザーセッションまたはレルムの値によって制限されていたため、誤解を招くものでした。したがって、このオプションは削除され、残りの 2 つのオプション ([レルム設定から継承] (クライアントは一般的なレルムタイムアウトを使用) および [有効期限]) (値はクライアントに対してオーバーライドされます) が優先されます。内部的には、[有効期限なし] は -1 で表されていました。現在、その値は管理コンソールに警告付きで表示され、管理者によって直接設定することはできません。

ビジネスおよび雇用に特化したプラットフォーム向けに、**LinkedIn OpenID Connect** という新しいソーシャルアイデンティティプロバイダーが導入されました。LinkedIn は最近、開発者向けの新しい製品 Sign In with LinkedIn using OpenID Connect をリリースしました。この製品は、OpenID Connect を使用してメンバーを認証する新しい方法を提供しますが、デフォルトの **OpenID Connect v1.0** アイデンティティプロバイダーは現時点では機能しません。そのため、Keycloak はこの新しいアイデンティティプロバイダーを新しい製品の特定のソーシャルプロバイダーとして追加します。

OAuth に基づく古い LinkedIn の方法は、開発者ポータル から完全に削除されたようです。既存の LinkedIn ソーシャルプロバイダーが現在のアプリケーションでどのように機能しているかは不明です。Keycloak は、古いプロバイダーの名前を **LinkedIn (非推奨)** に変更して維持していますが、デフォルトで無効になっている **linkedin-oauth** という非推奨の機能にあります。将来のバージョンでは削除される予定です。必要に応じて、起動時に再度有効にしてください。

Keycloak は、コードベースを Java EE (Enterprise Edition) から後継の Jakarta EE に移行しました。これにより、Keycloak にさまざまな変更がもたらされます。

Jakarta EE 10 をサポートするために、すべての Jakarta EE 仕様をアップグレードしました。次に例を示します。

Jakarta EE 10 は、クラウドネイティブな Java アプリケーションを構築するための、最新化、簡素化、軽量化されたアプローチを提供します。このイニシアチブ内で提供される主な変更点は、名前空間を javax.* から jakarta.* に変更することです。javax.security、javax.net、javax.crypto など、JDK で直接提供される javax.* パッケージには適用されません。

カスタム拡張機能、プロバイダー、または JPA エンティティでこれらの変更の影響を受ける可能性があります。

Keycloak は、Quarkus Java フレームワークのバージョン 3 にアップグレードしました。Quarkus 3 は、Java 開発を推進し、最新テクノロジーで最先端のユーザーエクスペリエンスを提供するという伝統を受け継いでいます。全体的なパフォーマンスと効率を引き続き向上させています。

Quarkus 3 は Jakarta EE 10 をベースにしており、Keycloak と同じであるため、スムーズな相互運用性が実現します。さらに、Jakarta EE 10 Core Profile に準拠した Eclipse MicroProfile 6 が含まれています。Quarkus 3 のアップグレードの中心部分は、JPA 3.1 と Hibernate ORM 6 の組み込みサポートです。

Keycloak は、Hibernate ORM 6.2 へのアップグレードの恩恵を受けるようになりました。これには、パフォーマンスの向上、SQL の改善、最新の JDK サポート、および最新の RDBMS 機能のサポートが含まれています。パフォーマンスの向上は、主に JDBC、HQL 変換、および Criteria 変換に影響を与えます。

カスタムプロバイダーまたは JPA エンティティがある場合、これらの変更が影響を与える可能性があります。

Quarkus 移行ガイド または Hibernate リリースノート を参照して、詳細を確認することをお勧めします。

レガシー Promise API メソッドが Keycloak JS アダプターから削除されました。これは、アダプターから返された Promise で .success() および .error() を呼び出すことができなくなったことを意味します。代わりに、.then() や .catch() などの標準化された Promise メソッドを使用する必要があります。

以前のリリースでは、export および import コマンドを実行する前に、build コマンドを最初に実行する必要がありました。このリリース以降、export および import コマンドは、ビルド時の構成が変更された場合、Keycloak の自動再ビルドを実行します。

最初に build コマンドを実行する既存のスクリプトを移行する場合は、--optimized コマンドラインオプションを export および import コマンドに追加して移行し、Keycloak が自動的にイメージを再ビルドしないようにします。この --optimized オプションを追加しないと、Keycloak が再ビルドをトリガーしてデフォルト値に戻る可能性があり、エクスポートとインポートのためにデータベースに接続しても機能しなくなります。

次の例では、データベースパスワードなどのランタイムパラメーターが構成ファイルまたは環境変数を介して提供されることを前提としています。

以前のリリースでは、export および import コマンドでは、データベース URL などのランタイムパラメーターは構成ファイルまたは環境変数でのみ許可されていました。このリリース以降、これらのランタイムパラメーターはコマンドラインでも使用できるようになりました。サポートされているパラメーターについては、--help オプションを使用してください。

Jakarta EE へのアップグレード後、Keycloak 管理クライアントのアーティファクトの名前は、長期的な保守性を考慮して、より説明的な名前に変更されました。Jakarta EE と Java EE のサポートを備えた 2 つの個別の Keycloak 管理クライアントを引き続き提供します。

org.keycloak:keycloak-admin-client-jakarta アーティファクトのリリースを停止しました。Jakarta EE サポートを備えた Keycloak 管理クライアントのデフォルトは、org.keycloak:keycloak-admin-client (バージョン 22.0.0 以降) です。

Java EE サポートを備えた新しいアーティファクトは org.keycloak:keycloak-admin-client-jee です。

モード **passthrough** の Keycloak のプロキシ構成設定は、リクエスト内の HTTP 転送ヘッダーを解析しなくなりました。これは、プロキシがパススルーモードで HTTPS 接続を転送する場合、プロキシは HTTP ヘッダーを追加、削除、または更新できないためです。

クライアントのリクエストの HTTP ヘッダーを解析したいインストールでは、**edge** または **reencrypt** 設定を使用する必要があります。

詳細については、リバースプロキシの使用 を参照してください。

この変更は、レルムローカライズメッセージを使用している場合にのみ影響を与える可能性があります。

このバージョンまで、レルムローカライズメッセージを使用した場合、フォールバックメッセージの解決はテーマ間で一貫性がありませんでした。詳細については、次の 問題 を参照してください。

実装はすべてのテーマで統一されました。一般に、最も具体的な一致する言語タグのメッセージが最も優先順位が高くなります。レルムローカライズメッセージとテーマ i18n メッセージの両方がある場合、レルムローカライズメッセージの方が優先順位が高くなります。要約すると、メッセージの優先順位は次のとおりです (RL = レルムローカライズ、T = テーマ i18n ファイル): RL <variant> > T <variant> > RL <region> > T <region> > RL <language> > T <language> > RL en > T en。

おそらく、例でよりよく説明できます。バリアント de-CH-1996 がリクエストされ、バリアントのレルムローカライズメッセージがある場合、このメッセージが使用されます。そのようなレルムローカライズメッセージが存在しない場合、テーマ i18n ファイルでそのバリアントに対応するメッセージが検索されます。そのようなメッセージが存在しない場合、地域 (de-CH) のレルムローカライズメッセージが検索されます。そのようなレルムローカライズメッセージが存在しない場合、テーマ i18n ファイルでその地域のメッセージが検索されます。それでもメッセージが見つからない場合は、言語 (de) のレルムローカライズメッセージが検索されます。一致するレルムローカライズメッセージがない場合、テーマ i18n ファイルでその言語のメッセージが検索されます。最後のフォールバックとして、英語 (en) の翻訳が使用されます。最初に、英語のレルムローカライズが検索され、見つからない場合は、テーマ i18n ファイルで英語のメッセージが検索されます。

UserQueryProvider インターフェイスが 2 つに分割されました。1 つはユーザーのクエリ機能を提供する UserQueryMethodsProvider です。2 つ目は、特定のストレージ内のユーザー数をカウントする機能を提供する UserCountMethodsProvider です。

Keycloak は、カウントクエリを効率的に実行できるユーザー ストレージプロバイダーと、そうでないプロバイダーを区別できるようになりました。UserQueryProvider インターフェイスは引き続き存在し、両方の新しいインターフェイスを拡張します。したがって、UserQueryProvider の既存の実装では、同じメソッドを保持しているため、変更は必要ありません。

このリリース以降、Keycloak はフェデレーション LDAP データベースのクエリ時にページネーションメカニズムを使用します。ユーザーの検索は、ローカルデータベースの検索と一貫性がある必要があります。

このリリース以降、LDAPStorageProvider は UserQueryProvider ではなく、UserQueryMethodsProvider のみを実装します。

このリリース以降、次の Keycloak OpenID Connect アダプターに時間を費やすことはなくなります。

この動きは、ドキュメントとクイックスタートリポジトリにすでに反映されています。詳細については、次のリファレンスを参照してください。

上記の参照から代替案へのアプリケーションの移行を検討し始めることをお勧めします。これらのアダプターは、将来のリリースでは利用できなくなるはずです。

Keycloak JEE SAML アダプターは廃止され、このリリース以降、その開発に時間を費やすことはなくなります。

公式アダプターは Jakarta ベースになり、アプリケーションをこのテクノロジーに切り替えたらすぐに使用する必要があります。

この変更は、ドキュメントとクイックスタートリポジトリにすでに反映されています。詳細については、次のリファレンスを参照してください。

アプリケーションを Jakarta に移行できない場合は、「レガシー」SAML JEE アダプターを引き続き使用でき、サーバーの将来のリリースと統合することができます。ただし、JEE のサポートは提供されなくなったため、できるだけ早くアプリケーションをアップグレードすることを検討してください。

プレビュー機能 openshift-integration が Keycloak コードベースから削除され、個別の拡張機能に移動されました。これには、カスタムクライアントストレージプロバイダーや Openshift 統合用のトークンレビューエンドポイントなどの関連プロバイダーの移動が含まれます。

この機能を使用していた場合は、Keycloak サーバーの起動時に openshift-integration 機能を使用するのをやめ、代わりにカスタム拡張機能から JAR ファイルをデプロイする必要があります。Openshift 拡張機能 とその README ファイルの手順で、拡張機能を Keycloak サーバーにデプロイする方法を確認できます。

openshift-integration の削除により、Keycloak ディストリビューションからいくつかのサードパーティの依存関係を削除できます。これには、openshift-rest-client、okio-jvm、okhttp、commons-lang、commons-compress、jboss-dmr、および kotlin-stdlib が含まれます。これは、これらのライブラリのいずれかを Keycloak サーバーにデプロイされた独自のプロバイダーの依存関係として使用する場合、これらの jar ファイルも明示的に Keycloak ディストリビューションの providers ディレクトリにコピーする必要がある場合があることを意味します。

より優れたランタイムを提供し、基盤となるスタックを最大限に活用するために、javax.ws.rs.core.Context アノテーションを使用したコンテキストデータのすべてのインジェクションポイントが削除されました。パフォーマンスの向上は、リクエストライフサイクル中にプロキシインスタンスを複数回作成することをなくし、ランタイム時のリフレクションコードの量を大幅に削減することによって実現されます。

次の SPI のいずれかを拡張している場合

コンテキストデータを取得するために、カスタム JAX-RS (サブ) リソースを確認する必要があります。次のようにします。

現在のリクエストおよびレスポンスオブジェクトにアクセスする必要がある場合は、KeycloakSession から直接インスタンスを取得できるようになりました。

次のように置き換えられました。

JAX-RS リソースメソッドを呼び出すときに KeycloakSession インスタンスにアクセスできない場合は、次のように JAX-RS ランタイムからコンテキストデータを取得できます。

追加のコンテキストデータは、KeycloakContext インスタンスを介してランタイムから取得できます。

次の SPI を介してサーバーの REST API を拡張している場合

カスタムプロバイダーがパッケージ化されている JAR ファイルに空の META-INF/beans.xml を追加する必要があります。そうしないと、ランタイム時にサーバーによって認識されません。

RealmResourceSPI または AdminRealmResourceSpi を使用している場合、META-INF の下に beans.xml という空のファイルを追加するか、JAX-RS リソースクラスに jakarta.ws.rs.ext.Provider アノテーションを付けるかのいずれかを選択できます。

また、JAX-RS メソッドが、それぞれ @Consumes および @Produces アノテーションを付与することで、入出力に予期されるメディアタイプを宣言していることを確認する必要があります。

以前のバージョンの Keycloak では、プロバイダーとモデルのインターフェースは、特定のメソッドを非推奨とするクリーンアッププロセスを経ました。このリリースでは、これらのメソッドは削除され、さらにいくつかのメソッドが非推奨となりました。Keycloak 21 のこれらのメソッドの Javadoc には、対応する代替メソッドに関する情報が含まれていました。

複数の Keycloak CR を同じ名前空間に作成でき、オペレーターによって個別に管理されます。これを可能にするには、古いバージョンのオペレーターによって作成された StatefulSet を再作成する必要があります。これはオペレーターがアップグレードされると自動的に行われ、わずかなダウンタイムが発生します。

条件ステータスフィールドは、標準の Kubernetes 条件に準拠するために、ブール値から文字列に変更されました。CRD では一時的に任意の内容を受け入れるように表現されますが、実際には常に文字列になります。このフィールドの使用箇所をすべて更新して、true または false ではなく、"True"、"False"、または "Unknown" の値が予期されるようにしてください。

Keycloak は IPv4/IPv6 デュアルスタックをサポートしており、デフォルトで IPv4 および IPv6 アドレス経由でアクセスできます。以前のバージョンの Keycloak では、デフォルトのアプローチは IPv4 アドレスのみを使用することでした。

詳細については、IPv4 または IPv6 で Keycloak サーバーを構成する を参照してください。

以前のバージョンでは、Java 17 で Javascript プロバイダー（スクリプト認証、Javascript 認可ポリシー、または OIDC および SAML クライアントのスクリプトプロトコルマッパー）で Keycloak を使用する場合、javascript エンジンをディストリビューションにコピーする必要がありました。Nashorn javascript エンジンが Keycloak サーバーでデフォルトで利用できるようになったため、これは不要になりました。スクリプトプロバイダーをデプロイする場合、nashorn スクリプトエンジンとその依存関係を Keycloak ディストリビューションにコピーしないことをお勧めします。

サービスアカウントクライアント のデフォルトの クライアント ID マッパーが変更されました。トークンクレーム名 フィールドの値が clientId から client_id に変更されました。client_id クレームは OAuth2 仕様に準拠しています。

clientId userSession ノートは引き続き存在します。

歴史的に、Keycloak() 関数を直接呼び出すことで Keycloak JS アダプターのインスタンスを作成することが可能でした。

これを JavaScript 世界の最新の慣例に合わせるために、代わりに new 演算子 を使用してインスタンスを作成することが可能になりました。

関数スタイルのコンストラクターはしばらくの間非推奨となっていましたが、このバージョンから、使用時に非推奨メッセージを積極的にログに記録します。このスタイルのコンストラクターは将来のバージョンで削除される予定ですので、コードを移行して new 演算子を使用するようにしてください。

terms_and_conditions ユーザー属性は、21.0.0 で誤って大文字に変更されました。このバージョンでは、ユーザー属性は小文字に戻ります。属性の値は、利用規約ページに同意したときに設定されます。

カスタム拡張機能がこの属性に依存している場合は、コードを調整して、terms_and_conditions と TERMS_AND_CONDITIONS の両方の属性を確認する必要がある場合があります。

Keycloak は、Prometheus 形式でメトリクスをエクスポートするオプションのメトリクスエンドポイントを提供します。このリリースでは、このデータを提供する実装が SmallRye から Micrometer に切り替えられました。Micrometer は、Quarkus に推奨されるメトリクスライブラリ です。

この変更により、メトリクスは名前が変更されました。次の表にいくつかの例を示します。

アップグレードする前に、エンドポイントから返されるすべてのメトリクスを、変更前と変更後で確認し、ダッシュボードとアラートでの使用状況を更新することをお勧めします。

SAML アダプター、クライアント、およびアイデンティティプロバイダーで 署名アルゴリズム として構成できるアルゴリズム RSA_SHA1 および DSA_SHA1 は非推奨となりました。SHA256 または SHA512 に基づくより安全な代替手段を使用することをお勧めします。また、これらのアルゴリズムを使用した署名付き SAML ドキュメントまたはアサーションの署名検証は、Java 17 以降では機能しません。このアルゴリズムを使用しており、SAML ドキュメントを利用する相手が Java 17 以降で実行されている場合、署名検証は機能しません。

考えられる回避策は、$JAVA_HOME/conf/security/java.security ファイルのプロパティ jdk.xml.dsig.secureValidationPolicy で構成されている「許可されないアルゴリズム」のリストから、http://www.w3.org/2000/09/xmldsig#rsa-sha1 や http://www.w3.org/2000/09/xmldsig#dsa-sha1 などのアルゴリズムを削除することです。

このバージョンでは、Keycloak は署名目的で生成されたレルムキーを使用して暗号化されたアサーションの復号化を拒否します。この変更は、IDP から SP (Keycloak が SP として機能する) へのすべての暗号化通信が動作を停止することを意味します。

これを機能させるには 2 つの方法があります。

Keycloak 13 では UserLoginFailureProvider が導入され、UserSessionProvider からいくつかのメソッドがそこに移動されました。UserSessionProvider のメソッドは非推奨となり、削除されました。これらのメソッドの Javadoc には、対応する代替メソッドが含まれていました (Keycloak 20 リリースの Javadoc を参照)。

以前のバージョンで非推奨となった古い管理コンソールがついに削除されました。これは、古い管理コンソールを親テーマとして使用したり、古い管理コンソールからインポートしたりしていたカスタムテーマが動作しなくなることも意味します。古い管理コンソールを拡張することはもはや適用できず、そのようなテーマがデプロイされていると Keycloak で問題 (少なくともログに警告またはエラー) が発生する可能性があるため、そのようなテーマを一切デプロイしないことを強くお勧めします。

Keycloak コンテナイメージ は、セキュリティを強化するために変更されました。その結果、カスタマイズされたイメージで使用していた可能性のある curl やその他の CLI ツールが削除されました。この変更の処理方法については、更新された コンテナガイド を参照してください。

Keycloak 管理 REST クライアントの RESTEasy バージョンを次のメジャーバージョンに更新しました。

Keycloak は開発目的で H2 データベースドライバーを同梱しています。開発目的のみを意図しているため、本番環境で使用しないでください。

このリリースでは、H2 ドライバーがバージョン 1.x からバージョン 2.x にアップグレードされました。この変更により、既存の Keycloak セットアップで H2 JDBC URL または H2 データベースファイルの移行が必要になる場合があります。

このリリースには、Keycloak CR における次の互換性を損なう変更が含まれています。

Keycloak Operator Lifecycle Manager のデフォルトチャネルが fast に変更されました。

Keycloak 15 より前に、プロバイダーとモデルのインターフェースのクリーンアップがあり、そこでいくつかのメソッドを非推奨としました。これらのメソッドの Javadoc には、対応する代替メソッドが含まれていました (Keycloak 19 リリースの Javadoc を参照)。このリリースでは、これらのメソッドは削除されました。以下に変更されたすべてのクラスのリストを示します。

メソッドを非推奨および削除するための最も一般的なパターンは次のとおりです。

Keycloak 18.0.0 で、ログアウトは新しい OIDC 仕様と互換性を持つようになりました。新しい OIDC 仕様では、URL パラメーターの処理が変更されました。ただし、以前のバージョンとの互換性を維持するために、互換性フラグが導入されました。下位互換性オプションの詳細については、アップグレードガイド を参照してください。このオプションを使用すると、アプリケーションは引き続き URL パラメーターの古い形式を使用できます。

URL パラメーターは互換性を持つように構成できるようになりましたが、Keycloak 17 以前のリリースとの間にまだ 1 つの非互換性がありました。ユーザーが有効な idTokenHint を提供しない場合、ログアウトのリダイレクトが成功する代わりにログアウトプロンプトが表示されます。そのため、ログアウト画面を抑制するための新しい互換性フラグ suppress-logout-confirmation-screen が導入されました。

サーバーを起動するときに、次のコマンドを入力してこのパラメーターを有効にできます。

この構成により、ユーザープロンプトなしでログアウトエンドポイントを引き続き使用できます。

これまで、SAML クライアントまたはクライアントスコープで SAML javascript プロトコルマッパーを使用していた管理者は、Keycloak 管理コンソールおよび RESTful Admin API を介してサーバーにスクリプトをアップロードすることが許可されていました。

当面の間、この機能は 無効 になり、ユーザーはスクリプトをサーバーに直接デプロイする必要があります。この動作は、他のスクリプトベースのプロバイダーと一致しています。詳細については、JavaScript プロバイダー を参照してください。

新しい管理コンソールが Keycloak のデフォルトコンソールになりました。新しい管理コンソールの使用を開始できない場合は、たとえば次を実行して、新しいコンソールを無効にすることで、古い管理コンソールを引き続き使用できます。

古い管理コンソールを引き続き使用する別の方法として、マスターレルムまたは他のレルムのテーマを keycloak に設定する方法があります。

新しい管理コンソールは古い管理コンソールとは大幅に異なり、React ベースで、新しいバージョンの PatternFly を使用しているため、カスタムテーマはほとんどの場合、最初から再実装する必要があります。新しい管理コンソール用のカスタムテーマを作成するには、テーマは keycloak ではなく keycloak.v2 を拡張する必要があります。

マスターレルムまたは他のレルムの管理コンソールテーマを keycloak に明示的に設定している場合、古い管理コンソールを引き続き使用します。新しい管理コンソールに更新するには、テーマを keycloak.v2 に変更する必要があります。

古い管理コンソールは Keycloak 21 で削除されます。

このリリースより前は、サーバーを起動する前にビルドオプションが変更された場合に、条件付きで build を実行するようにサーバーに指示するために、start コマンドを実行するときに --auto-build を使用していました。

このリリースでは、--auto-build フラグは 非推奨 となり、サーバーを起動するときにビルドオプションを設定することを示すために使用する必要はなくなりました。代わりに、ビルドオプションが変更された場合、サーバーはサーバーを起動する前に常にデフォルトで build を実行するようになります。新しい動作は、最高の起動時間とメモリフットプリントを実現するために、build コマンドを事前に実行することがオプションですが、強く推奨されるようになり、サーバーの構成と起動時の全体的なエクスペリエンスを向上させます。

最高の起動時間とメモリフットプリントを実現するには、新しいデフォルトの動作を無効にするために --optimized オプションを設定してください。--optimized フラグは、起動の一部として直接 build をチェックして実行する必要がないことをサーバーに指示します。

カスタムイメージをすでに使用してビルドオプションを設定し、最適化された Keycloak コンテナを実行している場合は、start コマンドを呼び出すときに --optimized オプションを設定していることを確認してください。

詳細については、構成ガイド および コンテナガイド を参照してください。

Keycloak 19.0.0 より前は、Quarkus ベースの Keycloak ディストリビューションは、意図せずに次の非アプリケーションエンドポイントを常に有効にしていました。

Keycloak 19.0.0 以降では、これらのエンドポイントは 無効 になり、リクエストは 404 HTTP ステータスコードになります。/q/…​ エンドポイントを使用している場合は、Keycloak 19.0.0 にアップグレードするときに、意図されたヘルスエンドポイントを使用するようにプローブと監視システムを変更してください。

意図されたヘルスエンドポイントは次のとおりです。

/q/ エンドポイントを無効にする以外に、ヘルスエンドポイントに対して行われたその他の改善点は次のとおりです。

この領域では、今後さらに機能強化が期待されます。詳細については、ヘルスガイド を参照してください。

リリースノートに記載されているように、Keycloak は GELF ロギングを標準でサポートするようになりました。

以前のバージョンで GELF 関連の Quarkus JAR を自分で追加した場合、ロギングガイド のサポートされている構成オプションに切り替え、providers フォルダーから JAR を削除してください。

Keycloak は大規模なリファクタリングを行っており、既存のコードに影響を与えます。これらの変更の一部では、既存のコードの更新が必要です。これらについては、以下で詳しく説明します。

今回のリリースでは、レガシー Keycloak Operator の Keycloak CR の podDisruptionBudget フィールドを非推奨にしました。このオプションのフィールドは、Operator が Kubernetes バージョン 1.25 以降にデプロイされている場合、無視されます。

回避策として、Pod Disruption Budget をクラスターに手動で作成できます。例:

Kubernetes ドキュメントも参照してください。

新しい Keycloak Operator は、Keycloak デプロイメントに Deployment の代わりに StatefulSet を使用するようになりました。このリリースでは Operator が技術プレビューであるため、自動移行は行われません。18.0.z で新しい Operator を使用している場合は、19.0.0 へのアップグレード後に Keycloak CR をバックアップ、削除、再作成してください。

ステップアップ認証は新機能です。この機能は、トークンに acr クレームを追加することを目的としたプロトコルマッパーを含む acr クライアントスコープを提供します。acr クレームは、このバージョンより前のように自動的に追加されるのではなく、このクライアントスコープとプロトコルマッパーを使用することで追加されます。

クライアントスコープはレルムの「デフォルト」クライアントスコープとして追加されるため、新しく作成されたすべてのクライアントに追加されます。パフォーマンス上の理由から、クライアントスコープは移行中に既存のすべてのクライアントに自動的に追加されません。クライアントは、移行後、デフォルトでは acr クレームを持ちません。以下の可能なアクションを検討してください。

以前のバージョンの Keycloak では、http(s)://example-host/auth/realms/my-realm-name/protocol/openid-connect/logout?redirect_uri=encodedRedirectUri のようなログアウトエンドポイント URL を開くことで、ユーザーの自動ログアウトとアプリケーションへのリダイレクトがサポートされていました。その実装は使いやすかったものの、パフォーマンスとセキュリティに潜在的な悪影響がありました。新しいバージョンでは、OpenID Connect RP-Initiated Logout 仕様に基づいたログアウトのサポートが向上しています。パラメーター redirect_uri はサポートされなくなりました。また、新しいバージョンでは、ユーザーはログアウトを確認する必要があります。ログインに使用した ID トークンとともにパラメーター post_logout_redirect_uri とパラメーター id_token_hint を含めると、確認を省略してアプリケーションへの自動リダイレクトを実行できます。

既存のデプロイメントは、次の方法で影響を受けます。

アプリケーションが redirect_uri パラメーターの古い形式を引き続き使用できるようにする下位互換性オプションがあります。

サーバーを起動するときに、次のコマンドを入力してこのパラメーターを有効にできます。

この構成では、redirect_uri パラメーターを含む形式を引き続き使用できます。id_token_hint が省略されている場合、確認画面が必要になることに注意してください。

以前のバージョンの Keycloak では、管理コンソールや REST API などの管理インターフェースを介して JavaScript コードを管理することがサポートされていました。このバージョン以降、これは不可能になり、次のプロバイダーを構成するために、スクリプトをサーバーにデプロイする必要があります。

スクリプトをサーバーにデプロイする方法の詳細については、ドキュメントを参照してください。スクリプトを使用するには、scripts 技術プレビュー機能を有効にする必要があることに注意してください。

スクリプトをデプロイすると、サーバーは対応するプロバイダーを自動的に作成するため、認証フロー、マッパー、および承認ポリシーを構成するときにそれらを選択できます。

一般的に、レルムを更新する手順は次のとおりです。

Patternfly (PF) React ライブラリが更新され、@patternfly/react-core が v3.153.3 から v4.147.0 に、@patternfly/react-icons が v3.15.16 から v 4.11.8 に、@patternfly/react-styles が v3.7.14 から v4.11.8 に更新されました。アカウントコンソールを PF デザイン標準に合わせるために、いくつかのマイナーな UI アップデートが実施されました。

カスタム開発されたアカウント UI は、PF の破壊的変更により、これらのアップデートと互換性がない可能性があります。ほとんどの破壊的変更は、PF コンポーネントの props を更新することで解決できるはずです。

リソース

破壊的変更があることが判明しているコンポーネント

metrics-enabled オプションは、Keycloak のメトリクスのみを有効にするようになりました。readiness および liveness ヘルスエンドポイントを有効にするには、新しいブール値オプション health-enabled があります。これにより、これらのオプションをよりきめ細かく使用できます。例えば、オンプレミスユースケースの場合、メトリクスを有効にするが、readiness/liveness プローブを有効にしないなどです。metrics-enabled=true が設定されていた場合と同じ動作を維持するには、Keycloak をビルドするときに health-enabled=true も追加で設定する必要があります。

Keycloak のデフォルトディストリビューションは、Quarkus で駆動されるようになり、Keycloak の構成方法とカスタムプロバイダーのデプロイ方法に多くの破壊的変更がもたらされました。詳細については、Quarkus 移行ガイドを確認してください。

Keycloak の WildFly ディストリビューションは非推奨となり、サポートは 2022 年 6 月に終了します。Quarkus ディストリビューションへの移行をできるだけ早く行うことをお勧めします。ただし、レガシー WildFly ディストリビューションをしばらくの間維持する必要がある場合は、考慮すべきいくつかの変更点があります。

Quarkus ディストリビューションへの移行、何かの構成機能の欠落、または一般的なアイデアやフィードバックに関する問題が発生した場合は、GitHub Discussions でディスカッションを開始してください。

プレビュー Quarkus ディストリビューションが Keycloak 15.1.0 でリリースされてから、多くのことが変更されました。変更点について学習する理想的な方法は、新しい サーバーガイドを確認することです。要約すると、変更点は次のとおりです。

client-scopes 条件を含むポリシーを使用していて、JSON ドキュメントを直接編集した場合は、JSON ドキュメントの "scope" フィールド名を "scopes" に変更する必要があります。

Liquibase がバージョン 3.5.5 から 4.6.2 に更新されました。これには、とりわけ、いくつかのバグ修正と、ServiceLoader を使用したカスタム拡張機能を登録する新しい方法が含まれています。

以前の Keycloak バージョンから Keycloak 17.0.0 への移行は、現在サポートされているすべてのデータベースで広範囲にテストされていますが、アップグレードガイド、特にアップグレード前に既存のデータベースをバックアップすることを厳守することの重要性を強調したいと思います。Liquibase アップグレードの結果をテストするために最善を尽くしましたが、一部のインストールでは、不明な特定の設定を使用している可能性があります。

WildFly 25 は、とりわけ TLS の構成に使用されていたレガシーセキュリティサブシステムを非推奨にしました。変更量が多いため、過去に行ったような移行スクリプトを提供することはできません。

以前のバージョンの Keycloak から構成ファイルをコピーするのではなく、Keycloak 16 で提供されているデフォルトの構成ファイルから開始して、関連する変更を適用することをお勧めします。

Keycloak サブシステムの構成は、直接コピーできます。

Elytron サブシステムの詳細については、WildFly ドキュメントを参照してください。

このご不便をおかけして大変申し訳ございません。Keycloak 16 へのアップグレードがすべての人にとって非常に困難になることを理解していますが、代替アプローチを見つけることができませんでした。

指摘する価値のあることの 1 つは、Keycloak 17 で完全にサポートする予定の Quarkus ディストリビューションへの切り替えにより、Keycloak の構成とアップグレードが大幅に容易になることです。

WildFly 25 の詳細については、WildFly 25 リリースノートを参照してください。

Keycloak は、送信 HTTP リクエストに対して標準の HTTP_PROXY、HTTPS_PROXY、および NO_PROXY 環境変数を尊重するようになりました。この変更により、例えば HTTP_PROXY 変数が定義されているが、SPI 構成で明示的なプロキシマッピングが指定されていない場合、プロキシサーバーが予期せず使用される可能性があります。Keycloak がこれらの環境変数を使用しないようにするには、すべてリクエストに対して .*;NO_PROXY としてプロキシルートなしを明示的に作成できます。

今回のリリースでは、Keycloak Operator の一部の機能を非推奨にしたり、サポート対象外としてマークしたりしました。これは、Backup CRD とオペレーター管理の Postgres データベースに関係します。

以前は、Keycloak Operator による Keycloak CR の作成例に、サポート対象外のメトリクス拡張機能が追加されていました。これは削除されました。

クライアントポリシー機能は、Keycloak 12 以降のプレビュー機能であり、適切なサポートがありませんでした。この機能を試して、Keycloak 12 または Keycloak 13 でクライアントポリシーまたはクライアントプロファイルを構成した場合、新しいバージョンでクライアントポリシーとクライアントプロファイルを再度構成する必要があります。構成の形式は、プレビューのみであったため大幅に変更されており、Keycloak 12 または Keycloak 13 で作成されたクライアントポリシーとクライアントプロファイルの自動移行は提供していません。

standalone.xml に SmallRye モジュールへの参照が含まれている場合、手動での変更が必要です。SmallRye モジュールは、基盤となる WildFly ディストリビューションから削除され、構成がそれらを参照している場合、サーバーは起動しません。したがって、standalone.xml の構成がこれらのモジュールを参照している場合、migrate-standalone.cli によるサーバー構成の移行は、構成に変更が加えられる前に失敗します。そのような場合、サーバー構成の移行を実行するには、SmallRye モジュールを参照するすべての行を手動で削除する必要があります。デフォルト構成では、具体的には次の行を削除する必要があります。

Keycloak サーバーは、基盤となるコンテナとして Wildfly 23 を使用するようにアップグレードされました。これは、特定の Keycloak サーバー機能に直接関係するものではありませんが、移行に関連するこれらの変更に注意してください。

Keycloak サーバーは、基盤となるコンテナとして Wildfly 22 を使用するようにアップグレードされました。これは、特定の Keycloak サーバー機能に直接関係するものではありませんが、移行に関連するこれらの変更に注意してください。

読み取り専用のユーザー属性のサポートが追加されました。これには、REST API または Keycloak ユーザーインターフェースでユーザーを更新するときに、ユーザーまたは管理者によって編集されないはずのユーザー属性が含まれます。特に次を使用する場合は重要になる可能性があります。

詳細については、脅威モデルの軽減に関する章を参照してください。

OpenID Connect パラメーター request_uri を使用する場合、クライアントが Valid Request URIs を構成する必要があるという要件が存在します。これは、管理コンソールのクライアント詳細ページ、または管理 REST API またはクライアント登録 API を介して構成できます。有効なリクエスト URI には、特定のクライアントで許可されているリクエスト URI 値のリストを含める必要があります。これは、SSRF 攻撃を回避するためです。Valid Redirect URIs オプションと同様に、ワイルドカードまたは相対パスを使用する可能性がありますが、セキュリティ上の理由から、可能な限り具体的な値を使用することを通常はお勧めします。

Keycloak サーバーは、基盤となるコンテナとして Wildfly 22 を使用するようにアップグレードされました。これは、特定の Keycloak サーバー機能に直接関係するものではありませんが、移行に関連するいくつかの変更点があり、言及する価値があります。

Keycloak サーバーは、基盤となるコンテナとして Wildfly 21 を使用するようにアップグレードされました。これは、特定の Keycloak サーバー機能に直接関係するものではありませんが、移行に関連するこれらの変更に注意してください。

Docker プロトコルでの認証が成功した後、ユーザーセッションは作成されません。詳細については、サーバー管理ガイドを参照してください。

Keycloak ログインテーマコンポーネントが PatternFly 4 にアップグレードされました。古い PatternFly 3 は新しいものと同時に実行されるため、PF3 コンポーネントを保持することは可能です。ただし、ログインテーマのデザインにいくつかの変更が加えられました。それらにより、カスタムログインテーマをアップグレードしてください。必要な変更を含む例は、keycloak/examples/themes/theme/sunrise ディレクトリにあります。追加のセットアップは必要ありません。

この Keycloak バージョン以降、OAuth2 クライアントクレデンシャルグラントエンドポイントは、デフォルトでリフレッシュトークンを発行しません。この動作は、OAuth2 仕様に準拠しています。この変更の副作用として、クライアントクレデンシャル認証が成功した後、Keycloak サーバー側でユーザーセッションが作成されなくなり、パフォーマンスとメモリ消費が向上します。クライアントクレデンシャルグラントを使用するクライアントは、リフレッシュトークンの使用を停止し、refresh_token をグラントタイプとして使用する代わりに、grant_type=client_credentials でリクエストごとに常に認証することをお勧めします。これに関連して、Keycloak は OAuth2 失効エンドポイントでのアクセストークンの失効をサポートしているため、クライアントは必要に応じて個々のアクセストークンを失効させることができます。

後方互換性のため、古いバージョンの動作に固執する可能性が存在します。これを使用すると、クライアントクレデンシャルグラントによる認証が成功した後でもリフレッシュトークンが発行され、ユーザーセッションも作成されます。これは、Keycloak管理コンソールの特定クライアントの設定で、OpenID Connect Compatibility ModesセクションのUse Refresh Tokens For Client Credentials Grantスイッチで有効にできます。

Keycloakサーバーは、基盤となるコンテナとしてWildFly 20を使用するようにアップグレードされました。これはKeycloakサーバーの特定の機能に直接的な影響はありませんが、移行に関連する以下の変更点に注意してください。

以前のKeycloakバージョンでは、LDAPプロバイダーがImport Users OFFで設定されている場合、LDAPにマッピングされていない属性が変更されてもユーザーを更新することが可能でした。この状況では、属性が更新されたように見えても実際には更新されていないという、紛らわしい動作が発生していました。現在のバージョンでは、LDAPにマッピングされていない属性が変更された場合、更新は一切許可されません。

これはほとんどのデプロイメントには影響しないはずですが、まれな状況下では影響を受ける可能性があります。たとえば、以前に管理者REST APIを使用してユーザーを更新しようとした際に、ユーザーに誤った属性変更があった場合でも、更新は可能でした。現在のバージョンでは、更新は不可能になり、その理由がすぐに通知されます。

UserModelのフィールドであるusername、email、firstName、およびlastNameは、今後のバージョンでKeycloakにさらに洗練されたユーザープロファイルを追加するための準備として、カスタム属性に移行されました。データベースにそれらの正確な名前のカスタム属性を持つユーザーが含まれている場合、アップグレードする前にカスタム属性を移行する必要があります。この移行は自動的には行われません。そうしないと、それらはデータベースから読み取られなくなり、削除される可能性があります。この状況は、usernameがUserModel.getFirstAttribute(UserModel.USERNAME)を介してアクセスおよび設定できるようになったことも意味します。他のフィールドにも同様の影響があります。UserModelを直接的または間接的にサブクラス化するSPIの実装者は、setUsernameとsetSingleAttribute(UserModel.USERNAME, …​)（および他のフィールドについても同様）の間の動作が一貫していることを確認する必要があります。ポリシー評価機能のユーザーは、すべてのユーザーがデフォルトで4つの新しい属性を持つようになるため、属性の数を使用する評価を行う場合はポリシーを適合させる必要があります。

UserModelのパブリックAPIは変更されていません。フロントエンドリソースまたはユーザーデータにアクセスするSPIへの変更は必要ありません。また、データベースもまだ変更されていません。

Instagram IdPは、古いレガシーAPIが非推奨になったため、新しいAPIを使用するようになりました。これには、新しいAPIクレデンシャルを取得する必要があります。詳細については、サーバー管理ガイドを参照してください。

Instagram IdPを使用する既存ユーザー、特にそれが唯一の認証オプションであるユーザーは特別な注意が必要です。そのようなユーザーは、2020年9月30日までにInstagram IdPを使用してKeycloakにログインする必要があります。その日以降は、Instagramソーシャルリンクを手動で更新するか、Keycloakで新しいアカウントを作成するために、別の認証方法（パスワードなど）を使用する必要があります。これは、InstagramユーザーIDが古いAPIと新しいAPIの間で互換性がないためですが、新しいAPIは移行を可能にするために一時的に新旧両方のユーザーIDを返します。Keycloakは、ユーザーがログインするとIDを自動的に移行します。

以前のバージョンでは、Keycloakは2つのイントロスペクションエンドポイント、token_introspection_endpointとintrospection_endpointをアドバタイズしていました。後者はRFC-8414で定義されているものです。前者は以前に非推奨となり、現在は削除されました。

JavaScriptアダプターでpromiseTypeを設定する必要がなくなり、両方が同時に利用可能になりました。レガシーAPI（successとerror）は将来のある時点で削除されるため、ネイティブPromise API（thenとcatch）を使用するようにアプリケーションをできるだけ早く更新することを推奨します。

バージョン9.0.1では、レルム内に重複したトップレベルグループを作成する可能性のある問題が修正されました。それにもかかわらず、以前の重複グループの存在はアップグレードプロセスを失敗させます。Keycloakサーバーは、H2、MariaDB、MySQL、またはPostgreSQLデータベースを使用している場合にこの問題の影響を受ける可能性があります。アップグレードを開始する前に、サーバーに重複したトップレベルグループが含まれているか確認してください。たとえば、次のSQLクエリをデータベースレベルで実行してリストできます。

各レルムに同じ名前のトップレベルグループは1つしか存在できません。重複は確認し、アップグレード前に削除する必要があります。アップグレードのエラーには、Change Set META-INF/jpa-changelog-9.0.1.xml::9.0.1- KEYCLOAK-12579-add-not-null-constraint::keycloak failed.というメッセージが含まれています。

ログインページのロケールの選択方法、およびユーザーのロケールが更新されるタイミングに関して、多くの改善が行われました。

詳細については、サーバー管理ガイドを参照してください。

2038年には、intは1970年からの秒数を保持できなくなるため、これらをlong値に更新する作業を進めています。さらに、トークン表現におけるint値の処理に関連する別の問題が存在します。intはデフォルトでJSON表現で0になりますが、含まれるべきではありません。

非推奨になった正確なメソッドと代替メソッドの詳細については、JavaDocを参照してください。

古いリクエストおよび固定ホスト名プロバイダーは、新しいデフォルトホスト名プロバイダーに置き換えられました。リクエストおよび固定ホスト名プロバイダーは非推奨となり、できるだけ早くデフォルトホスト名プロバイダーに切り替えることを推奨します。

Keycloakサーバーは、基盤となるコンテナとしてWildFly 18を使用するようにアップグレードされました。これはKeycloakサーバーの特定の機能に直接的な影響はありませんが、移行に関連する以下の変更点に注意してください。

これまで、管理者はKeycloak管理コンソールおよびRESTful Admin APIを通じてサーバーにスクリプトをアップロードすることが許可されていました。

当面の間、この機能はデフォルトで無効になっており、ユーザーはスクリプトをサーバーに直接デプロイすることを推奨します。詳細については、JavaScriptプロバイダーを参照してください。

以前のリリースでは、開発者はJavaScriptアダプターにクライアントクレデンシャルを提供することが許可されていました。当面の間、クライアント側のアプリはシークレットを安全に保持できないため、この機能は削除されました。

認証フローに関連するリファクタリングと改善を行いました。移行中に注意が必要です。

ユーザー資格情報の保存に関する柔軟性を高めました。とりわけ、すべてのユーザーは同じタイプの複数の資格情報、たとえば複数のOTP資格情報を持つことができます。その結果、データベーススキーマにいくつかの変更が加えられました。ただし、以前のバージョンの資格情報は新しい形式に自動的に更新されるはずであり、ユーザーは以前のバージョンで設定されたパスワードまたはOTP資格情報で引き続きログインできるはずです。

Keycloakサーバーは、基盤となるコンテナとしてWildFly 17を使用するようにアップグレードされました。これはKeycloakサーバーの特定の機能に直接的な影響はありませんが、移行に関連する以下の変更点に注意してください。

Keycloakサーバーは、基盤となるコンテナとしてWildFly 16を使用するようにアップグレードされました。これはKeycloakサーバーの特定の機能に直接的な影響はありませんが、移行に関連する以下の変更点に注意してください。

MicroProfile/JWT Auth仕様で定義されているクレームを処理するために、新しいmicroprofile-jwtオプションのクライアントスコープを追加しました。この新しいクライアントスコープは、認証されたユーザーのユーザー名をupnクレームに設定し、レルムロールをgroupsクレームに設定するためのプロトコルマッパーを定義します。

prompt=noneクエリパラメータを含む転送リクエストを処理できるIDPを識別するために、OIDCアイデンティティプロバイダー設定にAccepts prompt=none forward from clientという名前の新しいスイッチを追加しました。

これまで、prompt=noneを含む認証リクエストを受信した場合、ユーザーがIDPによって認証されているかどうかを確認せずに、レルムで認証されていない場合、レルムはlogin_requiredエラーを返していました。今後は、認証リクエストのデフォルトIDPを（kc_idp_hintクエリパラメータの使用またはレルムのデフォルトIDPの設定によって）特定でき、IDPに対してAccepts prompt=none forward from clientスイッチが有効になっている場合、ユーザーがそこで認証されているかどうかを確認するために認証リクエストがIDPに転送されます。

このスイッチは、デフォルトIDPが指定されている場合にのみ考慮されることに注意することが重要です。その場合、ユーザーにIDPを選択するように求めることなく、認証リクエストをどこに転送するかを知っています。デフォルトIDPを特定できない場合は、認証リクエストを満たすためにどのIDPが使用されるかを推測できないため、リクエスト転送は実行されません。

Keycloakサーバーは、基盤となるコンテナとしてWildFly 15を使用するようにアップグレードされました。これはKeycloakサーバーの特定の機能に直接的な影響はありませんが、移行に関連する以下の変更点に注意してください。

バージョン4.8.1までのKeycloakのGoogleアイデンティティプロバイダーの実装は、認証とユーザープロファイルの取得にGoogle+ APIエンドポイントに依存していました。2019年3月以降、Googleは新しいGoogle Sign-in認証システムを優先してGoogle+ APIのサポートを削除しています。Keycloakアイデンティティプロバイダーは新しいエンドポイントを使用するように更新されたため、この統合を使用している場合は、Keycloakバージョン4.8.2以降にアップグレードしてください。

ディレクトリにアプリケーション識別子が見つからないというエラーが発生した場合は、Google API Consoleポータルでクライアントアプリケーションを再度登録して、新しいアプリケーションIDとシークレットを取得する必要があります。

Google+ユーザー情報エンドポイントによって提供され、Google Sign-in APIによって異なる名前で提供される非標準クレームのカスタムマッパーを調整する必要がある場合があります。利用可能なクレームに関する最新情報については、Googleドキュメントを参照してください。

LinkedInの方針に従い、すべての開発者はAPIおよびOAuth 2.0のバージョン2.0に移行する必要があります。そのため、LinkedInソーシャルブローカーを更新しました。

このブローカーを使用している既存のデプロイメントでは、LinkedIn APIのバージョン2を使用してユーザーのプロファイルをフェッチする際にエラーが発生し始める可能性があります。このエラーは、ブローカーの設定に使用されるクライアントアプリケーションに付与された権限の欠如に関連している可能性があり、Profile APIへのアクセスまたは認証プロセス中の特定のOAuth2スコープのリクエストが承認されていない可能性があります。

新しく作成されたLinkedInクライアントアプリケーションであっても、クライアントが少なくともr_liteprofileおよびr_emailaddress OAuth2スコープをリクエストできること、およびクライアントアプリケーションがhttps://api.linkedin.com/v2/meエンドポイントから現在のメンバーのプロファイルをフェッチできることを確認する必要があります。

メンバーの情報へのアクセスに関するLinkedInによって課せられたこれらのプライバシー制限と、現在のメンバーのProfile APIによって返されるクレームの限定されたセットにより、LinkedInソーシャルブローカーはメンバーのメールアドレスをデフォルトのユーザー名として使用するようになりました。つまり、認証中に承認リクエストを送信するときに、r_emailaddressが常に設定されるということです。

新しいレルムデフォルトクライアントスコープrolesとweb-originsを追加しました。これらのクライアントスコープには、ユーザーのロールと許可されたWebオリジンをトークンに追加するプロトコルマッパーが含まれています。移行中に、これらのクライアントスコープは、すべてのOpenID Connectクライアントにデフォルトクライアントスコープとして自動的に追加されるはずです。したがって、データベースの移行が完了した後、セットアップは必要ありません。

ネイティブJavaScript PromiseをJavaScriptアダプターで使用するには、initオプションでpromiseTypeをnativeに設定する必要があります。

過去には、ネイティブPromiseが利用可能な場合、レガシーKeycloak PromiseとネイティブPromiseの両方を提供するラッパーが返されていました。これにより、ネイティブエラーイベントの前にエラーハンドラーが常に設定されているとは限らず、Uncaught (in promise)エラーが発生するという問題が発生していました。

バージョン4.5.0までのKeycloakのMicrosoftアイデンティティプロバイダーの実装は、認証とユーザープロファイルの取得にLive SDKエンドポイントに依存していました。2018年11月以降、Microsoftは新しいMicrosoft Graph APIを優先してLive SDK APIのサポートを削除しています。Keycloakアイデンティティプロバイダーは新しいエンドポイントを使用するように更新されたため、この統合を使用している場合は、Keycloakバージョン4.6.0以降にアップグレードしてください。

"Live SDKアプリケーション"の下に登録されたレガシークライアントアプリケーションは、アプリケーションのID形式の変更により、Microsoft Graphエンドポイントでは動作しません。ディレクトリにアプリケーション識別子が見つからないというエラーが発生した場合は、Microsoft Application Registrationポータルでクライアントアプリケーションを再度登録して、新しいアプリケーションIDを取得する必要があります。

Keycloakサーバーは、基盤となるコンテナとしてWildFly 14を使用するようにアップグレードされました。これはKeycloakサーバーの特定の機能に直接的な影響はありませんが、移行に関連する以下の変更点に注意してください。

Keycloakサーバーは、基盤となるコンテナとしてWildFly 13を使用するようにアップグレードされました。これはKeycloakサーバーの特定の機能に直接的な影響はありませんが、移行に関連する以下の変更点に注意してください。

以前のバージョンでは、許可されたホスト名を指定するためにフィルターを使用することが推奨されていました。固定ホスト名を設定できるようになり、有効なホスト名が使用されていることを確認することが容易になり、内部アプリケーションが代替URL（たとえば内部IPアドレス）を介してKeycloakを呼び出すことも可能になりました。本番環境ではこのアプローチに切り替えることを推奨します。

クライアントスコープのサポートを追加しました。移行中に注意が必要です。