Keycloakのアップグレード

このガイドでは、Keycloakをアップグレードする方法について説明します。最初にKeycloakサーバーを、次にKeycloakアダプターをアップグレードすることが推奨されます。

アップグレードする前に、手順をよく読み移行に伴う変更に示された変更を十分に確認してください。

Keycloakサーバーのアップグレード

アップグレードする準備

アップグレードする前に、踏まなければならない手順がありますので、その順序に気をつけてください。特に、アダプターをアップグレードする前に、必ずKeycloakサーバーをアップグレードしてください。

Keycloakのマイナー・アップグレードでは、すべてのユーザー・セッションが失われます。アップグレード後は、すべてのユーザーが再度ログインする必要があります。

手順
  1. 古いインストール(設定、テーマなど)をバックアップします。

  2. リレーショナル・データベースのドキュメントに記載されている手順で、データベースをバックアップします。

  3. Keycloakサーバーをアップグレードします。

    アップグレード後のデータベースは、旧サーバーとの互換性がなくなります。

  4. アップグレードを元に戻す必要がある場合は、まず古いインストールを復元してから、バックアップのコピーからデータベースを復元します。

  5. アダプターをアップグレードします。

Keycloakサーバーのアップグレード

アダプターをアップグレードする前に、Keycloakサーバーをアップグレードすることが重要です。

前提条件
  • 開いているトランザクションを処理し、data/tx-object-store/トランザクション・ディレクトリーを削除します。

手順
  1. 新しいサーバー・アーカイブをダウンロードします。

  2. ダウンロードしたアーカイブを移したい場所に移動させます。

  3. アーカイブを展開します。この手順により、最新のKeycloakのリリースのクリーンなインスタンスがインストールされます。

  4. 以前のインストールから conf/providers/themes/ を新しいインストールにコピーします。

データベースの移行

Keycloakでは、データベース・スキーマの移行は自動的にできますが、手動でも行うことができます。デフォルトでは、新規インストールディレクトリーでの初回起動時に自動的にデータベースが移行されます。

自動リレーショナル・データベース移行

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

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

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

kc.[sh|bat] start --spi-connections-liquibase-default-index-creation-threshold=300000

手動リレーショナル・データベース移行

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

kc.[sh|bat] start --spi-connections-jpa-legacy-migration-strategy=manual

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

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

kc.[sh|bat] start --spi-connections-jpa-legacy-migration-export=<path>/<file.sql>

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

テーマの移行

カスタム・テーマを作成した場合、それらを新しいサーバーに移行する必要があります。組み込みのテーマの変更については、カスタマイズした項目に応じて、カスタム・テーマに反映させる必要があります。

古いサーバーの themes ディレクトリーから、新しいサーバーの themes ディレクトリーにカスタム・テーマをコピーする必要があります。その後、以下の変更を確認し、その変更をカスタムテーマに適用させる必要があるかどうか検討しなければなりません。

要約すると、以下のとおりになります。

  • テンプレートをカスタマイズした場合、基本テーマのテンプレートと比較して、適用する必要のある変更があるかどうかを確認しなければなりません。

  • スタイルをカスタマイズし、Keycloakテーマを拡張している場合、そのスタイルへの変更を確認する必要があります。基本テーマを拡張している場合は、この手順をスキップすることができます。

  • メッセージをカスタマイズした場合、キーまたは値を変更するか、メッセージを追加する必要があります。

テンプレートの移行

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

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

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

更新版のログイン・テーマのテンプレートとサンプルのカスタム・ログイン・テーマのテンプレートの比較

theme migration meld info 1

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

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

古いインストール・ディレクトリーのログイン・テーマ・テンプレートと更新されたバージョンのログイン・テーマ・テンプレートの比較

theme migration meld info 2

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

メッセージの移行

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

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

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

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

スタイルの移行

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

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

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

$ diff KEYCLOAK_HOME_OLD/themes/keycloak/login/resources/css/login.css \
KEYCLOAK_HOME_NEW/themes/keycloak/login/resources/css/login.css

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

Keycloakアダプターのアップグレード

まずKeycloakサーバーをアップグレードし、次にアダプターをアップグレードすることが重要です。以前のバージョンのアダプターは、それ以降のバージョンのKeycloakサーバーで動作しますが、以前のバージョンのKeycloakサーバーは、それ以降のバージョンのアダプターでは動作しません。

古いアダプターとの互換性

前述したとおり、新しいリリース・バージョンのKeycloakサーバーは、古いバージョンのアダプターとともに動作するようにサポートしています。ただし、Keycloakサーバー側に修正を含める必要があり、古いバージョンのアダプターとの互換性が損なわれることがあります。たとえば、OpenID Connectの新しい仕様を実装しても、古いバージョンのクライアント・アダプターはそれを認識できません。

そのような場合のために、互換モードを追加しました。OpenID Connectクライアントの場合、Keycloak管理コンソールのクライアントの詳細が表示されたページに、 OpenID Connect Compatibility Modes という名前のセクションがあります。ここでは、古いクライアント・アダプターとの互換性を維持するために、Keycloakサーバーの新しい機能を無効にすることができます。詳細は、各スイッチのツールチップを参照してください。

EAPアダプターのアップグレード

手順

WildFlyアダプターをアップグレードするには、以下の手順に沿って行います。

  1. 新しいアダプター・アーカイブをダウンロードします。

  2. WILDFLY_HOME/modules/system/add-ons/keycloak/ ディレクトリーを削除することで、以前のアダプター・モジュールを削除します。

  3. ダウンロードしたアーカイブを WILDFLY_HOME に解凍します。

JavaScriptアダプターのアップグレード

WebアプリケーションにコピーされたJavaScriptアダプターをアップグレードするには、以下の手順で行います。

手順
  1. 新しいアダプター・アーカイブをダウンロードします。

  2. ダウンロードしたアーカイブ内にあるkeycloak.jsファイルで、アプリケーションのkeycloak.jsファイルを上書きします。

Node.jsアダプターのアップグレード

WebアプリケーションにコピーされたNode.jsアダプターをアップグレードするには、以下の手順で行います。

手順
  1. 新しいアダプター・アーカイブをダウンロードします。

  2. 既存のNode.jsアダプター・ディレクトリーを削除します。

  3. 更新されたファイルをその場所に解凍します。

  4. アプリケーションのpackage.json内のkeycloak-connectの依存関係を変更します。

Keycloak Admin Clientのアップグレード

まずKeycloakサーバーをアップグレードし、次にadmin-clientをアップグレードすることが重要です。以前のバージョンのadmin-clientは、それ以降のバージョンのKeycloakサーバーで動作しますが、以前のバージョンのKeycloakサーバーは、それ以降のバージョンのadmin-clientでは動作しません。使用されているKeycloakサーバーのバージョンと一致するバージョンのadmin-clientを使用することをお勧めします。

移行に伴う変更

22.0.4への移行

電子メール・ローカル・パートの最大長を指定する新しいパラメーター

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

kc.[sh|bat] start --spi-user-profile-declarative-user-profile-max-email-local-part-length=100 ...

22.0.2への移行

クライアントの詳細設定コンボからNever expiresオプションを削除

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

新しいLinkedIn OpenID Connectソーシャル・プロバイダー

新しい 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 と呼ばれる非推奨の機能で、デフォルトでは無効になっています。これは将来のバージョンで削除される予定です。必要であれば、以下のように起動時に再度有効にしてください。

kc.[sh|bat] start --features linkedin-oauth ...

22.0.0への移行

Java EEからJakarta EEへの移行

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

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

  • Jakarta Persistence 3.1

  • Jakarta RESTful Web Services 3.1

  • Jakarta Mail API 2.1

  • Jakarta Servlet 6.0

  • Jakarta Activation 2.1

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

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

Quarkus 3へのアップグレード

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のビルトインサポートです。

quarkus.hibernate-orm.* プロパティーが機能しなくなりました

Quarkus 3では、Hibernate ORMの設定は、 persistence.xml ファイルかQuarkusのプロパティーで指定する必要がありますが、両方で指定することはできません。そのため、 quarkus.hibernate-orm で始まる名前を持つデフォルトの永続化ユニットに対して、Quarkusの設定プロパティーでKeycloakのJPAストアの設定を上書きすることはできなくなりました。

Hibernate ORM 6へのアップグレード

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

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

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

Keycloak JSアダプターからのレガシーPromise APIの削除

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

以降前:
const keycloak = new Keycloak();

keycloak.init()
  .success(function(authenticated) {
    alert(authenticated ? 'authenticated' : 'not authenticated');
  }).error(function() {
    alert('failed to initialize');
  });
移行後:
const keycloak = new Keycloak();

keycloak.init()
  .then(function(authenticated) {
    alert(authenticated ? 'authenticated' : 'not authenticated');
  }).catch(function() {
    alert('failed to initialize');
  });
あるいは、以下のように await キーワードを使用して、これらのPromiseを解くこともできます。
const keycloak = new Keycloak();

try {
  const authenticated = await keycloak.init();
  alert(authenticated ? 'authenticated' : 'not authenticated');
} catch (error) {
  alert('failed to initialize');
}

エクスポートとインポートによる自動ビルドの実行

以前のリリースでは、 export コマンドと import コマンドは、最初に build コマンドを実行する必要がありました。このリリースから、 exportimport コマンドはビルド時間設定が変更された場合にKeycloakの自動再構築を行うようになりました。

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

以下の例では、データベース・パスワードのようなランタイム・パラメーターが、設定ファイルまたは環境変数によって提供されることを想定しています。

移行前:エクスポート・コマンドを実行する前にビルドコマンドを実行する
bin/kc.[sh|bat] build --db=postgres ...
bin/kc.[sh|bat] export --dir <dir>
移行後:エクスポート・コマンドに --optimized を追加する
bin/kc.[sh|bat] build --db=postgres ...
bin/kc.[sh|bat] export --optimized --dir <dir>
移行後:オートビルド機能を活用する
bin/kc.[sh|bat] export --dir <dir> --db=postgres ...
注意

