Upgrading Guide

自動移行を実行するには、目的のデータベースに接続しているサーバーを起動します。データベースのスキーマが新しいバージョンのサーバー用に変更されている場合は、そのスキーマが移行されます。

数百万のレコードを含む巨大なテーブルにインデックスを作成すると、簡単に膨大な時間がかかり、アップグレード時にサービスが大幅に中断する可能性があります。そのような場合のために、自動インデックス作成のしきい値（レコード数）を追加しました。デフォルトでは、このしきい値は 300000 レコードです。レコード数がしきい値を超えると、インデックスは自動的に作成されず、後で手動で適用できるSQLコマンドを含む警告メッセージがサーバーログに表示されます。

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

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

この設定でサーバーを起動すると、データベースを移行する必要があるかどうかがチェックされます。必要な変更は bin/keycloak-database-update.sql ファイルに書き込まれ、データベースに対して確認し、手動で実行することができます。

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

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

テンプレートをカスタマイズした場合、テンプレートに加えられた変更をしっかり確認し、カスタマイズしたテンプレートにそれらの変更を適用する必要があるかどうか判断しなければなりません。ほとんどの場合、カスタマイズしたテンプレートに同じ変更を適用する必要があります。テンプレートをカスタマイズしていなかった場合は、このセクションをスキップすることができます。

diffツールを使用してテンプレートを比較し、カスタマイズしたテンプレートにどんな変更を加えるか確認することがベスト・プラクティスになります。マイナーチェンジしただけの場合、更新されたテンプレートとカスタマイズしたテンプレートを比較する方が簡単です。ただし、変更をたくさん加えた場合は、新しいテンプレートとカスタマイズした古いテンプレートを比較する方が、必要な変更が表示されるため簡単です。

下記のスクリーンショットは、ログイン・テーマのinfo.ftlテンプレートとサンプルのカスタム・テーマを比較しています。

この比較によって、1つ目の変更（Hello world!!）はカスタマイズで、2つ目の変更（if pageRedirectUri）は基本テーマの変更であるということが簡単に分かります。2つ目の変更をカスタム・テンプレートにコピーすると、カスタマイズしたテンプレートは正常に更新されます。

もう1つ代替の方法になりますが、下記のスクリーンショットは、古いインストールのinfo.ftlテンプレートと新しいインストールの更新版のinfo.ftlテンプレートを比較しています。

この比較によって、基本テンプレートにどんな変更が加えられたのか簡単に分かります。次に、変更したテンプレートに同じ変更を手動で加える必要があります。このアプローチは最初のほど簡単ではないため、最初のアプローチが実現不可能な場合にのみ、このアプローチを使用します。

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

追加した値については、基本テーマのメッセージの値を確認して、そのメッセージをカスタマイズする必要があるかどうかを判断します。

名前を変更したキーについては、カスタムテーマのキーの名前も変更します。

変更した値については、基本テーマの値をチェックし、カスタムテーマを変更する必要があるかどうか判断します。

keycloakまたはrh-ssoテーマからスタイルを引き継ぐ場合、カスタム・スタイルを更新し、組み込みテーマのスタイルに加えられた変更を反映させる必要があります。

diffツールを使用して、古いサーバー・インストールと新しいサーバー・インストールのスタイルシートの変更を比較することがベスト・プラクティスになります。

たとえば、下記のとおりdiffコマンドを使用します。

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

新しいパラメーター --spi-user-profile-declarative-user-profile-max-email-local-part-length が追加され、後方互換性を考慮した最大電子メール・ローカル・パートの長さを設定できるようになりました。デフォルト値は64です。使用例は以下のとおりです。

クライアントタブのAdvanced Settingsのすべてのコンボから Never expires オプションが削除されました。このオプションは誤解を招きやすいものでした。というのも、さまざまな寿命やアイドル・タイムアウトは決して無限ではなく、一般的なユーザーセッションやレルムの値によって制限されていたからです。そのため、このオプションは削除され、他の2つのオプションが残されました。 Inherits from the realm settings （クライアントが一般的なレルム設定のタイムアウトを使用する）と Expires in （クライアント用に値がオーバーライドされる）です。内部的には Never expires は -1 で表されていました。現在、この値は管理コンソールに警告とともに表示され、管理者が直接設定することはできません。

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

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

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

Jakarta EE 10に対応するため、以下のようにすべてのJakarta EE仕様をアップグレードしました。

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

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

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

Quarkus 3は、Keycloakと同じJakarta EE 10をベースにしており、両者のスムーズな相互運用性を実現しています。また、Eclipse MicroProfile 6が含まれており、Jakarta EE 10 Core Profileと整合しています。Quarkus 3アップグレードの中心的な部分は、JPA 3.1とHibernate ORM 6のビルトインサポートです。

Keycloakは現在、Hibernate ORM 6.2へのアップグレードの恩恵を受けており、パフォーマンスの向上、SQLの改善、最新のJDKサポート、最新のRDBMS機能のサポートが含まれています。パフォーマンスの向上は、主にJDBC、HQL翻訳、クライテリア翻訳に影響します。

カスタムのプロバイダーやJPAエンティティーを使用している場合、これらの変更が影響する可能性があります。

詳細については、 Quarkus migration guide または Hibernate release notes を確認することをお勧めします。

従来のPromise APIメソッドは、Keycloak JSアダプターから削除されました。これは、アダプターから返されたプロミスに対して .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 Adminクライアントのデフォルトは、 org.keycloak:keycloak-admin-client です（バージョン22.0.0以降）。

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

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

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

詳しくは、 リバース・プロキシーの使用を参照。

この変更は、レルムのローカリゼーション・メッセージを使用している場合にのみ影響する可能性があります。

このバージョンまで、レルムのローカライズ・メッセージが使用された場合、テーマ間でのフォールバック・メッセージの解決が一貫していませんでした。詳細は、次の issue で確認できます。

