Upgrading Guide

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

回避策としては、 $JAVA_HOME/conf/security/java.security のプロパティー jdk.xml.dsig.secureValidationPolicy で設定した「許可しないアルゴリズム」の一覧から http://www.w3.org/2000/09/xmldsig#rsa-sha1 や http://www.w3.org/2000/09/xmldsig#dsa-sha1 などのアルゴリズムを削除することが考えられます。

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

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

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

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

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

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

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

この変更に伴い、H2 JDBC URLの変更や、既存のKeycloakセットアップにおけるH2データベース・ファイルの移行が必要になる場合があります。

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Kubernetes Documentation もご参照ください。

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

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

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

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

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

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

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

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

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

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

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

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

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

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

リソースは以下です。

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

See the details in the Threat model mitigation chapter 。

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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