自動ビルドが実行されると、 --optimized フラグで開始されたコマンド( start コマンドを含む)以降のすべてのコマンドでビルド時間オプションが有効になります。

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

Keycloak管理クライアントのアーティファクトの名称変更

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 です。

Jakarta EEサポート
以降前:
<dependency>
    <groupId>org.keycloak</groupId>
    <artifactId>keycloak-admin-client-jakarta</artifactId>
    <version>21.0.0</version>
</dependency>
移行後:
<dependency>
    <groupId>org.keycloak</groupId>
    <artifactId>keycloak-admin-client</artifactId>
    <version>22.0.0</version>
</dependency>
Java EEサポート
以降前:
<dependency>
    <groupId>org.keycloak</groupId>
    <artifactId>keycloak-admin-client</artifactId>
    <version>21.0.0</version>
</dependency>
移行後:
<dependency>
    <groupId>org.keycloak</groupId>
    <artifactId>keycloak-admin-client-jee</artifactId>
    <version>22.0.0</version>
</dependency>

パススルー・プロキシー・モードの変更

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 の変更点

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

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

LDAPStorageProvider の検索の変更点

このリリースから、Keycloakは連携されたLDAPデータベースのクエリー時にページネーション機構を使用します。ユーザーの検索は、ローカル・データベースの検索と一貫性があるべきです。

このリリースでは、 LDAPStorageProviderUserQueryProvider ではなく、 UserQueryMethodsProvider のみを実装しています。

Keycloak OpenID Connectアダプターの非推奨化

このリリースから、以下のKeycloak OpenID Connectアダプターの開発には時間を投資しないことになりました。

  • Keycloak WildFly OpenID Connectアダプター

  • Keycloak JEE サーブレットOpenID Connectアダプター

  • Keycloak Spring Boot OpenID ConnectアダプターとKeycloak Spring Security OpenID Connectアダプター

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

上記の参照先から、アプリケーションを代替手段に移行することをお勧めします。これらのアダプターは将来のリリースでは利用できなくなる予定です。

Keycloak JEE SAMLアダプターの非推奨化

Keycloak JEE SAMLアダプターは廃止され、このリリース以降の開発には時間を投資しないことになりました。

公式のアダプターは現在、Jakarta EEの仕様に基づいており、アプリケーションをこのテクノロジーに切り替える際には、すぐに使用する必要があります。

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

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

openshift-integration機能の変更点

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

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

OpenShiftの拡張機能は、Keycloakチームによって公式にサポートおよびメンテナンスされていません。自己責任でのみ使用できます。
Http Challengeフローの削除

組み込みの認証フロー http challenge は、オーセンティケーターの実装 no-cookie-redirectbasic-auth 、および basic-auth-otp と共に削除されました。 http challenge 認証フローは、OpenShiftの統合も意図されていたため、上記の関連機能と共に削除されました。オーセンティケーターの実装は、前の段落で説明されているOpenshift拡張機能に移動されました。

もし、http challenge フローをレルムのフローとして、または First Broker Login フローまたは Post Broker Login フローとして、いずれかのアイデンティティー・プロバイダーに使用している場合、移行は不可能です。移行前に、レルムの設定を更新して http challenge フローの使用を排除するようにしてください。もし、http challenge フローをクライアントの Authentication Flow Binding Override として使用している場合、移行は完了しますが、そのクライアントにログインすることはできなくなります。移行後、新しい/異なるフローを使用するようにクライアントの設定を再作成する必要があります。

サードパーティーの依存関係の削除

openshift-integrationの削除により、Keycloakの配布物からいくつかのサードパーティーの依存関係を削除することができます。これには、 openshift-rest-clientokio-jvmokhttpcommons-langcommons-compressjboss-dmr 、および kotlin-stdlib が含まれます。つまり、これらのライブラリーをKeycloakサーバーにデプロイされた独自のプロバイダーの依存関係として使用している場合、これらの jar ファイルをKeycloakの配布物の providers ディレクトリーに明示的にコピーする必要がある場合があります。

JAX-RSリソースに対して、コンテキストと依存性の注入が無効になりました。

より良いランタイムを提供し、基礎となるスタックを可能な限り活用するために、javax.ws.rs.core.Context アノテーションを使用したコンテキスト・データの注入ポイントはすべて削除された。期待される性能の改善には、リクエストのライフサイクル中にプロキシーのインスタンスを複数回生成する必要がなくなり、実行時のリフレクションコードの量が劇的に減ることが含まれます。

次のSPIのいずれかを拡張している場合は、以下のようにしてください。

  • PolicySpi

  • AdminRealmResourceSpi

  • IdentityProviderSpi

  • RealmResourceSPI

カスタムのJAX-RS(サブ)リソースを確認して、次のようにコンテキストデータを取得してください。

KeycloakSession session = org.keycloak.common.util.Resteasy.getContextData(KeycloakSession.class);

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

@Context
org.jboss.resteasy.spi.HttpRequest request;
@Context
org.jboss.resteasy.spi.HttpResponse response;

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

KeycloakSession session = // obtain the session, which is usually available when creating a custom provider from a factory
KeycloakContext context = session.getContext();

HttpRequest request = context.getHttpRequest();
HttpResponse response = context.getHttpResponse();

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

KeycloakSession session = org.keycloak.common.util.Resteasy.getContextData(KeycloakSession.class);

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

KeycloakSession session = // obtain the session
KeycloakContext context = session.getContext();
MyContextualObject myContextualObject = context.getContextObject(MyContextualObject.class);

カスタムJAX-RSリソースのアップグレード

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

  • PolicySpi

  • AdminRealmResourceSpi

  • IdentityProviderSpi

  • RealmResourceSPI

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

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

プロバイダーからの非推奨メソッドとモデル

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

  • RealmModel#searchForGroupByNameStream(String, Integer, Integer) は削除されました。

  • UserProvider#getUsersStream(RealmModel, boolean) は削除されました。

  • UserSessionPersisterProvider#loadUserSessions(int, int, boolean, int, String) は削除されました。

  • ストリーム化作業のために追加されたインターフェイスは削除されました。例えば、 RoleMapperModel.Streams などです。

  • Streams インターフェイスは、フェデレーテッド・ストレージ・プロバイダー・クラスで非推奨となりました。

  • KeycloakModelUtils#getClientScopeMappings は削除されました。

  • KeycloakSession の非推奨メソッドは削除されました。

  • UserQueryProvider#getUsersStream メソッドは削除されました。

複数のKeycloakインスタンス

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

k8s.keycloak.org/v2alpha1の変更

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

KeycloakはIPv4/IPv6デュアルスタックをサポートしています。

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

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

21.1.0への移行

クラスパス上でデフォルトで利用できるJavaScriptエンジン

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

Service Account ClientのデフォルトのクライアントIDマッパーの変更

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

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

Keycloak JSアダプターは new 演算子でインスタンス化する必要があります

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

const keycloak = Keycloak();

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

const keycloak = new Keycloak();

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

21.0.2への移行

利用規約のユーザー属性の移行

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

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

21.0.0への移行

メトリクスにマイクロメーターを採用

Keycloakは、Prometheusフォーマットでメトリクスをエクスポートするメトリクス・エンドポイントをオプションで提供しています。このリリースでは、このデータを提供する実装がSmallRyeからMicrometerに変更されました。これは、 Quarkusの推奨メトリクスライブラリー です。

この変更に伴い、メトリクスの名称が変更されました。以下の表は、その一例です。

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

Table 1. 変更されたメトリクス名の例
旧メトリック名 新メトリックス名

base_gc_total

jvm_gc_pause_seconds_count

base_gc_time_total_seconds

jvm_gc_pause_seconds_sum

base_thread_count

jvm_threads_live_threads

vendor_agroal_*

agroal_*

SAMLのRSA_SHA1およびDSA_SHA1アルゴリズムが非推奨

SAMLアダプター、クライアント、アイデンティティー・プロバイダーで 署名アルゴリズム として設定できる RSA_SHA1DSA_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-sha1http://www.w3.org/2000/09/xmldsig#dsa-sha1 などのアルゴリズムを削除することが考えられます。

SAML SPメタデータの変更

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

これには、以下の2つの方法があります。

  • どちらかが、より新しいバージョンのKeycloakによって生成されたメタデータでIDP設定を更新します、

  • または、Keycloakを後方互換モードで実行すると、Keycloakの古いバージョンで生成されたメタデータでKeycloakが動作するようになります。このモードは -Dkeycloak.saml.deprecated.encryption=true フラグを使用して有効にすることができます。なお、この後方互換モードは、Keycloak 24で削除される予定です。

ユーザー・セッション・プロバイダーの非推奨メソッドが削除されました

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

旧管理コンソールを使用したカスタムテーマが動作しなくなります

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

Curlはコンテナーから削除されました

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

20.0.0への移行

RESTEasyのバージョンアップ

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

H2のバージョンアップ

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

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

H2 JDBC URLの変更

H2バージョン2.xのJPAレガシーストアでKeycloakを動作させるには、JDBC URLに NON_KEYWORDS=VALUE という属性が必要です。

H2が余分なパラメーターなしでKeycloakによって初期化されるセットアップでは、Keycloakは自動的に属性を付加します。これは、開発セットアップのデフォルトです。

H2 JDBC URLがコマンドラインまたは設定ファイルで提供され、そのJDBC URLにすでに NON_KEYWORDS= 属性が含まれている場合、この属性を VALUE キーワードで修正する必要があります。

H2データベースのコネクション・ファクトリーがKeycloakの外部で初期化される場合、その初期化で NON_KEYWORDS 属性を追加する必要があります。