実装はすべてのテーマで統一されました。一般的に、最も一致する言語タグのメッセージが最優先されます。もしレルムのローカライズ・メッセージとテーマの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 EEの仕様に基づいており、アプリケーションをこのテクノロジーに切り替える際には、すぐに使用する必要があります。

この変更はすでに私たちのドキュメントとクイックスタートのリポジトリーにあります。詳細については、以下を参照してください。

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

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

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

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 から直接インスタンスを取得できます。

は、以下に置き換えられました。

KeycloakSession インスタンスを呼び出す際に access to がない場合、JAX-RSリソース・メソッドからコンテキスト・データを以下のようにJAX-RSランタイムから取得できます。

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

サーバーのREST APIを以下のSPIを介して拡張している場合は、元のテキストの大文字と句読点をできるだけ保持してください。

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

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

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

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

Kubernetesの標準的な条件に準拠するため、条件ステータス・フィールドはブール型から文字列型に変更されました。CRDでは一時的に任意のコンテンツを受け入れる形で表されますが、実際には常に文字列です。このフィールドの使用方法が、trueまたはfalseではなく、"True"、"False"、または"Unknown"の値を期待するように更新されていることを確認してください。

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

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

以前のバージョンでは、KeycloakをJava 17上でJavaScriptプロバイダー（スクリプト・オーセンティケーター、JavaScript認可ポリシー、OIDCおよびSAMLクライアント用のスクリプト・プロトコル・マッパー）を使用する場合、JavaScriptエンジンを配布物にコピーする必要がありました。NashornのJavaScriptエンジンはKeycloakサーバーでデフォルトで利用可能なため、この必要はもうありません。スクリプト・プロバイダーをデプロイする際には、Nashornスクリプト・エンジンとその依存関係をKeycloakの配布物にコピーしないことをお勧めします。

Service Account Client のデフォルトの Client ID マッパーが変更されました。 Token Claim Name フィールドの値が clientId から client_id に変更されました。 client_id クレームは以下のOAuth2の仕様に準拠しています。

clientId ユーザー・セッション・ノートはまだ存在しています。

これまで、Keycloak JSアダプターのインスタンスを作成するには、 Keycloak() 関数を以下のように直接呼び出すことが可能でした。

これをJavaScriptの世界の現代的な慣習に合わせるために、代わりに以下のように new 演算子 を使ってインスタンスを生成することができるようになりました。

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

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

カスタム拡張機能がこの属性に依存している場合、 terms_and_conditions と TERMS_AND_CONDITIONS の両方の属性をチェックするようにコードを調整する必要があるかもしれません。

Keycloakは、Prometheusフォーマットでメトリクスをエクスポートするメトリクス・エンドポイントをオプションで提供しています。このリリースでは、このデータを提供する実装がSmallRyeから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に問題が発生する可能性があります（少なくともログに警告やエラーが表示される）ので、そのようなテーマを一切導入しないことを強くお勧めします。

Keycloaコンテナー・イメージ は、セキュリティー強化のために変更されました。その結果、カスタマイズしたイメージで使用していた curl やその他のCLIツールは削除されました。この変更の扱い方については、更新された container guide を参照してください。

RESTEasy版Keycloak Admin REST Clientを次のメジャーバージョンに更新しました。

Keycloakは、開発用としてH2データベース・ドライバーを搭載して出荷されています。開発目的のみのため、プロダクション環境では絶対に使用しないでください。

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

本リリースには、Keycloak CRの以下のブレークダウンが含まれています。

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

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

メソッドの非推奨・削除のパターンとしては、以下のようなものがよくあります。

Keycloak 18.0.0では、ログアウトが新しいOIDC仕様に対応し、URLパラメーターの取り扱いが変更されました。ただし、以前のバージョンとの互換性も保つために、互換性フラグが導入されています。後方互換オプションの詳細については、 Upgrading Guide を参照してください。これにより、アプリケーションはURLパラメーターの古い形式を引き続き使用できます。

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

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

この設定でも、ログアウト・プロンプトを表示せずに、ログアウト・エンドポイントを使用することは可能です。

これまで、SAMLクライアントやクライアント・スコープでSAML JavaScriptプロトコル・マッパーを使用している管理者は、管理REST APIだけでなくKeycloak管理コンソールからもサーバーにスクリプトをアップロードすることができました。

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

新しい管理コンソールが、Keycloakのデフォルトコンソールになりました。新しい管理コンソールの使用を開始できない場合、新しいコンソールを無効にすることで、古い管理コンソールを使い続けることが可能です（たとえば、以下を実行してください）。

古い管理コンソールを使い続ける別の方法は、masterレルムまたは他のレルムのテーマを keycloak に設定することです。

新しい管理コンソールは古い管理コンソールと大きく異なり、Reactをベースにし、PatternFlyの新しいバージョンを使用しているため、カスタムテーマはおそらくゼロから再実装する必要があります。新しい管理コンソール用のカスタムテーマを作成するには、テーマは keycloak の代わりに keycloak.v2 を拡張する必要があります。

masterレルムやその他のレルムで管理コンソールのテーマを明示的に keycloak に設定している場合、古い管理コンソールを使い続けることになります。新しい管理コンソールに更新するには、テーマを keycloak.v2 に変更する必要があります。

旧管理コンソールは、Keycloak 21で削除される予定です。

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

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

最高のスタートアップ時間とメモリー・フットプリントを達成するために、以下のように --optimized オプションを設定して、新しいデフォルトの動作を無効にします。このフラグは、起動時に build を直接チェックし、実行する必要がないことをサーバーに伝えます。

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

詳しくは、 Configuration Guide 、 Containers Guide を参照してください。

Keycloak 19.0.0以前では、QuarkusベースのKeycloakディストリビューションでは、以下の非アプリケーション・エンドポイントが意図せず常に有効になっていました。

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

意図するヘルス・エンドポイントは、以下の通りです。

/q/エンドポイントを無効化する以外に、ヘルス・エンドポイントに施された改良点は以下の通りです。

