アップグレードガイド

X-Forwarded-Host ヘッダーにはオプションでポートも含めることができます。以前のバージョンでは、ポートがヘッダーから省略されると、Red Hat build of Keycloak は実際の要求ポートにフォールバックしていました。たとえば、Red Hat build of Keycloak がポート 8080 でリッスンしていて、リクエストに X-Forwarded-Host: example.com ヘッダーが含まれていた場合、解決された URL は http://example.com:8080 になります。

これが変更され、ポートが省略されると、解決された URL から削除されます。前の例から解決された URL は http://example.com になります。

これを軽減するには、リバースプロキシーの X-Forwarded-Host ヘッダーにポートを含めるか、X-Forwarded-Port ヘッダーに必要なポートを設定するように指定します。

ディストリビューションに明示的に追加する必要がある Oracle JDBC ドライバーに必要な JAR が変更されました。ojdbc11 JAR を提供する代わりに、Oracle データベースドライバーのインストール に記載されているように、ojdbc17 JAR を使用します。

今回のバージョンでは、デフォルトの H2 ベースの dev-file データベースによって認証情報が変更されました。この dev のみデータベースを使用するインスタンスからの移行はサポートされていませんが、データベースのユーザー名とパスワードに以前のデフォルトを明示的に指定すると、既存の H2 データベースを引き続き使用できる場合があります。たとえば、keycloak.conf で以下を指定します。

OpenID Connect core specification の最新のドラフトバージョンでは、クライアント認証方法 private_key_jwt および client_secret_jwt の JWT クライアントアサーションにおけるオーディエンス検証のルールが変更されました。

以前は、JWT クライアントアサーションの aud クレームは The Audience SHOULD be the URL of the Authorization Server’s Token Endpoint と緩く定義されていましたが、他の URL の使用が排除されていませんでした。

改訂された OIDC コア仕様では、より厳格なオーディエンスチェックが使用されます (The Audience value MUST be the OP’s Issuer Identifier passed as a string, and not a single-element array.)。

private_key_jwt と client_secret_jwt の両方の JWT クライアント認証オーセンティケーターを適応させて、デフォルトでトークン内の対象ユーザー 1 つだけ許可されるようにしました。現在、オーディエンスは、クライアント JWT 認証で使用される発行者、トークンエンドポイント、イントロスペクションエンドポイント、またはその他の OAuth/OIDC エンドポイントにすることができます。ただし、現在許可されているオーディエンスは 1 つだけなので、他の無関係なオーディエンス値を使用できません。つまり、JWT トークンは実際には Red Hat build of Keycloak によるクライアント認証でのみ有効になります。

この厳格なオーディエンスチェックは、OIDC ログインプロトコル SPI の新しいオプションを使用して、以前のより緩いチェックに戻すことができます。サーバーが以下のオプションで起動された場合、引き続き JWT で複数のオーディエンスを使用することができます。

--spi-login-protocol-openid-connect-allow-multiple-audiences-for-jwt-client-authentication=true

このオプションは今後削除される可能性があることに注意してください。おそらく、Red Hat build of Keycloak 27 で削除されます。そのため、このオプションを使用する代わりに、単一のオーディエンスを使用するようにクライアントを更新することを強く推奨します。また、クライアント認証のために JWT を送信するときは、今後のバージョンの OIDC 仕様と互換性があるため、クライアントがオーディエンスに発行者 URL を使用することを推奨します。

このリリースでは、特定の機能が削除され、今後のリリースで削除されるようにその他の機能は非推奨としてマークされています。これらの変更の詳細は、リリースノート を参照してください。

このリリースでは、Red Hat build of Keycloak は 標準トークン交換 (機能 token-exchange-standard:v2) のサポートを追加しました。過去の Red Hat build of Keycloak リリースでは、Red Hat build of Keycloak にはプレビュートークン交換機能しかありませんでした。この機能は現在 レガシートークン交換 (機能 token-exchange:v1) と呼ばれています。レガシートークン交換はまだプレビュー段階であり、以前のリリースと同じように機能します。内部間トークン交換 を使用していた場合は、新しい標準トークン交換への移行を検討してください。