詳しくはH2ドキュメント on NON_KEYWORDS attribute を参照してください。

H2データベース・ファイルのアップグレード

H2バージョン1.xで作成したH2データベースベース・ファイルは、バージョン2.xでは使用しないでください。

既存のH2データベースファイルをパージして空のデータベースから始め、Keycloakのエクスポートおよびインポート機能を使ってレルムをエクスポートおよびインポートするか、 H2データベースプロジェクトのウェブサイトの移行ノート を参照して、H2データベースのコンテンツを移行してください。

新バージョンのKeycloak Operatorでの主な変更点

最新バージョンのKeycloak Operatorを使用するためには、CRの手動再インストールとバージョンアップが必要です。自動移行はありません。

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

serverConfigurationの自由形式のフィールドの名前が変更されました。

これからは additionalOptions という名前になります。この決定の背景には、KeycloakのQuarkusのディストリビューションとより一致させ、命名の一貫性を達成/維持するための考えがあります。 serverConfiguration は、Keycloakのカスタムリソース(CR)で宣言された代替手段を持たないオプションを設定するために、まだ使用することができます。このような使い方の良い例として、サービス・プロバイダーがあります。

イングレスのオプションが洗練されました

以前は、 disableDefaultIngress プロパティーで定義していました。このため、今後は以下のような構造でイングレス設定を制御することができます。

spec:
    ...
    ingress:
      enabled: false
HTTPオプションが追加されました

ingressと同様に、以下のように複数のHTTPオプションをより構造的に定義することができます。

spec:
    ...
  http:
    httpEnabled: true
    httpPort: 80
    httpsPort: 443
    tlsSecret: my-tls-secret
ホスト名オプションが追加されました

以下のように、ホスト名のオプションも変更されました。

spec:
    ...
  hostname:
    hostname: [keycloak-server-hostname]
    admin: [admin-console-hostname]
    adminUrl: [admin-console-base-url]
    strict: [true|false]
    strictBackchannel: [true|false]
一部の項目は必須ではなくなりました

Quarkusの配布設定に合わせるため、 hostnametlsSecret フィールドはオプションになりました。これに伴い、これらのフィールドに INSECURE-DISABLE という特別な値を設定することもできなくなりました。ホスト名のチェックを無効にしてHTTPを有効にするには、Quarkusディストリビューションと同じアプローチで、 strict: falsestrictBackchannel: falsehttpEnabled: true フィールドを設定してください。

OLMのチャンネルが高速に変更されました

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

データ・プロバイダーやモデルから非推奨のメソッドが削除されました

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

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

  • Streamification - インターフェイスがStreamベースのメソッドのみを含むようになりました。

    たとえば、 GroupProvider インターフェイスの場合

    @Deprecated
    List<GroupModel> getGroups(RealmModel realm);

    was replaced by

    Stream<GroupModel> getGroupsStream(RealmModel realm);

    ストリーム化作業の詳細は、 KEYCLOAK-14011 に記載されています。

  • 一貫したパラメーター順序 - メソッドは、常に RealmModel を最初のパラメーターとする厳格なパラメーター順序を持つようになりました。

    たとえば、 UserLookupProvider インターフェイスの場合

    @Deprecated
    UserModel getUserById(String id, RealmModel realm);,

    was replaced by

    UserModel getUserById(RealmModel realm, String id)
変更されたインターフェイスの一覧

( o.k.org.keycloak. パッケージの略)

  • server-spi module

    • o.k.credential.CredentialInputUpdater

    • o.k.credential.UserCredentialStore

    • o.k.models.ClientProvider

    • o.k.models.ClientSessionContext

    • o.k.models.GroupModel

    • o.k.models.GroupProvider

    • o.k.models.KeyManager

    • o.k.models.KeycloakSessionFactory

    • o.k.models.ProtocolMapperContainerModel

    • o.k.models.RealmModel

    • o.k.models.RealmProvider

    • o.k.models.RoleContainerModel

    • o.k.models.RoleMapperModel

    • o.k.models.RoleModel

    • o.k.models.RoleProvider

    • o.k.models.ScopeContainerModel

    • o.k.models.UserCredentialManager

    • o.k.models.UserModel

    • o.k.models.UserProvider

    • o.k.models.UserSessionProvider

    • o.k.models.utils.RoleUtils

    • o.k.sessions.AuthenticationSessionProvider

    • o.k.storage.client.ClientLookupProvider

    • o.k.storage.group.GroupLookupProvider

    • o.k.storage.user.UserLookupProvider

    • o.k.storage.user.UserQueryProvider

  • server-spi-private module

    • o.k.events.EventQuery

    • o.k.events.admin.AdminEventQuery

    • o.k.keys.KeyProvider

すべての変更は、以下の issue にリンクされています。

19.0.2への移行

OpenID Connectのログアウトプロンプト

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

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

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

bin/kc.[sh|bat] --spi-login-protocol-openid-connect-suppress-logout-confirmation-screen=true start

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

この後方互換性スイッチは、将来のバージョン(おそらくKeycloak 23)で削除される予定です。このスイッチに依存するのではなく、上記のようにできるだけ早くクライアントを更新することが推奨されます。

SAML JavaScriptプロトコル・マッパーによるスクリプトのデプロイ

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

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

UserInfoエンドポイントの変更

エラーレスポンスの変更

UserInfo エンドポイントは、 RFC 6750(The OAuth 2.0 Authorization Framework: Bearer Token Usage) に完全に準拠したエラーレスポンスを返すようになりました。エラーコードと説明(利用可能な場合)は、JSONオブジェクト・フィールドではなく、 WWW-Authenticate チャレンジ属性として提供されます。レスポンスは、エラー状態に応じて、以下のようになります。

  • アクセストークンが提供されていない場合は、以下のようになります。

    401 Unauthorized
    WWW-Authenticate: Bearer realm="myrealm"
  • アクセストークンを提供するために複数のメソッドを同時に使用した場合(例:Authorizationヘッダー+POSTアクセストークン・パラメーター)、またはPOSTパラメーターが重複している場合は、以下のようになります。

    400 Bad Request
    WWW-Authenticate: Bearer realm="myrealm", error="invalid_request", error_description="..."
  • アクセストークンがない場合、以下のように openid スコープを使用します。

    403 Forbidden
    WWW-Authenticate: Bearer realm="myrealm", error="insufficient_scope", error_description="Missing openid scope"
  • UserInfo レスポンスの署名/暗号化のための暗号鍵が解決できない場合は、以下のようになります。

    500 Internal Server Error
  • トークン検証エラーの場合、 401 Unauthorizedinvalid_token エラーコードとセットで返されます。このエラーは、ユーザーとクライアントに関連するチェックを含み、実際には以下のように残りのすべてのエラーケースを捕捉します。

    401 Unauthorized
    WWW-Authenticate: Bearer realm="myrealm", error="invalid_token", error_description="..."
その他の変更点
  • これは、UserInfoがOAuth 2.0ではなくOpenID Connectに特有の機能であることから規定されたものです。トークンに openid スコープがない場合、リクエストは 403 Forbidden で拒否されます(上記を参照)。

  • UserInfoがユーザーのステータスをチェックするようになり、ユーザーが無効になっている場合は invalid_token レスポンスを返すようになりました。

19.0.0への移行

新しい管理コンソールがデフォルトのコンソールになりました

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

bin/kc.sh start-dev --features-disabled=admin2

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

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

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

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

サーバーの設定と起動方法の変更

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

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

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

kc.sh start --optimized

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

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

ヘルス・エンドポイントの動作不良を起こす可能性のある変更

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

  • /q/health

  • /q/health/live

  • /q/health/ready

  • /q/metrics

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

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

  • /health

  • /health/live

  • /health/ready

  • /metrics

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

  • liveness probeに使用される health/live エンドポイントは、現在のグッド・プラクティスに合わせ、 health/ready エンドポイントと同じ動作をしないよう、データベース接続のヘルスチェックから切り離されました。その結果、/health/live を呼び出したときにデータベースチェックが checks: 配列に表示されなくなり、データベースに異常が発生しても、liveness probeはHTTPステータス コード200と「UP」のステータスを返すため、ポッドの再起動は発生しません。

  • readiness probeに使用される health/ready エンドポイントでは、データベース接続が機能しているかどうかが依然としてチェックされます。データベースのチェックを有効にするために、 health-enabled=true だけでなく metrics-enabled=true も設定されていることを確認し、結果として有効なreadiness probeとなります。データベース接続が健全な状態でない場合、HTTPステータスコード503と「DOWN」のステータスを返します。

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

GELFを使った変更/ログの集中型管理

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

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

デベロッパーに影響を与える変更点

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

変更の理由

たとえば、Keycloakクラスターのアップグレードには、Keycloakのダウンタイムが必要です。この限界に対処するために、徹底的なリファクタリングが開始されました。

このバージョンでの変更は、主にストレージのリファクタリングと、マップストレージと呼ばれる新しいストレージの準備に関連するものです。このストレージは、最終的に現在のストレージを置き換えるもので、このバージョンでは legacy store と呼ばれる予定です。レガシーストアは、さらにいくつかのバージョンでKeycloakで利用できるようになる予定です。

新しいストアでは、サービス層とストレージ層の間に厳格な責任分担を課しています。そのため、サービス層はオブジェクトの出所に関する可視性を制限され、キャッシュされたオブジェクトとされないオブジェクト、ローカルストレージとフェデレートストレージから発生したオブジェクトを区別することができなくなります。

ユーザーストレージSPIは、非推奨となります。これは、ユーザー、ロール、クライアント、グループなど、認識された任意の領域に対してカスタムストレージを作成する機能を提供します。

レガシーストアでサービスが利用できる詳細レベルに依存している拡張機能は、レガシーストアの全廃止期間中、この能力を維持するための調整が必要です。次のセクションでは、その調整方法について説明します。