今後のこの分野の強化に期待してください。詳しくは、 Health guide を参照してください。

リリースノートに記載されているように、Keycloakは集中型ロギングシステム用のelfロギングをサポートするようになりました。

以前のバージョンでelf関連のQuarkusのjarファイルを自分で追加した場合、 logging guide でサポートされている設定オプションに切り替え、 providers フォルダーから自分のjarファイルを削除するようにしてください。

Keycloakは大規模なリファクタリングが行われ、既存のコードに影響を及ぼします。これらの変更の中には、既存のコードの更新を必要とするものがあります。これらについては、以下で詳しく説明します。

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

回避策として、例えば、以下のようにクラスター内でPod Disruption Budgetを手動で作成できます。

Kubernetes Documentation もご参照ください。

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

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

クライアント・スコープは、レルムの「デフォルト」クライアント・スコープとして追加されるため、新しく作成されたすべてのクライアントに追加されます。パフォーマンス上の理由から、移行中はすべての既存クライアントにクライアント・スコープが自動的に追加されるわけではありません。移行後のクライアントは、デフォルトでは acr claim を持ちません。これらの可能なアクションを考えてみましょう。

以前のバージョンの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トークンを id_token_hint パラメーターと一緒に post_logout_redirect_uri パラメーターに含めると、確認を省略してアプリケーションへの自動リダイレクトを行うことができます。

既存のデプロイメントには、以下のような影響があります。

後方互換性オプションがあり、アプリケーションは 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からv4.11.8へ、そして @patternfly/react-styles がv3.7.14からv4.11.8へ更新されています。アカウント・コンソールをPFデザイン標準に合わせるため、いくつかのマイナーなUIアップデートが行われました。

カスタム開発されたアカウントUIは、PFの変更点のため、これらのアップデートと互換性がない場合があります。ほとんどの変更点は、PFコンポーネントのプロパティーを更新することで対応できるはずです。

リソースは以下です。

変更点があることが判明しているコンポーネントは以下の通りです。

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

KeycloakのデフォルトのディストリビューションはQuarkusで提供されるようになり、Keycloakの設定やカスタム・プロバイダーのデプロイに多くの変更があります。詳細については、 Quarkus Migration Guide を参照してください。

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

Quarkusディストリビューションへの移行に問題が発生した場合、設定ができない場合、または一般的なアイデアやフィードバックがある場合は、 GitHub Discussions でディスカッションを開いてください。

Keycloak 15.1.0でQuarkusディストリビューションのプレビューがリリースされて以来、多くの変更があります。変更点を知るには、新しい Server Guide をチェックするのが理想的です。要約すると、以下のような変更があります。

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

Liquibaseはバージョン3.5.5から4.6.2にアップグレードされ、いくつかのバグフィックスと ServiceLoader を使ったカスタム拡張の新しい登録方法が含まれています。

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

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

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

Keycloakサブシステムの設定は、直接コピーすることができます。

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

このようなご不便をおかけして本当に申し訳なく思っています。また、皆様がKeycloak 16にアップグレードすることが著しく困難になることを理解していますが、代替手段を見つけることができませんでした。

特筆すべきは、Quarkusディストリビューションへの切り替えで、Keycloak 17で完全にサポートされる予定ですが、これによりKeycloakの設定とアップグレードが大幅に容易になる予定です。

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

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

今回のリリースでは、Keycloak Operatorのいくつかの機能を非推奨および/またはサポート対象外としています。これは、バックアップCRDとOperator が管理するPostgresデータベースに関するものです。

以前は、Keycloak OperatorによるKeycloak CRの作成例で、サポートされていないMetrics Extensionが追加されていました。これは削除されました。

クライアント・ポリシー機能は、Keycloak 12以降のプレビュー機能であり、適切なサポートがありませんでした。この機能を試して、Keycloak 12やKeycloak 13でいくつかのクライアント・ポリシーやクライアント・プロファイルを設定した場合、新バージョンで再度クライアント・ポリシーやクライアント・プロファイルを設定する必要があります。あくまでもプレビューのため、設定の形式が大きく変わったため、Keycloak 12やKeycloak 13で作成したクライアント・ポリシーやクライアント・プロファイルの自動移行は行っておりません。

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

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

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

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

See the details in the Threat model mitigation chapter 。

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

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

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

Dockerプロトコルによる認証が成功した後、ユーザー・セッションは作成されません。詳細については、 Server Administration Guide を参照してください。

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

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

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

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

以前のバージョンのKeycloakでは、 Import Users がオフのLDAPプロバイダーが設定されている場合、非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を変更する必要はありません。データベースもまだ変更されていません。

古いレガシーAPIが 廃止 されたため、Instagram IdPは新しいAPIを使用するようになりました。これには、新しいAPIクレデンシャルを取得する必要があります。詳しくは、 Server Administration Guide を参照してください。

Instagram IdPを使用する既存のユーザー、特にそれが唯一の認証オプションであるユーザーには、特別な注意が必要です。そのようなユーザーは、2020年9月30日までにInstagram IdPを使用してKeycloakにログインする必要があります。その日を過ぎると、ログインに別の認証方法（パスワードなど）を使用してInstagramソーシャルリンクを手動で更新するか、Keycloakに新しいアカウントを作成する必要があります 。これは、InstagramのユーザーIDが古いAPIと新しいAPIの間で互換性がないためですが、新しいAPIは移行を許可するために一時的に新しいユーザーIDと古いユーザー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 Databaseを使用している場合、この問題の影響を受ける可能性があります。アップグレードを開始する前に、サーバーに重複した最上位グループが含まれているかどうかを確認してください。たとえば、次のSQLクエリーをデータベース・レベルで実行して、それらを一覧表示できます。

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

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

詳細については、 Server Administration Guide を参照してください。

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

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

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

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

これまで、管理者はKeycloak管理コンソールとRESTful Admin APIを使用して、サーバーにスクリプトをアップロードできました。