レガシートークン交換を引き続き使用する場合、標準のトークン交換機能を無効にする必要はありません。クライアントは、Red Hat build of Keycloak クライアントで標準トークン交換が有効になっている場合にのみ、標準トークン交換を使用します。ただし、標準のトークン交換への移行が推奨されます。これは公式にサポートされている方法であり、機能拡張の優先事項です。

新しい標準トークン交換への移行を計画する際には、次の注意事項を考慮してください。

2 種類のトークン交換の動作における次の追加の変更を考慮してください。

現在、オフラインセッションから発行されたサブジェクトトークンを使用して、オフライントークンのリクエストやリフレッシュトークンの交換を行うことはサポートされていません。推奨される方法は、可能な限り更新トークンではなく、アクセストークンを交換することです。

Red Hat build of Keycloak は、Fine-grained admin permissions V2 を導入することで、管理者権限に対する認可モデルをさらに柔軟で使いやすく改善しています。

複数のノードをクラスター化するために、Red Hat build of Keycloak は分散キャッシュを使用します。このリリース以降、すべての TCP ベースのトランスポートスタックでは、ノード間の通信は TLS で暗号化され、自動生成された一時キーと証明書で保護されます。

TCP ベースのトランスポートスタックを使用していない場合は、簡素化された設定と強化されたセキュリティーのメリットを享受するために、jdbc-ping トランスポートスタックに移行することを推奨します。

以前のリリースで TCP トランスポートスタック通信を保護するために独自のキーストアとトラストストアを指定していた場合は、設定の簡素化を最大限に活かせるように、自動生成される一時キーと証明書に移行することを推奨します。

カスタムトランスポートスタックを使用している場合は、cache-embedded-mtls-enabled オプションを false に設定することで、このデフォルトの動作を無効にできます。

サービスメッシュを使用している場合は、Red Hat build of Keycloak Pod 間の直接 mTLS 通信を許可するように設定します。

詳細は、トランスポートスタックのセキュリティー保護 を参照してください。

新しいユーザー、グループ、またはロールを追加すると、LDAP プロバイダーは常に検索用に設定された同じベース DN にその新規ユーザーなどを保存します。ただし、デプロイメントによっては、管理者が複数のサブ DN からユーザー (またはグループ/ロール) を取得するように、subtree スコープを含む幅広い DN を設定しつつも、LDAP のベース DN に新規ユーザー (またはグループ/ロール) を保存しないことを希望する場合などがあります。その場合は代わりに、サブ DN のいずれかを選択します。

LDAP プロバイダーおよび LDAP グループとロールマッパーの新しい Relative User Creation DN 設定オプションを使用して、新しいユーザー、グループ、またはロールが作成される場所を制御できるようになりました。詳細は、LDAP 管理 を参照してください。

組み込みの X.509 クライアント証明書検索プロバイダーは proxy-trusted-addresses 設定オプションを反映するようになりました。HTTP ヘッダーを通じて提供される証明書は、プロキシーが信頼されている場合、または proxy-trusted-addresses が設定されていない場合にのみ処理されるようになりました。

デフォルトでは、Red Hat build of Keycloak Operator は、Red Hat build of Keycloak の分散キャッシュに使用される内部ポートへのトラフィックを制限するための NetworkPolicy を作成するようになりました。

これにより、セキュアバイデフォルト (secure-by-default) の設定を強化し、新規設定の構成ステップを最小限に抑えます。この変更は既存のデプロイメントとの下位互換性を保つことを目的としているため、アップグレード時に追加の手順は必要ありません。Keycloak CR で NetworkPolicies の作成を無効にすると、以前の動作に戻すことができます。