レガシーストアとマップストアの使用は相互に排他的であり、一方のストアがアクティブである間は使用できません。

モジュール構成の変更

新しいストレージ機能を導入する一環として、 KeycloakSession のストレージ機能に関するいくつかのパブリックAPIが統合され、一部は非推奨となり、次のバージョンで削除される予定です。3つの新しいモジュールが導入され、 server-spiserver-spi-privateservices モジュールからデータ指向のコードが以下に移動されました。

org.keycloak:keycloak-model-legacy

ユーザー・ストレージAPIなど、レガシーストアのすべての公開APIが含まれます。

org.keycloak:keycloak-model-legacy-private

ストレージの *Manager クラスなど、ユーザー・ストレージ管理に関連するプライベートな実装が含まれます。

org.keycloak:keycloak-model-legacy-services

レガシーストアを直接操作し、新しいストアでは意味を持たないすべてのRESTエンドポイントを含んでいます。

これらのモジュールは、レガシーストアがサポートされる限り、利用可能です。それ以降は、削除されます。

この変更は、Wildflyディストリビューションの既存のユーザーストレージ・プロバイダーの配備に影響します。ユーザー・ストレージプロバイダーがWARアーカイブとしてデプロイされている場合、以下のように変更された依存関係を記載した META-INF/jboss-deployment-structure.xml ファイルをそのアーカイブに追加する必要があります。

<jboss-deployment-structure xmlns="urn:jboss:deployment-structure:1.2">
    <deployment>
        <dependencies>
            <module name="org.keycloak.keycloak-model-legacy" meta-inf="import"/>
        </dependencies>
    </deployment>
</jboss-deployment-structure>
KeycloakSession の変更点

KeycloakSession が簡略化されました。いくつかのメソッドは KeycloakSession で非推奨となっており、将来のバージョンで削除される予定です。

たとえば UserProvider には users()userLocalStorage()userCache()userStorageManager()userFederatedStorage() が含まれます。この状況は、各メソッドの正確な意味を理解しなければならない開発者にとっては混乱するかもしれませんし、現在のストアのレイアウトに依存します。新しいストアは、連携ストレージとローカル・ストレージを区別していません。

これらの理由から、 users() メソッドだけが KeycloakSession に残され、上に挙げた他のすべての呼び出しを置き換える必要があります。残りのメソッドは非推奨であり、いずれは削除されるでしょう。同じパターンの非推奨が、 clients()groups() など、他のオブジェクト領域のメソッドにも適用されます。また、 *StorageManager()*LocalStorage() で終わるすべてのメソッドは、新しいストアで直接置き換えることができないため、呼び出されると例外が発生するようになりました。次のセクションでは、これらの呼び出しを新しいAPIに移行する方法、または古いストアを使用しながらレガシーAPIを使用する方法について説明します。

KeycloakSessionの非推奨のメソッドは、将来のリリースで削除される予定です。 keycloak-model-legacy-* モジュールは、より長い期間利用でき、最終的には削除される予定です。

レガシーストアに依存しない既存プロバイダーの移行

既存のプロバイダーは、非推奨のメソッドを呼び出さないのであれば、移行する必要はありません(ほとんどのプロバイダーがそうであるはずです)。

プロバイダーが非推奨のメソッドを使用しているが、ローカルストレージと非ローカルストレージに依存しない場合、現在非推奨の userLocalStorage() から users() というメソッドに呼び出しを変更することが最良の選択肢となります。新しいメソッドでは、ローカル・セットアップでキャッシュが有効になっている場合、キャッシュを含むため、ここでセマンティクスが変化することに注意してください。

移行前:非推奨のAPIにアクセスすると、例外が発生するようになりました。
session.userLocalStorage();
移行後:新しいAPI呼び出し元へのアクセスは、レガシーストレージAPIに依存しません。
session.users();
レガシーストアに依存する既存プロバイダーの移行

カスタム・プロバイダーが特定のプロバイダーのモードを区別する必要がある場合、非推奨のオブジェクトへのアクセスは LegacyStoreManagers データストア・プロバイダーを使用することによって提供されるまれなケースです。このオプションは、レガシーモジュールがデプロイの一部である場合にのみ利用可能です。

移行前:非推奨のAPIにアクセスすると、例外が発生するようになりました。
session.userLocalStorage();
移行後:LegacyStoreManagers APIで旧機能にアクセスします。
((LegacyDatastoreProvider) session.getProvider(DatastoreProvider.class)).userLocalStorage();

ユーザー・ストレージに関連するいくつかのAPIは、利便性のために org.keycloak.storage.UserStorageUtil でラップされています。

カスタム・ストレージ・プロバイダーの作成

カスタム・ストレージ・プロバイダーを作成するためのAPIは、テクニカル・プレビューとして利用可能ですが、まだ完全に安定化されていません。詳細は MapStorageProvider SPIとそのJavadocを参照してください。新しいAPIを利用できるようにすることは、次のKeycloakのバージョンにとって優先事項です。

RealmModel の変更点

getUserStorageProvidersgetUserStorageProvidersStreamgetClientStorageProvidersgetClientStorageProvidersStreamgetRoleStorageProvidersgetRoleStorageProvidersStream メソッドは削除されました。これらのメソッドに依存し、レガシー・ストレージを有効にして実行するコードは、次のようにインスタンスをキャストする必要があります。

移行前:APIが変更されたため、コードがコンパイルされません。
realm.getClientStorageProvidersStream()...;
移行後:レガシーインターフェースにインスタンスをキャストします。
((LegacyRealmModel) realm).getClientStorageProvidersStream()...;

同様に、これまで RealmModel というインターフェースを実装していたコードで、これらのメソッドを提供したい場合は、新しいインターフェイス LegacyRealmModel を実装する必要があります。このインターフェイスは RealmModel のサブ・インターフェイスであり、以下の古いメソッドを含んでいます。

移行前:コードは古いインターフェイスを実装します。
public class MyClass extends RealmModel {
    /* might not compile due to @Override annotations for methods no longer present
       in the interface RealmModel. /
    / ... */
}
移行後:コードは新しいインターフェイスを実装します。
public class MyClass extends LegacyRealmModel {
    /* ... */
}
インターフェイス UserCache はレガシーモジュールに移されました

オブジェクトのキャッシュ状態はサービスに委ねられるため、  UserCache インターフェースは keycloak-legacy モジュールに移動されました。そのため、session.userCache() を呼び出すと、UserProvider のみを返すようになります(これは画期的な変更点です)。

レガシーな実装に依存するコードは UserCache に直接アクセスする必要があります。レガシーストアのキャッシュが使用されている間はこのような呼び出しが必要かもしれませんが、新しいマップストアを使用する際には、キャッシュが透過的に処理されるため、必要ありません。

移行前:戻り値の型が変更されたため、コードがコンパイルされません。
// session.userCache() might return null, null-check omitted for brevity.
session.userCache().evict(realm, user);
移行後:APIを直接利用します。
// session.getProvider(UserCache.class) might return null, null-check omitted for brevity.
session.getProvider(UserCache.class).evict(realm, user);

レルムの無効化をトリガーするには、UserCache APIを使用する代わりに、以下のようにイベントをトリガーすることを検討してください。

移行前:戻り値の型が変更されたため、コードがコンパイルされません。
UserCache cache = session.getProvider(UserCache.class);
if (cache != null) cache.clear();
移行後:無効化APIを利用します。
session.invalidate(InvalidationHandler.ObjectType.REALM, realm.getId());
ユーザーのクレデンシャルの管理

ユーザーのクレデンシャルは、これまで session.userCredentialManager().method(realm, user, ...) を使って管理していました。新しい方法では user.credentialManager().method(...) を活用します。この形式では、クレデンシャル機能をユーザーのAPIに近づけ、レルムとストレージに関するユーザーのクレデンシャルの位置の事前知識に依存しないようにします。

古いAPIは非推奨となり、レガシー・ストレージがデプロイメントで有効になっている場合にのみ動作するようになりました。新しいAPIは、古いストレージと新しいストレージの両方で動作します。

移行前:非推奨のAPIにアクセスします
session.userCredentialManager().createCredential(realm, user, credentialModel)
移行後:新しいAPIにアクセスします
user.credentialManager().createStoredCredential(credentialModel)

カスタム UserStorageProvider には、UserModel を返す際に実装する必要がある新しいメソッド credentialManager() が存在します。これらのプロバイダーはレガシーなステージが有効な環境で動作するため、 LegacyUserCredentialManager のインスタンスを返す必要があります:

移行前: UserModel が必要とする新しいメソッド credentialManager() のために、コードがコンパイルされません。
public class MyUserStorageProvider implements UserLookupProvider, ... {
    /* ... */
    protected UserModel createAdapter(RealmModel realm, String username) {
        return new AbstractUserAdapter(session, realm, model) {
            @Override
            public String getUsername() {
                return username;
            }
        };
    }
}
移行後:レガシーストアのAPI UserModel.credentialManager() を実装します。
public class MyUserStorageProvider implements UserLookupProvider, ... {
    /* ... */
    protected UserModel createAdapter(RealmModel realm, String username) {
        return new AbstractUserAdapter(session, realm, model) {
            @Override
            public String getUsername() {
                return username;
            }

            @Override
            public SubjectCredentialManager credentialManager() {
                return new LegacyUserCredentialManager(session, realm, this);
            }
        };
    }
}

レガシーなKeycloak Operatorで podDisruptionBudget が非推奨になりました。

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

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

apiVersion: policy/v1
kind: PodDisruptionBudget
metadata:
  labels:
    app: keycloak
  name: keycloak
spec:
  maxUnavailable: 1
  selector:
    matchLabels:
      component: keycloak

Kubernetes Documentation もご参照ください。

新しいKeycloak Operatorでのデプロイの変更。

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

18.0.0への移行