現時点では、この機能はデフォルトで 無効 であり、ユーザーはスクリプトをサーバーに直接デプロイすることを選択する必要があります。詳細については、JavaScript Providersを参照してください。

以前のリリースでは、開発者はクライアントのクレデンシャルをJavaScriptアダプターに提供できました。現時点では、この機能は 削除 されました。これは、クライアントサイドのアプリがシークレットを保持する上で安全ではないためです。

認証フローに関連するリファクタリングと改善をいくつか行いました。これにより、移行の際に注意が必要です。

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

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

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

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

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

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

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

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

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

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

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

したがってLinkedInでは、すべての開発者が自分のAPIのバージョン2.0とOAuth 2.0に移行する必要があります。そのため、LinkedIn Social Brokerを更新しました。

このブローカーを使用している既存のデプロイメントでは、LinkedIn APIのバージョン2を使用してユーザーのプロファイルを取得する際にエラーが発生する可能性があります。このエラーは、ブローカの設定に使用されるクライアント・アプリケーションに付与されたアクセス権が不足しており、認証プロセス中にProfile APIへのアクセスや特定のOAuth2スコープの要求を許可されていない可能性があります。

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

メンバーの情報へのアクセスと現在のメンバーのProfile APIによって返される限定されたクレーム・セットに関して、LinkedInによって課されたプライバシー制限のために、LinkedIn Social Brokerは現在デフォルトのユーザー名としてメンバーのメールアドレスを使用しています。つまり、認証中に認可リクエストを送信する際には常に r_emailaddress が設定されます。

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

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

以前は、ネイティブのPromiseが利用可能であった場合、レガシーのKeycloakのPromiseとネイティブのPromiseの両方を提供するラッパーが返されました。これにより、ネイティブのエラーイベントの前にエラーハンドラーが常に設定されていないために問題が発生していました。

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

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

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

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

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

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

UMA 2.0のサポートを追加しました。このバージョンのUMA仕様では、サーバーからのパーミッションの取得方法に関する重要な変更が導入されました。

ここでは、UMA 2.0サポートによって導入された主な変更点を示します。詳細は、 Authorization Services Guide を参照してください。

OpenID Connectセッション管理仕様では、パラメーター session_state がOpenID Connect認証レスポンスに存在する必要があります。

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

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

たとえば、クライアント・アプリケーションへの認証が成功すると、ブラウザーのURLには常にパラメーターが表示されます。このような場合、認証レスポンスに session_state パラメーターを追加することを無効にすると便利です。これは、Keycloak管理コンソールの特定のクライアントで行うことができます（クライアントの詳細については、 古いアダプターとの互換性 の OpenID Connect Compatibility Modes のセクションで説明しています）。 session_state パラメーターを認証レスポンスに追加しないようにすることができる専用の Exclude Session State From Authentication Response スイッチがあります。

2つの新しいパスワード・ハッシュ・アルゴリズム（pbkdf2-sha256とpbkdf2-sha512）を追加しました。新しいレルムでは、27500ハッシュ・イテレーションでpbkdf2-sha256ハッシュ・アルゴリズムが使用されます。pbkdf2-sha256はpbkdf2よりは多少速いため、そのイテレーションは20000から27500に増加されました。

既存のレルムは、パスワードポリシーにハッシュ・アルゴリズム（未指定）とイテレーション（20000）のデフォルト値が含まれている場合、アップグレードされます。ハッシュ・イテレーションを変更しており、セキュリティー上より安全なハッシュ・アルゴリズムを使用したい場合は、手動でpbkdf2-sha256に変更する必要があります。

OpenID Connectの仕様では、初回の認可リクエストにおいて、 openid の値を持つパラメーターである scope を使用する必要があります。そのため、Keycloak 2.1.0では、KeycloakへのURIへリダイレクトする際に scope=openid を使用するように、アダプターを変更しました。また、サーバー部分も変更され、 scope=openid が実際に使用される場合にのみ、IDトークンがアプリケーションに送信されます。 scope=openid が使用されない場合は、IDトークンはスキップされ、アクセストークンとリフレッシュトークンだけがアプリケーションに送信されます。これにより、目的に応じて（たとえば、容量やパフォーマンスなどの目的で）、IDトークンの生成を省略することもできます。

ダイレクト・グラント（OAuth2リソース・オーナー・パスワード・クレデンシャル・グラント）とサービス・アカウント・ログイン（OAuth2クライアント・クレデンシャル・グラント）でも、IDトークンはデフォルトで使用されません。IDトークンを含めるには、敢えて scope=openid パラメーターを追加する必要があります。

現在、Keycloakに対してマルチ・データセンターのサポートが実装されています。最初のステップとして、認証セッションとアクション・トークンを導入しました。認証セッションは、以前のバージョンで使用されていたクライアント・セッションを入れ替えたものになります。アクション・トークンは、現在、特殊なシナリオで使用されていますが、このシナリオにおいてはauthenticatorまたはrequiredActionProviderによってユーザーにEメールが送られ、ユーザーがEメールに記載されているリンクをクリックする必要があります。

これに関する具体的な変更は下記のとおりで、移行に影響を与えることになります。

これに関する1つ目の変更は、 standalone.xml または standalone-ha.xml 内の新しいInfinispanのキャッシュ authenticationSessions と actionTokens を導入したことです。移行CLIを使用している場合は、 standalone(-ha).xml ファイルは自動的に移行されるため、ほとんど気にする必要はありません。

2つ目の変更は、認証SPIのメソッドで複数の署名を変更したことです。この変更により、カスタム Authenticator または RequiredActionProvider を使用すると影響を受けることになります。クラス AuthenticationFlowContext と RequiredActionContext によって、クライアント・セッションの代わりに認証セッションを取得することができます。

また、スティッキー・セッションの初回サポートも追加しました。パフォーマンスを上げたい場合は、ロードバランサーまたはプロキシー・サーバーを変更し、それを設定できます。ルートには新しい AUTH_SESSION_ID Cookieに追加されます。詳しくは、クラスター構成についてのドキュメントを参照してください。