デプロイメントスクリプトが Red Hat build of Keycloak に明示的な NetworkPolicies を追加する場合は、それらを削除し、アップグレードのフォローアップとして Keycloak CR で提供される新しい機能に移行することを検討してください。

詳細は、Operator の高度な設定 を参照してください。

以前は、認証情報のリセットフロー (forgot password 機能) では、同じ認証セッション (同じブラウザー) が使用された場合、認証情報のリセット後もユーザーはログインしたままでした。フェデレーションユーザープロバイダーの場合、この動作はセキュリティー上の問題になる可能性があります。プロバイダー実装がユーザーが enabled であると検出し、パスワードの変更を正常に実行したにもかかわらず、何らかの理由でユーザーパスワードの検証が失敗するシナリオを考えてみましょう。このシナリオでは、認証情報のリセットフローにより、パスワードの変更が成功した後にユーザーのログインは可能であっても、通常のブラウザーフローを使用するとそのログインは拒否されます。これは一般的なシナリオではありませんが、デフォルトでは使用しないようにしてください。

このため、オーセンティケーター reset-credential-email (Send Reset Email) には、force-login (Force login after reset) という新しい設定オプションが追加されました。値として true (常にログインを強制)、false (同じ認証セッションが使用される場合はユーザーのログイン状態を維持する以前の動作)、および only-federated (フェデレーションユーザーに再度認証を強制し、Red Hat build of Keycloak に保存されているユーザーに対して以前の動作を維持するデフォルト値) を指定できます。

このオプションの変更の詳細は、パスワードを忘れた場合の有効化 を参照してください。

Red Hat build of Keycloak のすべてのオフラインセッションは、オンラインセッションから作成されます。Offline_access スコープが要求されると、現在のオンラインセッションを使用して、クライアントに関連付けられたオフラインセッションが作成されます。したがって、これまで完了したすべての offline_access 要求では、オンラインセッションとオフラインセッションの 2 つのセッションが作成されました。この状況は、信頼できない動作につながります。たとえば、scope=offline_access によるログインのみが要求された場合、未使用のオンラインセッションが作成されることがあります。このセッションはほとんどの場合役に立たず、余分なサーバーリソースが消費されてしまいます。

このバージョン以降、セッションの最初の対話として、offline_scope が直接要求された場合、Red Hat build of Keycloak は初期オンラインセッションを削除します。クライアントは、オフラインセッションに関連付けられたコードとトークンの交換後にオフライントークンを取得しますが、以前のオンラインセッションは削除されます。online_scope 要求の前に、同じクライアントまたは別のクライアントによってオンラインセッションが使用されていた場合、オンラインセッションは現在と同様にアクティブなままになります。この状況になると、scope=offline_access のログイン要求が使用され、ユーザーが事前に SSO で認証されていない場合、ブラウザーで SSO セッションが作成されていません。クライアントアプリケーションは、オフライントークンのみを要求するため、この新しい動作は理にかなっていますが、最初の offline_scope トークン要求の後も、オンラインセッションを保持する必要があるシナリオには影響する可能性があります。

Red Hat build of Keycloak は、service_account と呼ばれるレルムレベルの新しいクライアントスコープを導入します。このスコープは、プロトコルマッパーを使用して、client_credentials 付与の特定のクレーム (client_id、clientHost、clientAddress) を追加します。このスコープは、クライアント設定で serviceAccountsEnabled オプションが設定または設定解除されると、クライアントに自動的に割り当てられ、クライアントから割り当て解除されます。

以前は、クライアントがサービスアカウントを有効にするように設定されたときに、3 つのマッパー (クライアント ID、クライアントホスト、クライアント IP アドレス) が専用スコープに直接追加され、削除されることはありませんでした。