ステップアップ認証

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

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

  • ステップアップ認証機能を使用する予定はありませんが、トークンの acr クレームに依存している場合は、 step_up_authentication 機能を無効にすることができます。通常認証の場合は 1、SSO認証の場合は 0 という値でクレームが追加されます。

  • 管理REST APIまたは管理コンソールを使って、クライアントに acr クライアント・スコープを手動で追加してください。これは、特にステップアップ認証を使用する場合に必要です。もし、レルム内に多数のクライアントがあり、すべてのクライアントに acr クレームを使用したい場合は、DBに対してこのようなSQLをトリガーすることができます。ただし、Keycloakがすでに起動している場合は、キャッシュをクリアするか、サーバーを再起動することを忘れないようにしてください。

insert into CLIENT_SCOPE_CLIENT (CLIENT_ID, SCOPE_ID, DEFAULT_SCOPE) select CLIENT.ID as CLIENT_ID, CLIENT_SCOPE.ID as SCOPE_ID, true as DEFAULT_SCOPE
from CLIENT_SCOPE, CLIENT where CLIENT_SCOPE.REALM_ID='test' and CLIENT_SCOPE.NAME='acr' and CLIENT.REALM_ID='test' and CLIENT.PROTOCOL='openid-connect';

OpenID Connectログアウト

以前のバージョンの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_hintpost_logout_redirect_uri パラメーターに置き換えることを検討してください。

  • Javaアダプターを使用していて、アプリケーションが httpServletRequest.logout() を呼び出してログアウトする場合、この呼び出しはログアウト・エンドポイントのバックチャネル型を使っていて、そのエンドポイントは変更されていないので、影響を受けません。

  • アプリケーションが最新のJavaScriptアダプターを使用している場合は、影響を受けません。しかし、古いバージョンのJavaScriptアダプターを使用している場合、このアダプターは非推奨の redirect_uri パラメーターを持つログアウト・エンドポイントの変種を使用しているため、影響を受けます。この場合、JavaScriptアダプターを最新バージョンにアップグレードする必要があるかもしれません。

  • Node.jsアダプターについては、JavaScriptアダプターと同じ指針が適用されます。古いバージョンのアダプターでは、非推奨の redirect_uri パラメーターを使用しているため、最新版に更新することを推奨します。最新のNode.js アダプターでは、ドキュメントやNode.jsアダプターのサンプルにあるように /logout URLに基づいてログアウトする限り、影響を受けることはありません。ただし、アプリケーションが keycloak.logoutUrl メソッドを直接使用する場合は、このメソッドの第2引数に idTokenHint を追加することを検討するとよいでしょう。このバージョンでは、第二引数に idTokenHint を追加できるようになりました。 idTokenHint には、ログイン時に取得した有効なIDトークンを指定する必要があります。 idTokenHint の追加は任意ですが、省略した場合、前述のようにログアウト画面の確認が必要になります。また、ログアウト後にアプリケーションにリダイレクトされることもありません。

後方互換性オプションがあり、アプリケーションは redirect_uri パラメーターの古い形式をまだ使用することができます。

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

bin/kc.[sh|bat] --spi-login-protocol-openid-connect-legacy-logout-redirect-uri=true start

この設定でも、 redirect_uri パラメーターを使用したフォーマットを使用することができます。 id_token_hint が省略された場合は、確認画面が必要になることに注意してください。

この後方互換性スイッチは、将来のバージョン(おそらくKeycloak 23)で削除される予定です。このスイッチに依存するのではなく、上記のようにできるだけ早くクライアントを更新することが推奨されます。

upload-scripts 機能の削除

Keycloakの以前のバージョンでは、管理コンソールやREST APIなどの管理インターフェイスを通じてJavaScriptコードを管理することができました。このバージョンから、これは不可能となり、以下のプロバイダーを設定するために、スクリプトをサーバーにデプロイする必要があります。

  • OpenID Connectスクリプト・マッパー

  • スクリプト・オーセンティケーター(認証エグゼキューション)

  • JavaScriptポリシー

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

kc.[sh|bat] start --auto-build --features=preview

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

一般的に、レルムを更新する手順は以下の通りです。

  • アップグレードする前に、使用しているスクリプト・プロバイダーを削除してください。

  • アップグレード後は、 ドキュメント の指示に従ってスクリプトをデプロイしてください。

  • サーバーに配置されたスクリプトから作成されたプロバイダーを使用するように、認証フロー、マッパー、およびクライアントの認証設定を更新してください。

アカウント・コンソールのPatternflyのアップグレード

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コンポーネントのプロパティーを更新することで対応できるはずです。

リソースは以下です。

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

  • Alert

  • action propが actionClose に変更されました。

  • Expandable

  • ExpandableSection に名称を変更しました。

  • Title

  • size属性が TitleSizes を使用するようになりました。

  • DataListContent

  • noPaddinghasNoPadding に変更されました。

  • Grid、Stack、Level、Gallery

  • gutter 属性が hasGutter に変更されました。

  • Modal

  • サイズ制御を isLarge などから ModalVariant を使用するように変更しました(例: variant={ModalVariant.large} )。

  • Select

  • ariaLabelTypeAheadtypeAheadAriaLabel に変更しました。

  • isExpandedisOpen に変更しました。

  • ariaLabelledByaria-labelledby に変更しました。

  • DataListContent

  • noPaddinghasNoPadding に変更しました。

Quarkusディストリビューション:metrics-enabledオプションをhealth-enabledとmetrics-enabledに分割

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

17.0.0への移行

Quarkusによるデフォルトのディストリビューション

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

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

  • レガシー・ディストリビューション・タグ用のコンテナイメージが変更されました。レガシー・ディストリビューションを使用するには、 legacy または 17.0.0-legacy というタグを使用してください。

  • レガシー・ディストリビューションのWebサイトでのダウンロードが keycloak-legacy-17.0.0.[zip|tar.gz] に変更されました。

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

プレビュー版Quarkusディストリビューションからの移行

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

  • コンテナーが quay.io/keycloak/keycloak:latestquay.io/keycloak/keycloak:17.0.0 にパブリッシュされるようになりました。

  • Webサイトでのダウンロードは keycloak-17.0.0.[zip|tar.gz] に名称変更されました。

  • conf/keycloak.propertiesconf/keycloak.conf に変更し、設定ファイルとCLI引数の設定キーを統一しました。

  • build optionsruntime configuration をより明確に分離しました。

  • カスタムのQuarkus設定は、 conf/quarkus.properties を使用して行います。

  • h2-memh2-file のデータベースは dev-memdev-file に名前を変更しました。

  • 機能の有効化・無効化は、各機能に個別の設定キーを持つ以前の方法に代わって、 --features--features-disabled を使用するようになりました。

  • ランタイム設定を kc.[sh|bat] build に渡すことができなくなり、ビルドの中で保持されなくなりました。

  • ログレベルとフォーマットが --log-level--log-format で設定できるようになりましたが、以前はサポートされていないQuarkusのプロパティーを使用して設定する必要がありました。

クライアント・ポリシーの移行 : client-scopes

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

Liquibaseをバージョン4.6.2にアップグレードしました。

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

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

16.0.0への移行

WildFly 25 アップグレード

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

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

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

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

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

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

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

プロキシー環境変数

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

Keycloak Operatorで非推奨の機能

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

サポートされていないのMetrics Extensionを含むKeycloak Operatorの例

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

14.0.0への移行

クライアント・ポリシーの移行

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

13.0.0への移行

必要な手動での移行の手順

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

<extension module="org.wildfly.extension.microprofile.config-smallrye"/>
<extension module="org.wildfly.extension.microprofile.health-smallrye"/>
<extension module="org.wildfly.extension.microprofile.metrics-smallrye"/>
<subsystem xmlns="urn:wildfly:microprofile-config-smallrye:1.0"/>
<subsystem xmlns="urn:wildfly:microprofile-health-smallrye:2.0" security-enabled="false" empty-liveness-checks-status="${env.MP_HEALTH_EMPTY_LIVENESS_CHECKS_STATUS:UP}" empty-readiness-checks-status="${env.MP_HEALTH_EMPTY_READINESS_CHECKS_STATUS:UP}"/>
<subsystem xmlns="urn:wildfly:microprofile-metrics-smallrye:2.0" security-enabled="false" exposed-subsystems="*" prefix="${wildfly.metrics.prefix:wildfly}"/>

WildFly 23へのアップグレード

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

依存関係の更新

依存関係が、WildFly 23サーバーによって使用されるバージョンに更新されました。たとえば、Infinispanは現在 11.0.9.Final です。

設定の変更

standalone(-ha).xmldomain.xml にはいくつかの設定変更があります。設定ファイルの自動移行を処理するには、Keycloakサーバーのアップグレードセクションに従ってください。ただし、独自の設定変更を行った場合に必要となる可能性がある最も重要な変更は次のとおりです。

  • Infinispanキャッシュコンテナーの module 属性は deprecated (未使用)となり、 modules 属性に 置き換わり 、このキャッシュ・コンテナーの設定に関連付けられたモジュールのセットを表します。さらに、ベースになるコンテナーとしてWildfly 23を使用したことにより、さまざまな要素の属性に追加の変更が加えられました。たとえば、 managed-executor-service 要素と managed-scheduled-executor-service 要素は、新しい hung-task-termination-period 属性を認識するようになりました。詳細については、 the Wildfly 23 full model reference を参照してください。

WildFly 22へのアップグレード

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

依存関係の更新

依存関係が、WildFly 22サーバーによって使用されるバージョンに更新されました。たとえば、Infinispanは現在 11.0.8.Final です。

設定の変更

standalone(-ha).xmldomain.xml にはいくつかの設定変更があります。設定ファイルの自動移行を処理するには、Keycloakサーバーのアップグレードセクションに従ってください。ただし、独自の設定変更を行った場合に必要となる可能性がある最も重要な変更は次のとおりです。