別の変更点として、 token.getClientSession() が削除されたことがあります。これは、たとえば、クライアントの初回アイデンティティー・ブローカー・リンキング機能を使用している場合などに、影響を受ける可能性があります。

ScriptBasedAuthenticator のバインディング名が、 clientSession から authenticationSession に変更されました。そのため、このオーセンティケーターを使用している場合、スクリプトを更新する必要があります。

最後に、新しいタイムアウトを管理コンソールに追加しました。この追加によって、たとえば、管理者およびユーザー自身によってトリガーされた電子メール・アクションに異なるタイムアウトを指定することができます。

2.2.0以前から移行してオフライン・トークンを使用した場合、オフライン・トークンは トークンのヘッダーにKIDを含んでいません。2.3.0では、複数のレルム鍵を持つ機能に加えて、KIDをトークン・ヘッダーに追加しました。そのため、KeycloakはトークンのKIDに基づく正しい鍵を見つけることができます。

KIDを含まないオフライン・トークンの場合、Keycloak 2.5.1はトークンの検証に適した鍵を見つけるため、常にアクティブなレルム鍵を使用します。言い換えると、古いオフライン・トークンが移行されることになります。そのため、たとえば、ユーザーが1.9.8でオフライン・トークンを要求すると、1.9.8から2.5.1に移行されたとき、ユーザーは2.5.1であっても古いオフライン・トークンをリフレッシュできることになります。

しかし、これには制限があります。アクティブなレルム鍵をいったん変更すると、ユーザーは古いオフライン・トークンを更新することができなくなります。したがって、オフライン・トークンを使用している全ユーザーが自身のトークンを更新するまで、アクティブ・レルム鍵を変更すべきではありません。新しく更新されたトークンには、確実にヘッダーにKIDが付与されます。そのため、全ユーザーが自身の古いオフライン・トークンを更新した後は、アクティブなレルム鍵を自由に変更することができます。

standalone.xml または standalone-ha.xml 設定ファイル内のInfinispanサブシステムで定義された realms キャッシュには、現在、デフォルトで10000レコードのエビクションが用意されています。 users キャッシュにも、同じようにデフォルト値が設定されています。

また、 authorization キャッシュにはデフォルトではエビクションは用意されていません。

keycloak-server-spiモジュールは、keycloak-server-spiとkeycloak-server-spi-privateに分割されています。今後のマイナーリリースにおいて、keycloak-server-spi内のAPIは変更しませんが、keycloak-server-spi-private内のAPIは変更する可能性が十分にあります。

現在、SAMLアサーション内のキーとドキュメントは、RSA-OAEP暗号化方式を使用して暗号化されています。暗号化されたアサーションを使用する場合、サービスプロバイダーがこの暗号化方式を理解していることを確認してください。稀なケースながら、SPがこの新しい方式を処理できない場合は、システム・プロパティー keycloak.saml.key_trans.rsa_v1.5 を true に設定して起動すると、KeycloakはレガシーなRSA-v1.5暗号化方式を使用することができます。

クラスター内でKeycloakを使用する場合でも、 standalone-ha.xml 内のinfinispanサブシステム内で定義されたキャッシュ realms と users は、現在常にローカル・キャッシュです。これらとは別に、クラスターノード間で無効化メッセージの送信し、クラスター全体に、 realms と users キャッシュの前提となるレコードの内どれが無効となるのかを知らせるキャッシュ work というものがあります。

現在、ページネーションをサポートするすべての管理REST APIエンドポイントで、最大結果件数のデフォルトは100に設定されています。100を超えるエントリーを返す場合は、敢えて ?max=<RESULTS> を使用して、それを指定する必要があります。

2.3.0リリースには、公開鍵ローテーションへのサポートを追加しました。管理者がKeycloak管理コンソールでレルム鍵のローテーションを行うと、クライアント・アダプターはそれを認識し、自動的に新しい公開鍵をKeycloakからダウンロードすることができます。ただし、ハードコーディングされた公開鍵を持つアダプターに realm-public-key オプションが指定されていない場合にのみ、この新しい鍵の自動ダウンロードは実行されます。このため、アダプター設定では realm-public-key オプションの使用は推奨されません。

このオプションは引き続きサポートはされていますが、アダプター設定でハードコーディングされた公開鍵を使用し、Keycloakから公開鍵をダウンロードしない場合にのみ便利です。この方法を使用する理論上の理由としては、アダプターとKeycloakの間に信頼できないネットワークがある場合に中間者攻撃を避けることができるという理由になりますが、実際はその場合、HTTPSを使用する方がはるかに良いです。HTTPSを使用すれば、アダプターとKeycloakの間のすべてのリクエストはセキュリティー上安全です。

このリリースでは、 standalone.xml または standalone-ha.xml 設定ファイルで定義されたInfinispanサブシステムに、新しいキャッシュ keys を追加しました。これには、エビクションと期限があります。このキャッシュは、サーバー（署名されたJWTでの認証を使用するアイデンティティー・プロバイダーまたはクライアント）によって信頼されるエンティティーの外部公開鍵をキャッシュするために内部的に使用されます。

現在、JPAとMongoの両方の databaseSchema プロパティーは 廃止 され、 initializeEmpty と migrationStrategy によって置き換えられています。 initializeEmpty は true または false に設定することができ、空のデータベースを初期化すべきかどうかを制御します。 migrationStrategy は update 、 validate および manual に設定することができます。 manual はリレーショナル・データベースでのみサポートされており、SQLファイルを作成してデータベース・スキーマに必要な変更を加えます。Oracle Databaseの場合は、作成されたSQLファイルには、OracleのSQLクライアントが理解できる SET DEFINE OFF コマンドが含まれています。他のクライアントがこのスクリプトを使用する場合は、変数の展開を無効にするためのツールの同等のコマンドで行を置換するか、そのような機能が適用されない場合は完全に削除してください。

以下のシナリオは、影響を受けることになります。

