Upgrading Guide

スタンドアローン・モード用のアップグレード・スクリプトを実行するには、以下の手順に従います。

スタンドアローン-高可用性（HA）モードでは、インスタンスはすべて同時にアップグレードされる必要があります。

スタンドアローン-HAモードのアップグレード・スクリプトを実行するには、以下の手順に沿って行います。

ドメインモードでは、インスタンスはすべて同時にアップグレードされる必要があります。

ドメインモードでアップグレード・スクリプトを実行するには、以下の手順に沿って行います。

ドメイン・クラスター・モードでは、インスタンスはすべて同時にアップグレードされる必要があります。

ドメイン・クラスター・モードでアップグレード・スクリプトを実行するには、以下の手順に沿って行います。

データベース・スキーマの自動アップグレードを有効にするには、デフォルトのconnectionsJpaプロバイダーのmigrationStrategyプロパティー値を"update"に設定します。

または、このCLIコマンドを実行します。

データベース・スキーマが新バージョンに変更されていた場合、この設定でサーバーを起動すると、データベースは自動的に移行されます。

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

または、このCLIコマンドを実行します。

この設定でサーバーを起動すると、データベースを移行する必要があるかどうか確認されます。必要な変更はSQLファイルに書き込まれ、確認およびデータベースに対する手動実行が可能です。このファイルをデータベースに適用する方法についての詳細は、利用しているリレーショナル・データベース用のドキュメントを参照してください。ファイルに変更が書き込まれると、サーバーは終了します。

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

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

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

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

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

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

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

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

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

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

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

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

サンプルとして、下記のとおりdiffコマンドを使用します。

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

WildFly 20をコンテナーとして使用するように、Keycloakサーバーがアップグレードされました。これは、特定の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 値に更新する作業を行っています。トークン表現には、さらに問題があります。これは、JSON表現で int はデフォルトで 0 になることを意味しますが、これを含めることはできません。

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

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

WildFly 18をコンテナーとして使用するように、Keycloakサーバーがアップグレードされました。これは、特定のKeycloakサーバーの機能には直接関係しませんが、移行に関連する若干の変更（言及する価値がある変更）があります。

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

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

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

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

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

WildFly 17をコンテナーとして使用するように、Keycloakサーバーがアップグレードされました。これは、特定のKeycloakサーバーの機能には直接関係しませんが、移行に関連する若干の変更（言及する価値がある変更）があります。

WildFly 16をコンテナーとして使用するように、Keycloakサーバーがアップグレードされました。これは、特定の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が使用されるかを推測できないため、リクエストの転送は実行されません。

WildFly 15をコンテナーとして使用するように、Keycloakサーバーがアップグレードされました。これは、特定の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 ポータルにクライアント・アプリケーションを再度登録する必要があります。

WildFly 14をコンテナーとして使用するように、Keycloakサーバーがアップグレードされました。これは、特定のKeycloakサーバーの機能には直接関係しませんが、移行に関連する若干の変更があります。

WildFly 13をコンテナーとして使用するように、Keycloakサーバーがアップグレードされました。これは、特定の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 を追加しました。この追加により、新規ユーザーがアイデンティティー・プロバイダー（またはソーシャル・プロバイダー）を介してログインした際に、厳密に何を実行する必要があるのかを指定できるようになりました。この一環として、 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としてこれをペーストするだけです。