12.0.2への移行

読み取り専用属性

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

  • カスタム・ユーザー・ストレージ・プロバイダー

  • カスタム・オーセンティケーター

  • ユーザー属性に基づいて認可を確立するカスタムJavaScript認可ポリシー

  • X.509証明書をユーザーIDにマッピングするためのカスタム属性を持つX.509オーセンティケーター

  • その他のカスタム機能(単純なユーザー・プロファイル情報ではなく、認証/認可/アイデンティティーのコンテキストを保持するためのメタデータとして、一部のユーザー属性が使用される個所)。

See the details in the Threat model mitigation chapter

Valid Request URIs

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

13.0.0への移行

WildFly 22へのアップグレード

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

依存関係の更新

依存関係はWildfly 22サーバーで使用されるバージョンに更新されました。たとえば、Infinispanは現在 11.0.8.Final です。

設定の変更

standalone(-ha).xmldomain.xml にはいくつかの設定変更があります。設定ファイルの自動移行を処理するには、Keycloakサーバーのアップグレードセクションに従ってください。たとえば、自分で設定を変更したため、より詳細な情報が必要な場合を考慮して、最も重要な変更の一覧を以下に示します。

12.0.0への移行

WildFly 21へのアップグレード

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

依存関係の更新

依存関係が、WildFly 21サーバーによって使用されるバージョンに更新されました。たとえば、Infinispanは現在 11.0.4.Final です。

設定の変更

standalone(-ha).xmldomain.xml にはいくつかの設定変更があります。設定ファイルの自動移行を処理するには、Keycloakサーバーのアップグレードセクションに従ってください。ただし、独自の設定変更を行った場合に必要となる可能性がある最も重要な変更は次のとおりです。

  • Infinispanキャッシュの object-memory 要素は 非推奨 (未使用)になり、 heap-memory 要素に置き換えられました。

Dockerプロトコル認証用のユーザー・セッションの作成をスキップします

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

PatternFly 4へのアップグレード

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 のスイッチを使用します。

11.0.0への移行

WildFly 20へのアップグレード

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

依存関係の更新

依存関係が、WildFly 20サーバーによって使用されるバージョンに更新されました。たとえば、Infinispanは現在 10.1.8.Final です。

設定の変更

standalone(-ha).xmldomain.xml にはいくつかの設定変更があります。設定ファイルの自動移行を処理するには、Keycloakサーバーのアップグレードセクションに従ってください。

クロス・データセンター・レプリケーションの変更
  • Infinispanサーバーをバージョン9.4.19にアップグレードする必要があります。旧バージョンでも動作する可能性はありますが、テストがされていないため、保証はできません。

  • Infinispanのキャッシュを設定する際には、remote-store要素に追加された protocolVersion プロパティーを使用することをお勧めします。Infinispanサーバー 9.4.18に接続する場合、KeycloakサーバーとInfinispanサーバーではInfinispanライブラリーのバージョンが異なりますので、hotrodプロトコルの推奨バージョンは2.9となります。詳しくは、Cross-Datacenterのドキュメントを参照してください。

  • サブシステム connectionsInfinispan の下にある remoteStoreSecurityEnabled プロパティーを使用することをお勧めします。詳細については、Cross-Datacenterのドキュメントを参照してください。

LDAPインポートしないバグの修正

以前のバージョンのKeycloakでは、 Import Users がオフのLDAPプロバイダーが設定されている場合、非LDAPマップ属性の一部が変更されていてもユーザーを更新することが可能でした。この状況は、混乱を与える動作となっていました(属性が更新されているように見えても、更新されなかった)。現在のバージョンでは、LDAP以外のマップされた属性が変更された場合、更新はまったく実行できません。

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

UserModelの変更

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

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

Instagram IdPが新しいAPIに移行

古いレガシー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_endpointintrospection_endpoint )を公開していました。後者は、 RFC-8414 で定義されているものです。前者は非推奨でしたが、現在は削除されています。

9.0.1への移行

JavaScriptアダプターのレガシーPromise

JavaScriptアダプターでpromiseTypeを設定する必要がなくなり、両方を同時に使用できるようになりました。レガシーAPI( successerror )はいつか削除されるため、できるだけ早くネイティブPromise API( thencatch )を使用するようにアプリケーションを更新することをお勧めします。

重複する最上位グループ

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

SELECT REALM_ID, NAME, COUNT(*) FROM KEYCLOAK_GROUP WHERE PARENT_GROUP is NULL GROUP BY REALM_ID, NAME HAVING COUNT(*) > 1;

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

9.0.0への移行

ユーザーロケールの処理の改善

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

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

トークン表現Javaクラスの非推奨メソッド

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

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

8.0.2への移行

より多くの認証フローの変更

REQUIREDとALTERNATIVEの実行は同じフローではサポートされません

以前のバージョンでは、同じレベルの同じ認証フロー内にREQUIREDとALTERNATIVEのエグゼキューションを設定することが可能でした。このアプローチにはいくつかの問題があり、認証SPIでリファクタリングを行いました。つまり、これはもはや有効とは見なされません。ALTERNATIVEとREQUIREDのエグゼキューションが同じレベルで設定されている場合、ALTERNATIVEのエグゼキューションは無効と見なされます。そのため、最新バージョンに移行すると、既存の認証フローは自動的に移行され、前のバージョンと同じ動作が維持されます。一部のREQUIREDのエグゼキューションと同じレベルのALTERNATIVEのエグゼキューションが含まれている場合、ALTERNATIVEのエグゼキューションは別のREQUIREDサブフローに追加されます。これにより、前のバージョンと同様に、特定の認証フローの動作が同じまたは同様になります。認証フローの設定を再確認してテストし、すべてが期待どおりに機能することを再確認することを常にお勧めします。この推奨事項は、カスタム・オーセンティケーターの実装を使用してさらにカスタマイズされた認証フローがある場合に特に当てはまります。

8.0.0への移行

新しいデフォルト・ホスト名プロバイダー

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

WildFly 18へのアップグレード

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

依存関係の更新

依存関係が、WildFly 18サーバーによって使用されるバージョンに更新されました。たとえば、Infinispanは現在9.4.16.Finalです。

設定の変更

standalone(-ha).xmldomain.xml にはいくつかの設定変更があります。設定ファイルの自動移行を処理するには、Keycloakサーバーのアップグレードセクションに従ってください。

クロス・データセンター・レプリケーションの変更
  • Infinispanサーバーをバージョン9.4.19にアップグレードする必要があります。旧バージョンでも動作する可能性はありますが、テストがされていないため、保証はできません。

サーバーへのスクリプトのデプロイ

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

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

JavaScriptアダプターのクライアント・クレデンシャル

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

認証フローの変更

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

OPTIONALのエグゼキューションのRequirementが削除されました

移行に関して最も重要な変更は、認証のエグゼキューションからOPTIONALの要件のサポートを削除し、それをCONDITIONALの要件に置き換えることです。これにより、柔軟性が高まります。前のバージョンで構成された既存のOPTIONALのオーセンティケーターは、CONDITIONALのサブフローに置き換えられます。これらのサブフローには、最初のエグゼキューションとして設定された Condition - User Configured 条件があり、2回目のエグゼキューションとして以前のOPTIONALオーセンティケーター(たとえば、 OTP Form )が設定されます。ユーザーの観点からは、認証中の動作は以前のバージョンと同じです。

Java SPIの変更

Java Authentication SPIおよびCredential Provider SPIにはいくつかの変更があります。インターフェース Authenticator は変更されませんが、新しいクレデンシャル・タイプ( CredentialModel のサブクラス)を導入するより高度なオーセンティケーターを開発している場合は影響を受ける可能性があります。 CredentialProvider インターフェイスに変更があり、 CredentialValidator のようないくつかの新しいインターフェイスが導入されています。また、オーセンティケーターがOPTIONALのエグゼキューションのRequirementをサポートしている場合、影響を受ける可能性があります。詳細については、サーバー開発ガイドの最新の認証の例を再確認することをお勧めします。

Freemarkerテンプレートの変更

Freemarkerテンプレートにもいくつかの変更があります。ログインフォームまたは一部のアカウント・フォーム、特にOTPに関連するフォームのカスタムFreemarkerテンプレートを使用した独自のテーマがある場合、影響を受ける可能性があります。最新のKeycloakのFreemarkerテンプレートの変更を再確認し、それに応じてテンプレートを調整することをお勧めします。

ユーザー・クレデンシャルの変更

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

7.0.0への移行

WildFly 17へのアップグレード

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

依存関係の更新

依存関係が、WildFly 17サーバーによって使用されるバージョンに更新されました。たとえば、Infinispanは現在9.4.14.Finalです。

設定の変更

standalone(-ha).xmldomain.xml にはいくつかの設定変更があります。設定ファイルの自動移行を処理するには、Keycloakサーバーのアップグレードセクションに従ってください。

クロス・データセンター・レプリケーションの変更
  • Infinispanサーバーをバージョン9.4.19にアップグレードする必要があります。旧バージョンでも動作する可能性はありますが、テストがされていないため、保証はできません。

6.0.0への移行

WildFly 16へのアップグレード

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

依存関係の更新

依存関係が、WildFly 16サーバーによって使用されるバージョンに更新されました。たとえば、Infinispanは現在9.4.8.Finalです。

設定の変更

standalone(-ha).xmldomain.xml にはいくつかの設定変更があります。設定ファイルの自動移行を処理するには、Keycloakサーバーのアップグレードセクションに従ってください。

クロス・データセンター・レプリケーションの変更
  • Infinispanサーバーをバージョン9.4.19にアップグレードする必要があります。旧バージョンでも動作する可能性はありますが、テストがされていないため、保証はできません。

新しいオプションのクライアント・スコープ

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

prompt=noneをデフォルトのIDPに伝播する機能