アイデンティティー・プロバイダーには、デフォルトの認証プロバイダーとして設定されるオプションはもはやありません。その代わり、認証に移動して Browser フローを選択し、 Identity Provider Redirector を設定します。デフォルトのアイデンティティー・プロバイダーを設定するオプションがあります。

1.0.0.Finalからのアップグレードはサポートされなくなりました。2.0.0へアップグレードするには、その前に1.9.8.Finalへアップグレードしてください。

新しいレルムのためにデフォルトでパスワードをハッシングする間隔は、（以前の1から） 20Kに増加されました。この変更により、ユーザー認証時のパフォーマンスが影響を受けることになります。たとえば、以前のデフォルト（1）ではパスワードをハッシングするのに1ミリ秒もかかりませんでしたが、新しいデフォルト（20K）では50から100ミリ秒かかります。

Keycloakの管理者ユーザーを追加するスクリプトの名前を、 add-user-keycloak へ変更しました。

オプションauth-server-url-for-backend-requestsは削除しました。このオプションが使用されると、いくつかのシナリオに問題が生じたためです。具体的には、2つの異なるコンテキスト（内部および外部）からKeycloakサーバーへのアクセスが可能だったのですが、このことがトークンを検証する際などに問題を起こしていました。

それでも、このオプションが提供する（アプリケーションがバックチャネル・リクエストをロードバランサーを通じて送るのではなく、ローカルのKeycloakサーバーに直接送るという）ネットワークの最適化を使用したい場合は、ホスト設定（DNS）レベルで処理する必要があります。

テーマとプロバイダーのディレクトリーを standalone/configuration/themes と standalone/configuration/providers から themes と providers へそれぞれ移動させました。カスタマイズしたテーマとプロバイダーを追加している場合は、それらを新しい場所に移動させる必要があります。また、このことによって変更されたとおりに、 keycloak-server.json を更新する必要もあります。

以前は、SAMLまたはOIDCのKeycloakサブシステム・アダプターを、WildFlyまたはJBoss EAPにすでにインストールしていた場合に、Keycloakを使用していたか否かに関わらず、全てのアプリケーションにKeycloakクライアントのjarを自動的に含めていました。現在は、そのアダプターのためにKeycloak認証を（サブシステムまたはweb.xml内のauth-methodを通じて）有効にしている場合にのみ、これらのライブラリーはデプロイメントに追加されることになります。

クライアント登録サービスのエンドポイントは、 {realm-name}/clients から {realm-name}/clients-registrations へ移動しました。

OpenID Connectの認証レスポンスにおけるセッション状態を session-state というキー名にしていましたが、これは仕様上間違っていたため、 session_state に変更しました。

1.2では、OpenID Connectの仕様と合わないエンドポイントを大量に廃止し、現在は削除されています。これは、1.8で新しいイントロスペクト・エンドポイントに置き換えられた、トークン検証エンドポイントにも適用されます。

template.ftlのフィードバックを移動し、フォーマットをわずかに変更しました。

モジュールとソースコードのほとんどは、keycloak-server-spiおよびkeycloak-servicesという、2つのmavenモジュールに統合されました。 SPIのインターフェイスはserver-spiに、実装はkeycloak-servicesに統合されています。すべてのJPA依存のモジュールはkeycloak-model-jpaに統合されました。mongoとInfinispanも同様で、keycloak-model-mongoとkeycloak-model-infinispanのモジュールに統合されています。

セッションIDをサポートするプラットフォーム（Tomcat 8、Undertow/WildFly、Jetty9）では、セキュリティー攻撃口をふさぐために、ログイン後にKeycloakのOIDCとSAMLアダプターによってセッションIDが変更されます。この動作をアダプターの設定スイッチをチェックすることでオフにすることができます。

現在、KeycloakのSAML SPクライアント・アダプターは、IDPで登録されるために、特定のエンドポイント /saml を要求します。

以前のリリースでは、デフォルトのパスワードでデフォルトの管理者ユーザーを設定していましたが、現在はこれを削除しています。1.8の新規のインストールでは、最初の手順として管理者ユーザーを作成する必要があります。

OAuth2の仕様により合わせるために、トークン・イントロスペクション用の新しいエンドポイントを追加しました。新しいエンドポイントは /realms/{realm-name}/protocols/openid-connect/token/introspect で取得することができ、 RFC-7662 にのみ基づいています。

/realms/{realm-name}/protocols/openid-connect/validate エンドポイントは現在廃止されています。新しいイントロスペクション・エンドポイントにできるだけ早く移動することを強くお勧めします。この変更の理由は、RFC-7662が、より標準的でセキュリティー上安全なイントロスペクション・エンドポイントが提供していることです。

新しいトークン・イントロスペクションURLは、現在 /realms/{realm-name}/.well-known/openid-configuration 上のOpenID Connectプロバイダーの設定から取得することができます。このレスポンス内に、 token_introspection_endpoint という名前のクレームがあります。 confidential clients だけがこの新しいエンドポイントを呼び出すことが許可されており、そこでは、これらのクライアントは通常、リソースサーバーとして機能し、ローカルの認可チェックを実施するために、トークンのメタデータを検索します。

OpenID Connectの仕様により合わせるために、管理コンソールのClient Settingsのページにフラグを追加しました。そのページでは、さまざまな種類のOpenID ConnectまたはOAuth2のフロー（Standard flow、Implicit flow、Direct Access Grants、Service Accounts）を有効または無効にすることができます。この一環として、新規クライアント用にはデフォルトで無効となっている Direct Access Grants （OAuth2の Resource Owner Password Credentials Grant に対応）があります。

以前のバージョンから移行されたクライアントは、 Direct Grants Only フラグがオンである場合のみ、 Direct Access Grants が有効になります。ダイレクト・アクセス・グラントを有効にし、スタンダード + インプリシットの両方のフローを無効にした場合と同等の、 Direct Grants Only フラグは削除されました（同じ効果となるため）。