トークン内のクレームは実質的に以前と同じであるため、動作はほとんどの Red Hat build of Keycloak デプロイメントで実質的に同じになるはずです。クライアント認証情報の付与を使用しており、上記の 3 つのプロトコルマッパーを手動で削除または更新するツールで Red Hat build of Keycloak 環境を準備している場合、影響を受ける可能性があります。たとえば、管理 CLI スクリプトを使用してクライアントのサービスアカウントを有効にし、組み込みのサービスアカウントプロトコルマッパーを削除する場合、プロトコルマッパーを削除する代わりに、クライアントから service_account クライアントスコープの割り当てを削除するように CLI を調整できます。

クライアントが 署名済み JWT または クライアントシークレット付きの署名済み JWT タイプを使用して認証するように設定されている場合、Red Hat build of Keycloak はトークンの最大有効期限を強制するようになりました。つまり、トークンの exp (有効期限) 要求はかなり後のタイミングで設定されているにもかかわらず、Red Hat build of Keycloak は最大有効期限より前に発行されたトークンを受け入れません。デフォルト値は、60 秒です。JWT トークンは認証のために送信される直前に発行される必要があることに注意してください。その結果、クライアントがログイン用トークンを送信できる時間は約 1 分間に限られます。ただし、クライアント Credentials タブで Max expiration 設定オプションを使用してこの有効期限を調整できます。詳細は、機密クライアント認証情報 を参照してください。

自動移行を実行するには、目的のデータベースに接続されているサーバーを起動します。新しいサーバーバージョンでデータベーススキーマが変更すると、データベースのレコード数が多すぎない限り、移行が自動的に開始されます。

たとえば、数百万件のレコードを含むテーブルにインデックスを作成すると、時間がかかり、サービスの大きな中断を引き起こす可能性があります。したがって、自動移行には 300000 レコードのしきい値が存在します。レコード数がこのしきい値を超えると、インデックスは作成されません。代わりに、手動で適用できる SQL コマンドを含む警告がサーバーログに表示されます。

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

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

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

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

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

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

この設定でサーバーを起動すると、サーバーはデータベースを移行する必要があるか確認します。移行が必要な場合、必要な変更は bin/keycloak-database-update.sql SQL ファイルに書き込まれます。これらのコマンドを確認し、データベースに対して手動で実行できます。

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

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

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

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

テンプレートをカスタマイズした場合は、そのテンプレートの新しいバージョンと比較します。この比較により、カスタマイズしたテンプレートに適用する必要がある変更が示されます。差分ツールを使用してテンプレートを比較できます。次のスクリーンショットは、Login テーマの info.ftl テンプレートとカスタムテーマの例を比較したものです。

この比較から、1 つ目の変更点 (Hello world!!) はカスタマイズであり、2 つ目の変更点 (if pageRedirectUri) はベーステーマの変更点であることがわかります。2 つ目の変更点をカスタムテンプレートにコピーすると、カスタマイズしたテンプレートが正常に更新されます。

別の方法として、次のスクリーンショットは、古いインストールの info.ftl テンプレートと新しいインストールの更新された info.ftl テンプレートを比較したものです。

この比較から、ベーステンプレートの変更点がわかります。これをもとに、変更したテンプレートに同じ変更を手動で加えることができます。この方法はより複雑であるため、最初の方法が実行不可能な場合にのみ使用してください。

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

組み込みテーマのスタイルに加えた変更を反映するには、カスタムスタイルを更新する必要がある場合があります。差分ツールを使用して、古いサーバーインストールと新しいサーバーインストール間のスタイルシートの変更を比較することを検討してください。

以下に例を示します。

diff RHSSO_HOME_OLD/themes/keycloak/login/resources/css/login.css \
RHSSO_HOME_NEW/themes/keycloak/login/resources/css/login.css

$ diff RHSSO_HOME_OLD/themes/keycloak/login/resources/css/login.css \
RHSSO_HOME_NEW/themes/keycloak/login/resources/css/login.css

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