転送されてきた 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が使用されるかを推測できないため、リクエストの転送は実行されません。

5.0.0への移行

WildFly 15へのアップグレード

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

依存関係の更新

依存関係が、WildFly 15サーバーによって使用されるバージョンに更新されました。たとえば、Infinispanは現在9.4.3.Finalです。

設定の変更

standalone(-ha).xmldomain.xml にはいくつかの設定変更があります。設定ファイルの自動移行を処理するには、Keycloakサーバーのアップグレードセクションに従ってください。

クロス・データセンター・レプリケーションの変更
  • Infinispanサーバーをバージョン9.4.19にアップグレードする必要があります。旧バージョンでも動作する可能性はありますが、テストがされていないため、保証はできません。

4.8.2への移行

Google Identity ProviderはGoogle Sign-in認証システムを使用するように更新されました

バージョン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 Social BrokerがLinkedIn APIのバージョン2に更新されました

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

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

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

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

4.6.0への移行

新しいデフォルト・クライアント・スコープ

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

Protocol Mapper SPIの追加

これに関連して、(サポートされていない)Protocol Mappers SPIにはわずかな追加があります。カスタムのProtocolMapperを実装した場合にのみ影響を受ける可能性があります。ProtocolMapperインターフェイスに新しい getPriority() メソッドが導入されました。このメソッドは、デフォルトの実装が0を返すように設定しています。プロトコル・マッパーの実装がアクセストークンの realmAccess または resourceAccess プロパティーにあるロールに依存している場合は、マッパーの優先度を高くする必要があります。

オーディエンスの解決

認証されたユーザーが少なくとも一つのクライアントロールを持つすべてのクライアントのオーディエンスは、現在アクセストークンの aud クレームに自動的に追加されます。一方、アクセストークンは、それが発行されたフロントエンド・クライアントのAudienceを自動的に含まない場合があります。詳しくは Server Administration Guide を参照してください。

JavaScriptアダプターのPromise

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

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

Microsoft Identity ProviderはMicrosoft Graph APIを使用するように更新されました

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

依存関係の更新

依存関係が、WildFly 14サーバーによって使用されるバージョンに更新されました。たとえば、Infinispanは現在9.3.1.Finalです。

設定の変更

standalone(-ha).xmldomain.xml にはいくつかの設定変更があります。設定ファイルの自動移行を処理するには、Keycloakサーバーのアップグレードセクションに従ってください。

クロス・データセンター・レプリケーションの変更
  • Infinispanサーバーをバージョン9.4.19にアップグレードする必要があります。旧バージョンでも動作する可能性はありますが、テストがされていないため、保証はできません。

4.4.0への移行

WildFly 13へのアップグレード

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

依存関係の更新

依存関係が、WildFly 13サーバーによって使用されるバージョンに更新されました。たとえば、Infinispanは現在9.2.4.Finalで、Undertowは2.0.9.Finalです。

設定の変更

standalone(-ha).xmldomain.xml にはいくつかの設定変更があります。設定ファイルの自動移行を処理するには、Keycloakサーバーのアップグレードセクションに従ってください。ただし、独自の設定変更を行った場合に必要となる可能性がある最も重要な変更は次のとおりです。

  • infinispanキャッシュ上の eviction 要素は 廃止 され(未使用)、 object-memory 要素に置き換えられました。

  • Infinispanサブシステムの cache-container 要素は jndi-attribute認識しなくなりました

クロス・データセンター・レプリケーションの変更
  • Infinispanサーバーをバージョン9.4.19にアップグレードする必要があります。旧バージョンでも動作する可能性はありますが、テストがされていないため、保証はできません。

  • Infinispanサーバー設定ファイルでセキュリティーを設定する必要はありません。

  • transaction 要素は、Infinispanサーバーのレプリケーションされたキャッシュの設定から削除する必要があります。これは、infinispanバグ https://issues.redhat.com/browse/ISPN-9323 の対策のために必要です。

4.3.0への移行

ホスト名の設定

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

4.0.0への移行

クライアント・テンプレートがクライアント・スコープに変更されました

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

クライアント・テンプレートがクライアント・スコープに変更されました

クライアント・テンプレートがクライアント・スコープに変更されました。クライアント・テンプレートがあれば、そのプロトコル・マッパーとロールスコープのマッピングは保持されます。

名前の中の空白文字の置き換え

名前に空白文字を含むクライアント・テンプレートの名前は、スペースをアンダースコアに置き換えた名前に変更されました。これは、クライアント・スコープの名前に空白文字が使用できないためです。たとえば、クライアント・テンプレート my template はクライアントスコープ my_template に変更されます。

クライアントへのクライアント・スコープのリンク

クライアント・テンプレートを持つクライアントの場合、対応するクライアント・スコープがクライアントに Default Client Scope として追加されます。したがって、プロトコル・マッパーとロール・スコープ・マッピングはクライアント上に保持されます。

既存のクライアントにリンクされていないレルム・デフォルト・クライアント・スコープ

移行中に、ビルトインのクライアント・スコープのリストが各レルムに追加されます。また、 Realm Default Client Scopes のリストも追加されます。ただし、既存のクライアントはアップグレードされず、新しいクライアント・スコープは自動的に追加されません。また、すべてのプロトコル・マッパーとロール・スコープ・マッピングは、既存のクライアントに保持されます。新しいバージョンでは、新しいクライアントを作成すると、Realm Default Client Scopesが自動的に付属され、プロトコル・マッパーは付属されません。移行中に既存のクライアントを変更することはありません。たとえば、クライアントのプロトコル・マッパーなどのカスタマイズを適切に検出することが不可能なためです。既存のクライアントを更新する場合(それらからプロトコル・マッパーを削除してクライアント・スコープとリンクする場合)、手動で行う必要があります。

同意を再度確認する必要があります

クライアント・スコープの変更は、同意のリファクタリングを必要としました。同意はクライアント・スコープを指し、ロールやプロトコル・マッパーは指しません。この変更により、ユーザーが以前に確認した永続的な同意はもはや有効ではなく、ユーザーは移行後に同意ページを再度確認する必要があります。

一部の設定スイッチが削除されました

Scope Param Required がRole Detailから削除されました。 Consent RequiredConsent Text のスイッチがプロトコル・マッパーの詳細から削除されました。これらのスイッチはクライアント・スコープ機能に置き換えられました。

認可サービスの変更

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

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

Authorization APIが削除されました

UMA 2.0以前(UMA 1.0)では、クライアント・アプリケーションがAuthorization APIを使用して、RPTの形式でサーバーからパーミッションを取得していました。新しいバージョンのUMA仕様では、Authorization APIが削除され、Keycloakからも削除されました。UMA 2.0では、特定の認可タイプを使用してトークン・エンドポイントからRPTを取得できるようになりました。詳細は、 Authorization Services Guide を参照してください。

Entitlement APIが削除されました

UMA 2.0の導入により、KeycloakからRPTを取得し、異なるAPIを使用することを避けるように、トークン・エンドポイントとUMAグラントタイプを活用することにしました。Entitlement APIによって提供される機能はこれまでどおり、リソースまたはスコープが提供されていない場合でも、1つ以上のリソースとスコープのセット、またはサーバーからのすべてのパーミッションを取得できます。詳細は、 Authorization Services Guide を参照してください。

UMA Discoveryエンドポイントの変更

UMA Discoveryドキュメントが変更されました。詳細は Authorization Services Guide を参照してください。

Keycloak認可JavaScriptアダプターの変更

以前と同じ動作を維持しながら、UMA 2.0によって導入された変更に準拠するように、Keycloak認可JavaScriptアダプター(keycloak-authz.js)が変更されました。主な変更点は、認可リクエストを表す特定のオブジェクト・タイプを想定する authorization メソッドと entitlement メソッドの両方を呼び出す方法です。この新しいオブジェクト・タイプは、UMAグラントタイプでサポートされているさまざまなパラメーターをサポートすることにより、サーバからパーミッションを取得するより柔軟な方法を提供します。詳細は、 Authorization Services Guide を参照してください。

このリリースで導入された主な変更の1つは、(UMAを使用しない場合)リソースサーバーによって保護されたリソースにアクセスするために、アクセストークンをRPTと交換する必要がなくなったことです。ポリシー・エンフォーサーがリソースサーバー側でどのように設定されているかに応じて、通常のアクセストークンをベアラートークンとして送信するだけで、パーミッションは引き続き適用されます。
Keycloak認可クライアントJava APIの変更

新しいバージョンのKeycloak認可クライアントJava APIにアップグレードすると、いくつかのRepresentationクラスが org.keycloak:keycloak-core の別のパッケージに移動されたことに気付くでしょう。

3.4.2への移行

OpenID Connect認証レスポンスにsession_stateパラメーターを追加

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 スイッチがあります。

パラメーター session_state が3.4.2で追加されましたが、 Exclude Session State From Authentication Response スイッチは4.0.0.Beta1に追加されました。Keycloakサーバーが3.4.2または3.4.3で、 session_state パラメーターに問題がある場合は、サーバーを4.0.0.Beta1以上にアップグレードする必要があります。

3.2.0への移行

新しいパスワード・ハッシュ・アルゴリズム

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

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

IDトークンにはscope=openidが必要

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のキャッシュ authenticationSessionsactionTokens を導入したことです。移行CLIを使用している場合は、 standalone(-ha).xml ファイルは自動的に移行されるため、ほとんど気にする必要はありません。

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

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

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

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

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

2.5.1への移行

古いオフライン・トークンの移行

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が付与されます。そのため、全ユーザーが自身の古いオフライン・トークンを更新した後は、アクティブなレルム鍵を自由に変更することができます。

2.5.0への移行

Infinispanキャッシュへの変更

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

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

2.4.0への移行

Server SPIをServer SPIとSever SPI Privateへ分割

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