また、組み込みのクライアント admin-cli を各レルムに追加しました。このクライアントは Direct Access Grants が有効になっています。そのため、管理REST APIまたはKeycloakの管理クライアントを使用している場合は、 security-admin-console の代わりに admin-cli を使用するように設定を更新する必要があります。現在、後者はデフォルトでダイレクト・アクセス・グラントが有効になっていないためです。

このバージョンで、 First Broker Login を追加しました。この追加により、新規ユーザーがアイデンティティー・プロバイダー（またはソーシャル・プロバイダー）を介してログインした際、ソーシャルアカウントにリンクされたKeycloakユーザーがまだ存在しない場合に何を実行するかを正確に指定できます。この一環として、 First Login Flow オプションをアイデンティティー・プロバイダーに追加しました。これにより、フローを特定し、管理コンソール内の Authentication タブでこのフローを設定することができるようになりました。

また、 Update Profile On First Login オプションをアイデンティティー・プロバイダー設定から削除し、 Review Profile オーセンティケーターの設定に移動させました。そのため、アイデンティティー・プロバイダー用にはどのフローを使う必要があるのかを指定すれば（デフォルトでは First Broker Login フローとなっていますが）、 Authentication タブに移動してフローを選択し、 Review Profile オーセンティケーターの下にあるオプションで設定することができます。

web.xml内のform-error-pageは、クライアント・アダプター認証エラーにより動作しなくなりました。さまざまなHTTPエラーコード用にerror-pageを定義する必要があります。アダプターのエラー条件を確認および処理したい場合、詳細はドキュメントを参照してください。

インターフェイス自体またはメソッドのシグネチャーに、変更はありません。しかし、動作には変更がいくつかあります。このリリースでは First Broker Login フローを追加し、 メソッド IdentityProviderMapper.importNewUser は First Broker Login フローが完了した後に呼び出されるようになりました。そのため、Review Profile ページ任意の属性を利用できるようにするには、 importNewUser の代わりに preprocessFederatedIdentity メソッドを使用する必要があります。 BrokeredIdentityContext.setUserAttribute を呼び出して属性を設定することができ、それを Review profile ページで利用できます。

Keycloakの古いバージョンでは、リフレッシュ・トークンを何回でも再利用することができました。Keycloakではこの再利用はいまだに許可されていますが、 Revoke refresh token オプションでこれを許可しないこともできます。このオプションは管理コンソールのトークン設定配下にあります。新しいアクセス・トークンが取得するためにリフレッシュ・トークンが使用された場合、新しいリフレッシュ・トークンもそこに含まれることになります。オプションが有効である場合は、次にアクセス・トークンがリフレッシュされた際に、この新しいリフレッシュ・トークンを使用する必要があります。古いリフレッシュ・トークンを何回も再利用することはできません。

いくつかのパッケージの構成と名前を少し変更しました。主にutilクラスの内部パッケージ名の変更です。アプリケーション（たとえば、AccessTokenまたはKeycloakSecurityContext）で使用される最も重要なクラスとSPIは変更されていません。ただし、影響を受けたりクラスのインポートを更新する必要がでてきたりする可能性がわずかながらあります。たとえば、multitenancyとKeycloakConfigResolverを使用している場合は、HttpFacadeクラスが別のパッケージ（これは現時点では org.keycloak.adapters.spi.HttpFacade です。）に移動されたのと同じように、影響を受けます。

このリリースにはオフライン・トークンのサポートを追加しました。つまり、 "offline" ユーザー・セッションは現在データベース内で永続化されているということです。オフライン・トークンを使用していない場合は、何も永続化されていませんので、 DBに追加で書き込むとパフォーマンスが低下するのではないかと心配する必要はありません。しかし、いかなる場合でも、 standalone/configuration/keycloak-server.json を更新し、以下のように userSessionPersister を追加する必要があります。

昔のRDBMSの代わりに、Mongo内でセッションを永続化させたい場合は、 mongo プロバイダーを代用してください。

Infinispanは現在デフォルトでレルムとユーザーのキャッシュ・プロバイダーのみとなっています。非クラスターモードでは、ローカルのInfinispanキャッシュが使用されます。また、カスタムのイン・メモリー・キャッシュと非キャッシュ・プロバイダーは削除しました。realmCacheまたはuserCacheがkeycloak-server.jsonでmemまたはnoneに設定されている場合は、それらを削除してください。Infinispanは、realmCacheとuserCacheのオブジェクトを必要としなくなった唯一のプロバイダーなので、それらを削除することができます。

Infinispanは現在デフォルトで唯一のユーザー・セッション・プロバイダーです。非クラスター・モードでは、ローカルのInfinispanキャッシュが使用されます。また、JPAとMongoユーザー・セッション・プロバイダーを削除しました。ユーザー・セッションをkeycloak-server.jsonでmem、jpaまたはmongoに設定している場合、それを削除してください。Infinispanは、ユーザー・セッションのオブジェクトを必要としなくなった唯一のプロバイダーなので、それを削除することができます。

ユーザー・セッションの耐久性を上げたい場合、ユーザー・セッション・キャッシュを一人以上の所有者で設定するか、または複製したキャッシュを使用します。また、Infinispanを設定してキャッシュを保持させる方法でも可能です。ただし、パフォーマンスに影響を与える可能性があります。

デフォルトのテーマでは、登録ページとアカウント管理からコンタクト詳細を現在削除してあります。管理コンソールには、特定のコンタクト属性だけでなく、現在すべてのユーザー属性がリスト表示されます。また、管理コンソールには、ユーザーに属性を追加したり削除したりする機能があります。コンタクト詳細を追加する場合は、サンプルに含まれているアドレス・テーマを参照してください。

以前は、ダイレクト・グラントAPI（またはリソース・オーナー・パスワード・クレデンシャル）はデフォルトで無効となっており、レルムのオプションによってそれを有効にすることができました。現在は、ダイレクト・グラントAPIは常に有効で、レルムで有効または無効にできるオプションは削除されています。

データベースの変更はほとんどありません。アップグレードする前にデータベースを忘れずバックアップしてください。

UserFederationProviderインターフェイスの変更はわずかなマイナーチェンジのみです。新しいバージョンにアップグレードする際に実装を同期させ、シグネチャーを変更したいくつかのメソッドをアップグレードする必要があるかもしれません。変更は本当にわずかですが、フェデレーションのパフォーマンスを上げるために必要でした。

最新リリースで実行された配布物の変更に伴って、現在Keycloakのスタンドアローン・ダウンロードはWildFly 9.0.0.Finalに基づいています。また、これはオーバーレイにも影響を及ぼし、WildFly 9.0.0.FinalまたはJBoss EAP6.4.0.GAにのみこのオーバーレイをデプロイすることができるようになりました。WildFly 8.2.0.Finalはサーバー用にサポートされなくなりました。

下記のとおり、WildFly、JBoss EAPおよびJBoss AS7用の3つの別のアダプター・ダウンロードがあります。

適切なものを選ぶよう注意してください。

また、拡張モジュールとサブシステム定義が変更されたので、standalone.xmlを更新する必要があります。詳しくは、Securing Applications and Services Guideを参照してください。

現在、Keycloakは3つのダウンロードで使用することができます。スタンドアローン、オーバーレイおよびデモ・バンドルの3つになります。スタンドアローンはプロダクションと非JEE開発者用に作られたものです。オーバーレイは既存のWildFly 8.2またはEAP 6.4環境へのKeycloakの追加を目的としており、主に開発用に作られたものです。最後にデモ（または開発）バンドルについてですが、これは開発者がKeycloakをはじめられるように作られたものです。このバンドルには、Keycloakサーバーとアダプターだけでなく、WildFlyサーバーも含まれます。また、すべてのドキュメントとサンプルも含まれています。

このリリースには、データベース上の変更点がいくつかあります。最も大きな変更は、アプリケーションとOAuthのクライアントのマージです。アップグレードする前に、データベースを忘れずにバックアップしてください。

現在、アプリケーションとOAuthクライアントは Clients にマージされています。管理コンソールのUIは更新されており、データベースも同様です。データベースのデータは自動的に更新されます。以前に設定されたアプリケーションは Consent required スイッチがオフのクライアントに変換され、OAuthクライアントはこのスイッチがオンのクライアントに変換されます。

このリリースには、データベース上の変更点がいくつかあります。アップグレードする前に、データベースを忘れずにバックアップしてください。

アクセス・トークンとIDトークン内の iss クレームの値は、 realm name から realm url へ変更されました。これはOpenID Connectの仕様の要求によるものです。アダプターを使用している場合は変更の必要はありませんが、 auth-server-url を指定せずにbearer-onlyだけを使用していた場合は変更する必要があります。別のライブラリ（またはRSATokenVerifier）を使用している場合は、 iss の検証時に対応できるよう変更を加える必要があります。

OpenID Connect仕様に合わせるために、認証とトークンのエンドポイントは、単一の認証エンドポイントと単一のトークン・エンドポイントを持つように変更されました。仕様どおりに response_type と grant_type パラメーターが使用され、必要なフローを選択できるようになります。古いエンドポイント( /realms/{realm-name}/protocols/openid-connect/login , /realms/{realm-name}/protocols/openid-connect/grants/access , /realms/{realm-name}/protocols/openid-connect/refresh , /realms/{realm-name}/protocols/openid-connect/access/codes )は現在廃止されており、今後の新しいバージョンでは削除されます。

テーマのレイアウトを変更しました。以前はディレクトリーの階層は type/name でしたが、現在は name/type に変更されています。たとえば、 sunrise という名前のログイン・テーマは、以前は standalone/configuration/themes/login/sunrise にデプロイされていましたが、現在は standalone/configuration/themes/sunrise/login に移されています。この変更は、同じテーマの異なるタイプのグループを1つのフォルダに保存するのを簡単にするために実施しました。

以前は、テーマをJARとしてデプロイした場合、Javaコードが必要なカスタム・テーマ・ローダーを作成する必要がありました。現在は、これが簡略化され、簡単なテキストファイル（ META-INF/keycloak-themes.json ）だけで、JARに含まれるテーマを記述できるようになりました。

以前は、アプリケーションとOAuthクライアント用に、管理コンソール内に Claims タブがありました。これは、特定のアプリケーションまたはクライアント用に、どの属性をアクセストークンに入れるのかを設定するために使用していました。このタブは削除され、より柔軟性が高いプロトコル・マッパーに置き換えました。

以前のバージョンからのデータベースの移動については気にする必要はありません。RDBMSとMongoの両方用の移行スクリプトの実行により、特定のアプリケーションまたはクライアント用に設定されたクレームは、対応するプロトコル・マッパーに変更されるようになりました（そうは言っても、新しいバージョンに移行する前にDBをバックアップしておいた方が安全です）。以前のバージョンからエクスポートされたJSONの記述についても、同様になります。

ソーシャル・プロバイダーSPIを、リファクタリングしてアイデンティティー・ブローカリングSPIに置き換えました。この方が柔軟性が高いです。管理コンソール内の Social タブは Identity Provider タブに名前が変更されました。

また、クレーム/プロトコル・マッパーと同様に、以前のバージョンからのデータベース移行について気にする必要はありません。ソーシャル・プロバイダーの設定とユーザーへの "social links" の両方は、対応するアイデンティティー・プロバイダーに変換されます。

実施すべきことは、特定のサード・パーティーのソーシャル・プロバイダーの管理コンソール内にある許可済みの Redirect URI に変更することのみです。まず、Keycloak管理コンソールに移動し、アイデンティティー・プロバイダーを設定したページからRedirect URIをコピーします。次に、サード・パーティーのプロバイダーの管理コンソール（たとえばFacebookの管理コンソール）に、許可されたRedirect URIとしてこれをペーストするだけです。