SAMLアサーションのキーの暗号化アルゴリズム

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

realmsとusersのInfinispanキャッシュは常にロ-カル

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

2.3.0への移行

ページネーションされたエンドポイントのデフォルト最大値

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

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

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

Infinispanキャッシュ keys の追加

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

2.2.0への移行

databaseSchema プロパティーの 廃止

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

クライアントの有効なリダイレクトURIの変更

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

  • クエリー・コンポーネントを持つ有効なリダイレクトURIがクライアント(サンプルとしては http://localhost/auth?foo=bar )で保存された場合、認証要求の redirect_uri はこのURI(または、このクライアントで登録された他のURI)と完全に一致する必要があります。

  • クエリー・コンポーネントを持たない有効なリダイレクトURIがクライアントに保存された場合も、 redirect_uri はこのURIと完全に一致する必要があります。

  • クエリー・コンポーネントを持たない、登録済みの有効なリダイレクトURIのワイルドカードは、サポートされなくなりました。そのため、 redirect_uri はこの登録済みのURIとも同様に一致する必要があります。

  • 登録済みの有効なリダイレクトURI( http://localhost/auth#fragment など)内のフラグメントはもはや許可されません。

アイデンティティー・プロバイダーからデフォルトで削除された認証

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

2.0.0への移行

1.0.0.Finalからのアップグレードはサポートされなくなりました

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

1.9.5への移行

デフォルトのパスワード・ハッシュ間隔は20Kに増加

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

1.9.3への移行

ユーザー追加スクリプトの名前の変更

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

1.9.2への移行

アダプター・オプションauth-server-url-for-backend-requestsを削除

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

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

1.9.0への移行

テーマとプロバイダーのディレクトリーを移動

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

アダプター・サブシステムはKeycloakが有効な場合にのみ依存関係となる

以前は、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 に変更しました。

いくつかのOpenID Connectエンドポイントを廃止

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を変更

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

SAML SPクライアント・アダプターの変更

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

1.8.0への移行

管理者アカウント

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

OAuth2トークン・イントロスペクション

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 だけがこの新しいエンドポイントを呼び出すことが許可されており、そこでは、これらのクライアントは通常、リソースサーバーとして機能し、ローカルの認可チェックを実施するために、トークンのメタデータを検索します。

1.7.0.CR1への移行

クライアントのダイレクト・アクセス・グラントをデフォルトで無効化

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 を使用するように設定を更新する必要があります。現在、後者はデフォルトでダイレクト・アクセス・グラントが有効になっていないためです。

オプション’Update Profile On First Login’をアイデンティティー・プロバイダーからレビュー・プロファイル・オーセンティケーターへ移動

このバージョンで、 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' 要素のサポートを終了

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

IdentityProviderMapperの変更

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

1.6.0.Finalへの移行

リフレッシュ・トークンを再利用しないオプション

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 を追加する必要があります。

"userSessionPersister": {
    "provider": "jpa"
},

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

1.5.0.Finalへの移行

レルムとユーザーのキャッシュ・プロバイダー

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

ユーザー・セッション・プロバイダー

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

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

コンタクト詳細を登録とアカウント管理から削除

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

1.3.0.Finalへの移行

ダイレクト・グラントAPIは常に有効

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

データベースの変更

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

UserFederationProviderの変更

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

WildFly 9.0.0.Final

最新リリースで実行された配布物の変更に伴って、現在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アダプター

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

  • eap6

  • wf9

  • wf8

  • as7

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

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

1.2.0.Beta1から1.2.0.RC1への移行

配布物の変更

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

データベースの変更

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

アプリケーションとOAuthクライアントのマージ

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

1.1.0.Finalから1.2.0.Beta1への移行

データベースの変更

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

アクセス・トークンとIDトークン内の iss

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

OpenID Connectエンドポイント

OpenID Connect仕様に合わせるために、認証とトークンのエンドポイントは、単一の認証エンドポイントと単一のトークン・エンドポイントを持つように変更されました。仕様どおりに response_typegrant_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としてこれをペーストするだけです。

1.1.0.Beta1から1.1.0.Beta2への移行

  • 現在、アダプターは別途ダウンロードすることになっています。これはアプライアンスやwar配布物には含まれていません。現在配布物にはあまりに多くのものが含まれていて、肥大化している状態です。

  • org.keycloak.adapters.tomcat7.KeycloakAuthenticatorValve +org.keycloak.adapters.tomcat.KeycloakAuthenticatorValve

  • 現在、JavaScriptアダプターには、idTokenとidTokenParsedプロパティーがあります。idTokenを使用してファーストネームやEメールなどを取得する場合、これをidTokenParsedに変更する必要があります。

  • as7-eap-subsystemとkeycloak-wildfly-subsystemは、1つのkeycloak-subsystemに統合されました。既存のstandalone.xmlまたはdomain.xmlを持っている場合は、ファイルの先頭あたりを編集し、拡張モジュール名をorg.keycloak.keycloak-subsystemに変更する必要があります。AS7だけは、拡張モジュール名がorg.keycloak.keycloak-as7-subsystemになります。

  • サーバーのインストールはAS7ではサポートされなくなりました。それでも、AS7はアプリケーション・クライアントとして使用することができます。

1.0.x.Finalから1.1.0.Beta1への移行

  • RealmModelのJPAとMongoストレージ・スキーマが変更されました

  • UserSessionModelのJPAとMongoストレージ・スキーマは、これらのインターフェイスがリファクタリングされたので、変更されました

  • アダプターをアップグレードしてください。古いアダプターはKeycloak 1.1と互換性がありません。JSON Web TokenとOIDC ID Tokenの仕様は間違って解釈されていました。 'aud' クレームはクライアントIDでなければなりませんが、そこにレルム名が格納されて検証されていました。

1.0 RC-1からRC-2への移行

  • 情報レベルのロギングの多くがデバッグレベルに変更されました。また、デフォルトではレルムにjboss-logging監査リスナーが無くなりました。ユーザーがログイン、ログアウト、パスワードの変更などをする際にログの出力が必要な場合は、管理コンソールでjboss-logging監査リスナーを有効にしてください。

1.0 Beta 4からRC-1への移行

  • ログアウトREST APIはリファクタリングされました。ログアウトURIのGETリクエストはsession_stateパラメーターを取得しなくなりました。セッションをログアウトするには、ログインする必要があります。また、ログアウトREST URIにPOSTすることもできます。このアクションでは、ログアウトするために有効なリフレッシュ・トークンが必要です。シグネチャーは、パラメーターからグラント・タイプを差し引いたリフレッシュ・トークンと同じものです。詳しくは、ドキュメントを参照してください。

1.0 Beta 1からBeta 4への移行

  • LDAP/AD設定は変更されました。これは "Settings" ページには存在しなくなりました。現在はUsers→Federationにあります。プロバイダーの追加には、 "ldap" オプションが表示されます。

  • 認証SPIは削除されて書き換えられました。新しいSPIはUserFederationProviderで、より柔軟性が高くなっています。

  • ssl-not-required +ssl-required +all +external +none

  • DBスキーマは再度変更されました。

  • 新規作成されたアプリケーションは、デフォルトでフルスコープを持つようになりました。つまり、必要ない場合は、アプリケーションのスコープを設定する必要はありません。

  • レルムデータをインポートするためのJSONファイルのフォーマットが変更されました。現在は特定のユーザーのJSONレコードでロール・マッピングを使用することができます。

1.0 Alpha 4からBeta 1への移行

  • DBスキーマが変更されました。Beta 1へデータベースのエクスポートを追加しましたが、古いバージョンからデータベースをインポートすることはできませんでした。これについては、今後のリリースでサポートされることになります。

  • ベアラー専用のアプリケーションを除いてクライアントはすべて、少なくとも1つのリダイレクトURIを指定する必要があります。そのアプリケーション用の有効なリダイレクトURIを指定しないと、Keycloakへのログインは許可されません。

  • Direct Grant API +ON

  • standalone/configuration/keycloak-server.json

  • JavaScriptアダプター

  • セッション・タイムアウト

1.0 Alpha 2からAlpha 3への移行

  • SkeletonKeyToken、SkeletonKeyScope、SkeletonKeyPrincipal、およびSkeletonKeySessionは、それぞれAccessToken、AccessScope、KeycloakPrincipal、およびKeycloakAuthenticatedSessionに名前が変更されました。

  • ServletOAuthClient.getBearerToken()メソッドのシグネチャーが変更されました。現在は、AccessTokenResponseが返されて、リフレッシュ・トークンも取得できるようになりました。

  • 現在、アダプターはリクエストの度にアクセストークンの期限を確認します。トークンが期限切れになっていると、アダプターは保存されたリフレッシュトークンを使用して、認証サーバー上でリフレッシュを実行しようとします。

  • AccessTokenのサブジェクトがUser IDに変更されました。

1.0 Alpha 1からAlpha 2への移行

  • DBスキーマが変更されました。Alpha 2の時点では、データ移行ユーティリティーはまだありません。

  • 現在、JBossアダプターとWildFlyアダプターはWildFlyサブシステムでインストールされています。アダプターのインストールのドキュメントを参照ください。現在、standalone.xmlへの編集が必要です。

  • 新しいクレデンシャル・タイプ "secret" が導入されました。他のクレデンシャル・タイプと異なり、データベース内のプレーンテキストに保存されていて、管理コンソールで確認することができます。

  • アプリケーションとOAuthクライアントのクレデンシャルは不要になりました。これらのクライアント・タイプは、 "secret" クレデンシャル・タイプを使用するようにハードコードされています。

  • アプリケーションとOAuthクライアントに対する "secret" クレデンシャルの変更により、管理コンソールのアプリケーションまたはOAuthクライアント・クレデンシャルのタブで、keycloak.json設定ファイルを更新してシークレットを再生成する必要があります。