Red Hat Summitアップグレードガイド
概要
第1章 Red Hat build of Keycloak のアップグレード
このガイドでは、Red Hat build of Keycloak をバージョン 26.2.x からバージョン 26.4 にアップグレードする方法を説明します。このガイドの手順は、次の順序で使用してください。
- Red Hat build of Keycloak の以前のバージョンからのリリース固有の変更を確認します。
- Red Hat build of Keycloak サーバーをアップグレードします。
- Red Hat build of Keycloak アダプターをアップグレードします。
- Red Hat build of Keycloak 管理クライアントをアップグレードします。
以前のバージョンの Red Hat build of Keycloak （バージョン 22.x、24.x、26.2 など）からアップグレードする場合は、お使いのバージョンと 26.4 間で公開される各アップグレードガイドの変更をすべて確認してください。次のアップグレードガイドを参照してください。
その後、このガイドで説明されているアップグレード手順を実行できます。
Red Hat Single Sign-On 7.6 のお客様の場合は、このガイドの代わりに 移行ガイド を使用してください。
第2章 リリース固有の変更
2.1. バージョン 26.4.4 での重大な変更
重大な変更は、既存ユーザーが設定またはアプリケーションへの変更を必要とする可能性があるため識別されます。マイナーリリースまたはパッチリリースでは、Red Hat build of Keycloak により、バグを修正するための重大な変更のみが導入されます。
2.1.1. リクエストでの正規化されたパスのみの受け入れ
以前のリリースでは、Red Hat build of Keycloak は、二重ドット(..)または二重スラッシュ(//)を含むパスを持つ HTTP リクエストを受け入れました。 これらの要求の処理により、正規化されたパスが生成され、RFC3986 に従って二重スラッシュが折りたたまれます。このアプローチでは、設定が困難な URL フィルタリングがつながります。たとえば、リバースプロキシーでは正規化が無効になり、Red Hat ビルドの Keycloak は HTTP 400 応答コードで応答します。
サーバーログで拒否されたリクエストを分析するには、org.keycloak.quarkus.runtime.services.RejectNonNormalizedPathFilter のデバッグログを有効にします。
以前の動作に戻り、正規化されていない URL を許可するには、http-accept-non-normalized-paths を true に設定します。この設定では、HTTP アクセスログを有効にして確認し、問題のあるリクエストを特定します。
2.2. バージョン 26.4.2 での重大な変更
2.2.1. acr_values リクエストパラメーターはアイデンティティープロバイダーに自動的に転送されない
acr_values 要求パラメーターは、認証中に OpenID Connect アイデンティティープロバイダーに自動的に転送されなくなりました。この変更により、外部 IDP への認証情報の意図しない情報の公開を防ぐことで、セキュリティーが強化されます。
acr_values パラメーターをアイデンティティープロバイダーに伝播する場合は、アイデンティティープロバイダー設定の Forwarded クエリーパラメーター設定に を明示的に設定する必要があります。
acr_values 要求パラメーター
2.2.2. CLIENT_ATTRIBUTES および GROUP_ATTRIBUTE テーブルで再作成されるインデックス
以前のバージョンの Red Hat build of Keycloak では、EnterpriseDB (EDB)はサポートされていないと見なされていました。これは変更されており、本リリースでは EDB Advanced がサポートされるようになりました。以前のバージョンの EDB JDBC ドライバーが EDB への接続に使用されていた場合、無効なスキーマの変更の一部がデータベースに適用されました。これを軽減するために、一部のインデックスは、このバージョンへのスキーマ移行中に自動的に再作成されます。以前のリリースで EDB を使用していたかどうかにかかわらず、PostreSQL データベース(EDB を含む)を使用している場合は、これに影響します。
これは、CLIENT_ATTRIBUTES および GROUP_ATTRIBUTE テーブルのインデックスに影響します。これらのテーブルに 300,000 を超えるエントリーが含まれる場合、Red Hat build of Keycloak はデフォルトで自動スキーマ移行中にインデックスの作成を省略し、代わりに Red Hat build of Keycloak の起動後に手動で適用されるように、移行中にコンソールで SQL ステートメントをログに記録します。異なる制限を設定する方法は、アップグレードガイド を参照してください。
2.2.3. 追加のデータソースの設定変更
以前のリリースでは、追加のデータソースを設定する唯一の方法として、通常はサポートされていないと思われる生の Quarkus プロパティーを使用していました。同時に、追加のデータソースの追加がサポートされていたため、不明確な状況が発生していました。
追加のデータソースを設定するためのサポートおよびユーザーフレンドリーな方法を提供するために、それに対して新しい専用サーバーオプションが導入されました。Quarkus プロパティーを使用した元のアプローチを使用した追加のデータソースの設定は、本リリース以降 はサポートされないと見なされ ます。
設定を移行する方法については、以下の例を確認してください。
- 新しい Red Hat build of Keycloak オプションの使用（推奨）
追加のデータソースを設定するためにサポートされる方法は、新しい設定オプションを使用することです。
この設定は、
conf/quarkus.propertiesで移行できます。quarkus.datasource.user-store.db-kind=postgresql quarkus.datasource.user-store.username=my-username quarkus.datasource.user-store.jdbc.url=jdbc:postgresql://my-remote-postgres:5432/user-store quarkus.datasource.user-store.jdbc.transactions=xa
quarkus.datasource.user-store.db-kind=postgresql quarkus.datasource.user-store.username=my-username quarkus.datasource.user-store.jdbc.url=jdbc:postgresql://my-remote-postgres:5432/user-store quarkus.datasource.user-store.jdbc.transactions=xaCopy to Clipboard Copied! Toggle word wrap Toggle overflow conf/keycloak.confでこの設定を行うには、以下を実行します。db-kind-user-store=postgres db-username-user-store=my-username db-url-full-user-store=jdbc:postgresql://my-remote-postgres:5432/user-store # transactions XA is enabled by default for datasources
db-kind-user-store=postgres db-username-user-store=my-username db-url-full-user-store=jdbc:postgresql://my-remote-postgres:5432/user-store # transactions XA is enabled by default for datasourcesCopy to Clipboard Copied! Toggle word wrap Toggle overflow データソースオプションの詳細は、複数のデータソースの設定 を参照してください。
quarkus.propertiesの引用の削除（サポート対象外）現在、Red Hat build of Keycloak データソースオプションに移行できない場合は、問題を防ぐためにデータソースオプションのマッピングの競合を避けるために、追加のデータソース名引用符を削除します。
つまり、
conf/quarkus.propertiesで設定を移行する必要があります。quarkus.datasource."user-store".db-kind=postgresql quarkus.datasource."user-store".username=my-username
quarkus.datasource."user-store".db-kind=postgresql quarkus.datasource."user-store".username=my-usernameCopy to Clipboard Copied! Toggle word wrap Toggle overflow バージョンを引用符なしの場合は以下を行います。
quarkus.datasource.user-store.db-kind=postgresql quarkus.datasource.user-store.username=my-username
quarkus.datasource.user-store.db-kind=postgresql quarkus.datasource.user-store.username=my-usernameCopy to Clipboard Copied! Toggle word wrap Toggle overflow
2.2.4. 一時的にロックされたユーザーに関する情報の読み取り
以前のリリースでは、REST エンドポイントでは、ユーザー(GET /admin/realms/{realm}/users/{user-id})を取得し、ユーザーを検索すると、一貫性がありませんでした(GET /admin/realms/{realm}/users)。BruteForce が有効になり、ユーザーが一時的にロックアウトされた場合、以前のエンドポイントは enabled=false を返しますが、後者は enabled=true を返します。一時的なロックアウトによりユーザーが更新されて有効であった場合は、ユーザーが永続的に無効になります。ユーザーが一時的にロックアウトされている場合、両方のエンドポイントは enabled=true を返すようになりました。ユーザーが一時的に BruteForceUserResource エンドポイントを利用する必要があるかどうかを確認します(GET /admin/realms/{realm}/attack-detection/brute-force/users/{userId})。
2.2.5. ユーザー API を使用したユーザーの検索が、ユーザープロファイル設定を尊重するようになりました
ユーザー API を使用してユーザーをクエリーする際に、ユーザー表現とその属性は、レルムに定義されたユーザープロファイル設定を考慮に入れるようになりました。
過去に返された情報が多すぎるユーザープロファイル設定によっては、ユーザー表現の属性が利用できない可能性があります。
2.2.6. ブローカーとして動作するときに OpenID Connect のクライアントシークレットを送信する際のエンコーディングが修正されました。
Red Hat build of Keycloak がブローカーとして機能し、OpenID Connect によって別のアイデンティティープロバイダーに接続するシナリオでは、RFC6749 で指定されている正しいエンコーディングで Basic 認証によるクライアントクレデンシャルを送信するようになりました。リクエスト本文で認証情報を送信するように Red Hat build of Keycloak を設定している場合は、影響を受けません。
これにより、コロンやパーセンテージ記号などを含むクライアント ID またはパスワードの問題が回避されます。
古い動作に戻すには、クライアント認証を URL エンコードなしで HTTP Basic authentication として送信される非推奨のオプション Client secret に変更します(client_secret_basic_unencoded)。
2.3. バージョン 26.4.6 での主な変更点
主な変更には、一般的な設定ミス、修正されたバグ、または Red Hat build of Keycloak の実行を簡素化するための変更を防ぐために、内部の動作の変更が含まれる場合があります。
2.3.1. LDAP 参照のみを許可するようにフィルターされた LDAP 参照
LDAP 参照はデフォルトで LDAP URL のみを含めることができるようになりました。この変更によりセキュリティーが強化され、LDAP 設定のベストプラクティスに準拠します。
この変更により、カスタム拡張機能を作成した場合に他の JDNI 参照が使用されなくなります。元の動作を復元するには、spi-storage-ldap-secure-referral オプションを false に設定します。このアクションと組み合わせて、すべての LDAP プロバイダーで LDAP 参照を無効にすることが推奨されます。
2.4. バージョン 26.4.4 での主な変更点
2.4.1. realm-admin ロールを持つ管理者が、admin ロールを割り当てることができるようになりました。
以前のバージョンでは、realm-admin ロールで付与された realm administrator は、委譲されたレルム管理者に admin ロールを付与できませんでした。この機能は、master レルムユーザーに admin ロールを付与することでのみ可能でしたため、そのユーザーはサーバー admin となっています。
本リリースでは、realm-admin ロールを持つユーザーのレルム管理者は、レルムのユーザーに admin ロールを割り当て、サーバー管理者権限を必要とせずに管理タスクを委譲できるようになりました。
FGAP を使用して管理を master レルム以外のレルムのユーザーに委譲する場合は、realm-admin ロールで付与されたユーザーに特権のエスカレーションを回避するためにこのロールが割り当てられていることを確認してください。
さまざまなタイプのレルム管理者の詳細は、パーミッションを使用したレルム管理の委譲 を参照してください。
2.4.2. OFFLINE_CLIENT_SESSION テーブルに新しいデータベースインデックス
この変更により、OFFLINE_CLIENT_SESSION テーブルに新しいインデックスが追加され、クライアントセッションの取得または削除時のパフォーマンスが向上します。
これらのテーブルに 300,000 を超えるエントリーが含まれる場合、Red Hat build of Keycloak は自動スキーマ移行中のインデックス作成を省略します。代わりに、移行には、Red Hat build of Keycloak の起動後に手動で適用される必要な SQL ステートメントが表示されます。異なる制限の設定に関する詳細は、Migrating the database を参照してください。
2.5. バージョン 26.4.2 での主な変更点
2.5.1. ディストリビューションのアップグレード手順の変更
ディストリビューションをダウンロードして Red Hat build of Keycloak をアップグレードする場合、アップグレード手順が変更されました。以前は、以前のインストールから新規インストールに、conf/ フォルダーからコンテンツをコピーすることが推奨されます。新しい手順では、新しいバージョンに含まれるファイルに基づいて、cache-ispn.xml またはカスタムキャッシュ設定への変更を再適用することを推奨します。
これにより、以前のバージョンから古い cache-ispn.xml ファイルを使用するなど、誤って機能がダウングレードされるのを防ぐことができます。
2.5.2. サポートされているデータベースのバージョン
各データベースのサポートされるバージョンが、データベースの 設定 に表示さ れます。ただし、基礎となるデータベース固有の Hibernate ダイアレクトによって、表示されているバージョンとは異なるバージョンを使用できる場合は、サポートされる設定ではありません。
| データベース | 最低サポート | ダイアレクトの最小 |
|---|---|---|
| MariaDB | 10.4 (LTS)→ 10.6 (LTS) | 10.4 (LTS)→ 10.6 (LTS) |
| PostgreSQL | 13.x のままです。 | 12.x → 13.x |
| Amazon Aurora PostgreSQL | 15.x のまま | 12.x → 13.x |
| Microsoft SQLServer | 2019 のままに | 2012 → 2014 |
2.5.3. 属性でユーザーを検索する際の 正確な 要求パラメーターの使用
特定の属性キー（値に関係なく）に一致するユーザー API で属性でユーザーをクエリーする場合は、GET メソッドを使用して /admin/realms/{realm}/users を呼び出す際に、正確な 要求パラメーターを false に設定することを検討してください。
たとえば、属性 myattribute が設定されているすべてのユーザーを検索するには、以下のようにする必要があります。
GET /admin/realms/{realm}/users?exact=false&q=myattribute:
GET /admin/realms/{realm}/users?exact=false&q=myattribute:
Red Hat build of Keycloak Admin Client は、実際 の request パラメーターを使用して属性でユーザーを検索する新しい方法でも更新されます。
2.5.4. レルムに対して Remember Me が無効になっている場合、Remember Me で作成したユーザーセッションは無効になりました
レルム設定で Remember Me オプションが無効になっていると、以前 Remember Me フラグで作成されたすべてのユーザーセッションが無効とみなされるようになりました。ユーザーは再度ログインする必要があり、関連付けられた更新トークンは使用できなくなります。Remember Me を選択せずに作成されたユーザーセッションは影響を受けません。
2.5.5. PostgreSQL ドライバーの自動データベース接続プロパティー
PostgreSQL のリーダーインスタンスとライターインスタンスを実行する場合、Red Hat build of Keycloak は作業を実行するために常にライターインスタンスに接続する必要があります。
このリリース以降、元の PostgreSQL ドライバーを使用する場合、Red Hat build of Keycloak は PostgreSQL JDBC ドライバーの targetServerType プロパティーを primary に設定し、書き込み可能な プライマリー インスタンスに接続し、フェイルオーバーまたはスイッチオーバーシナリオでセカンダリーリーダーインスタンスに接続しないようにします。
DB URL または追加のプロパティーで targetServerType に独自の値を設定することで、この動作をオーバーライドできます。
2.5.6. EVENT_ENTITY テーブルの新規データベースインデックス
EVENT_ENTITY テーブルには、USER_ID、TYPE、および EVENT_TIME 列のインデックス IDX_EVENT_ENTITY_USER_ID_TYPE が追加されました。これにより、管理コンソールで特定のユーザーおよびイベントタイプのイベントの検索が速くなります。
テーブルに 300,000 を超えるエントリーが含まれている場合、Red Hat build of Keycloak は自動スキーマ移行中のインデックス作成を省略します。ただし、移行中に SQL ステートメントがコンソールに表示されるため、Red Hat build of Keycloak の起動後に手動で適用できます。異なる制限の設定に関する詳細は、Migrating the database を参照してください。
2.5.7. Bouncy Castle ライブラリーが 2.1.x に更新
Red Hat build of Keycloak を FIPS 140-2 モードで実行する場合は、Bouncy Castle ライブラリーをリリースドキュメントに記載されているバージョンに更新してください。
Bouncy Castle 2.1.x へのアップグレードにより、FIPS 140-2 モードで EdDSA がサポートされるようになりました。
2.5.8. 最初の起動時にのリモートキャッシュの自動作成
リモートキャッシュを使用する場合、Red Hat build of Keycloak は、Data Grid サーバーに存在しない場合は、起動時に必要なキャッシュを自動的に作成するようになりました。
マルチクラスター設定では、事前に Cache CR を使用してキャッシュを作成し、キャッシュの正しい初期化を確認して、キャッシュがいずれかのサイトに存在する間に起動エラーを回避することを推奨します。
2.5.9. 問題のあるキャッシュ設定が無視される
以前のバージョンの Red Hat build of Keycloak では、揮発性ユーザーセッションを有効にするときに、所有者の数が間違って設定されていたり、キャッシュサイズが設定すべきでないのに設定されていたりするなど、問題のある設定について警告が出されていました。このドキュメントでは、揮発性ユーザーセッション用の cache-ispn.xml 設定ファイルも更新しています。
現行バージョンでは、影響を受けるユーザーおよびクライアントセッションキャッシュの所有者の数と最大キャッシュサイズに対して常に安全な設定が使用され、INFO メッセージのみがログに記録されます。この動作により、cache-ispn.xml 設定ファイルを更新する必要がなくなりました。以前に揮発性ユーザーセッションを使用するためにカスタムの cache-ispn.xml を使用していた場合は、それらの変更を元に戻し、標準の設定ファイルを使用することを推奨します。
2.5.10. cache-ispn.xml から削除されたキャッシュ設定
conf/cache-ispn.xml ファイルにはデフォルトのキャッシュ設定が含まれなくなりました。このファイルでは、Red Hat build of Keycloak で使用されるキャッシュ設定を依然として上書きできますが、Red Hat ビルドの Keycloak は、--cache-config-mutate=true オプションが設定されていない場合に警告をログに記録します。このオプションを設定せずにカスタムキャッシュを追加することもできます。
既存のデプロイメントをアップグレードする場合は、既存の conf/cache-ispn.xml からすべてのデフォルトのキャッシュ設定を削除し、たとえばキャッシュサイズを変更するために the --cache-... オプションを使用します。
2.5.11. MySQL および MariaDB の wait_timeout 検証
データベースサーバーによって接続が予期せず閉じられるのを防ぐには、サーバーの wait_timeout 設定に関して Red Hat build of Keycloak 接続プールが正しく設定されていることを確認する必要があります。
このリリース以降、Red Hat build of Keycloak はデフォルトの db-pool-max-lifetime の 7 時間および 50 分を定義し、デフォルトの wait_timeout は 8 時間です。
サーバーが、デフォルト値または提供されている db-pool-max-lifetime 値よりも大きい wait_timeout を定義すると、Red Hat build of Keycloak の起動に警告が記録されます。
2.5.12. メタデータの RFC8414 準拠のルックアップ
Red Hat build of Keycloak は、root URL レベル /.well-known/ で RFC8414 準拠のエンドポイントを公開するようになり、クライアントが発行者 URL によって OAuth 2.0 Authorization Server Metadata および他のよく知られているプロバイダーを検出できるようになりました。
たとえば、OAuth 2.0 Authorization Server Metadata 情報は以下の URL で公開されています。
https://keycloak.example.com/realms/{realm}/.well-known/oauth-authorization-server
https://keycloak.example.com/realms/{realm}/.well-known/oauth-authorization-server現在は、この URL でも利用できます。
https://keycloak.example.com/.well-known/oauth-authorization-server/realms/{realm}
https://keycloak.example.com/.well-known/oauth-authorization-server/realms/{realm}
これを活用するには、リバースプロキシー設定でパス /.well-known/ を公開します。
http-relative-path が設定されている場合は、/.well-known/ パスをサーバーの接頭辞でパスにマップするようにリバースプロキシーを設定します。
2.5.13. Operator のデフォルトのアフィニティー設定が変更されました
デフォルトのスケジューリングポリシーが更新され、障害発生時に可用性を高めるために、ゾーンとノードの両方に対してトポロジー分散制約が作成されるようになりました。以前のバージョンでは、デフォルトのストラテジーでは、すべてのノードが同じアベイラビリティーゾーンにデプロイされることを優先していました。詳細は、高可用性ガイド を参照してください。
2.5.14. JGroups システムプロパティーが CLI オプションに置き換えられました。
以前は、JGroups ネットワークアドレスおよびポートを設定するには、jgroups .bind.* および システムプロパティーを使用する必要がありました。本リリースでは、Red Hat build of Keycloak がこれらのアドレスとポートを直接設定できるように、以下の CLI オプションが導入されています。
jgroups. external_*
-
cache-embedded-network-bind-address -
cache-embedded-network-bind-port -
cache-embedded-network-external-address -
cache-embedded-network-external-port。
古いプロパティーを使用してポートの設定は変更されていませんが、以前の方法が非推奨になる可能性があるため、CLI オプションを使用することが推奨されます。
2.5.15. クライアントセッションの内部表現が変更されました。
認証されたクライアントセッションのキャッシュキーは組み込み Infinispan のキャッシュキーを変更しましたが、パブリック API は変更されていません。このため、以前のバージョンのクラスターで 26.4.1 を同時に実行しないでください。
2.5.16. 外部 IDP トークンの自動更新
更新トークンと JSON 応答を提供する OAuth 2.0 IDP、または OIDC IDP に提供する OAuth 2.0 IDP に /realms/{realm-name}/broker/{provider_alias}/token エンドポイントを使用する場合、アクセストークンの有効期限が切れ、IDP が更新トークンを提供している場合は、トークンはエンドポイント経由で取得されるたびに自動的に更新されます。
GitHub を IDP として使用する場合、JSON 応答を有効にして、このエンドポイントのトークン更新を活用できるようになりました。
2.5.17. 永続的なユーザーセッションバッチ処理の無効化
ユーザーセッション更新のバッチ処理は、デフォルトでオフになっています。これは、一部のデータベースベンダーのパフォーマンスに悪影響を与えるため、他のデータベースベンダーとの利点をオフセットするためです。CLI のオプション --spi-user-sessions-infinispan-use-batches=true を使用してバッチ 処理を有効にできますが、パフォーマンスの向上を確認するために環境をテストすることが推奨されます。
2.5.18. User Session note マッパーの必須フィールド
セッションノートの名前が、管理コンソールの必須フィールドとして表示されるようになりました。
2.5.19. OIDC 属性マッパーの必須フィールド
管理コンソールの必須フィールドとしてトークンクレームの名前が表示されるようになりました。
2.5.20. オフラインセッションメモリー要件に影響する揮発性のユーザーセッション
今回のリリース以降、Red Hat ビルドの Keycloak は、揮発性ユーザーセッションが有効になっている場合に、メモリー内のオフラインユーザーおよびクライアントセッションに対して、デフォルトで 10,000 エントリーのみをキャッシュするようになりました。この変更により、メモリー使用量が大幅に削減されます。
オフラインセッションキャッシュのサイズを変更するには、cache-embedded-offline-sessions-max-count オプションおよび cache-embedded-offline-client-sessions-max-count オプションを使用します。
2.5.21. 翻訳リソースバンドルファイル名
クラスローダーおよびフォルダーベースのテーマにおけるリソースバンドルの名前は、Java ResourceBunndle#getBundle のファイル名と一致するようになりました。de、pt-BR などの含まれるすべてのコミュニティー言語の場合、ファイルには messages_de.properties または messages_pt_BR.properties という名前が付けられます。カスタム言語コードを追加した場合は、ファイル名がまだ同じであるかどうかを確認します。
Red Hat build of Keycloak のコミュニティーテーマの zh-TW および zh-CN の過去の理由で、Chinese （トラスティション）および Chinese （単純化）の言語には名前が付けられています。新しい言語コードに移行する開始として、zh-Hant および zh-Hans は、クラスローダーとフォルダーベースのテーマは、古い言語コード zh-TW および zh-CN、および ファイルのために選択されます。messages_zh_Hant.properties messages_zh_Hant.properties のエントリーは、message _zh_TW.properties のエントリーよりも優先され、message _zh_Hans.properties のエントリーは のエントリーよりも優先されます。
messages _zh_CN.properties
2.5.22. 電子メール機能の更新がサポートされるようになりました。
Update Email がサポートされる機能になり、サーバーの起動時に有効になりました。レルムで Update Email required アクションが有効になっている場合、この機能がレルムに対して有効になります。この機能は、認証フロー中にプロファイルを更新するとき( UPDATE_PROFILE の必須アクションを実行する場合など)に、以前のバージョンから動作が若干変更されます。認証フロー中にプロファイルを更新するときにユーザーがメールを持っている場合、email 属性は利用できません。
2.5.23. SAML の更新アルゴリズム
SAML クライアントが Encrypt Assertions に対して有効になっている場合、SAML 応答に含まれるアサーションは、XML 暗号化構文と処理仕様の後に暗号化 されました。暗号化に使用されるアルゴリズムは固定され、古くなっていました。このリリース以降、デフォルトの暗号化オプションは最新の状態で、セキュリティーに関するより適しています。さらに、特定のクライアントが別のアルゴリズムを必要とする場合は、暗号化の詳細を設定できます。クライアントで新しい属性を定義して、暗号化に使用される正確なアルゴリズムを指定します。管理コンソールの Keys タブで Encrypt Assertions が有効になっている場合、これらの属性はクライアントの Settings タブ、Signature and Encryption セクションに表示されます。
後方互換性を維持するために、Red Hat build of Keycloak のアップグレードは、既存の SAML クライアントを変更して、以前と同じように動作するように暗号化属性を設定します。その結果、既存のクライアントは、同じ以前のアルゴリズムを使用して、同じ暗号化されたアサーションを受け取ります。クライアントが新しいデフォルト設定に対応している場合は、属性を削除することを推奨します。
クライアント設定の詳細は、SAML クライアントの作成 を 参照してください。
2.5.24. メールアクションの検証
必要なアクションまたはアプリケーション開始アクションとして電子メールアドレスを検証する場合、ユーザーはデフォルトでは 30 秒ごとにのみ検証メールを再送信できますが、以前のバージョンでは電子メールの再送に制限はありません。
管理者は、レルムの Authentication セクションの Verify Email required action で、レルムごとに間隔を設定できます。
2.5.25. 組み込み Infinispan キャッシュの拡張の追跡
トレースが有効になっている場合、Red Hat build of Keycloak クラスターの他のノードを呼び出すと、トレースにスパンが作成されるようになりました。
このようなトレースを無効にするには、オプション tracing-infinispan-enabled を false に設定します。
2.5.26. LDAP 接続のデフォルトタイムアウト
LDAP 設定で connectionTimeout または com.sun.jndi.ldap.connect.timeout システムプロパティーのいずれかの値が指定されていない場合、デフォルトのタイムアウトは 5 秒です。このタイムアウトにより、プールからの LDAP 接続の取得や LDAP サーバーへの接続時に LDAP 接続の取得を無期限で行うのではなく、エラーが表示されるようになります。
2.5.27. OTP およびリカバリーコードエントリー向けに最適化されたログインテーマ
OTP およびリカバリーコードへのログインテーマの入力フィールドが最適化されており、以下が最適化されています。
-
入力モードが数字になり
、モバイルデバイスでの入力が容易になります。 -
パスワードマネージャーとの干渉を避けるために、オートコンプリートは
ワンタイムパスワードに設定されます。
2.5.28. OIDC 認証要求のパラメーターの最大長
OIDC 認証要求（または OAuth2 認可要求）が送信されると、すべての標準的な OIDC/OAuth2 パラメーターの最大長に新しい制限が存在します。各標準パラメーターの最大長は 4,000 文字です。これは非常に大きな数値で、今後のリリースでは低くなる可能性があります。現時点では、後方互換性のために大きなものが残っています。唯一の例外は login_hint パラメーターで、最大長は 255 文字です。この値は、デフォルトのユーザープロファイル設定で設定された username および email 属性の最大長に合わせて調整されます。
これらの数値を増減する場合は、標準 OIDC/OAuth2 パラメーターのデフォルトの最大長として req-params-default-max-size でサーバーを起動し、1 つの特定のパラメーターに req-params-max-size などのものを使用することもできます。詳細は、All provider configuration の login-protocol provider configuration を参照してください。
2.5.29. メール送信元での UTF-8 の管理
今回のリリース以降、Red Hat ビルドの Keycloak は、レルム SMTP 設定に allowutf8 の新しいオプションを追加します（管理コンソールの Realm settings セクションの Email タブでUTF-8 フィールドを許可 します）。メール設定 の詳細は、レルムのメールの設定 を 参照してください。
オプションを有効にすると、送信時にメールアドレスが UTF-8 でエンコードされますが、SMTP サーバーにより SMTP サーバーでも、SMTP 拡張で UTF-8 をサポートします。Allow UTF-8 が無効な場合、Red Hat build of Keycloak は、非 ASCII 文字が使用されている場合に、メールアドレスのドメイン部分 (@ の後に続く 2 番目の部分) を punycode を使用してエンコードし、ローカル部分に非 ASCII 文字が使用されているメールアドレスを拒否します。ビルトインのユーザープロファイルメールバリデーターは、このオプションが無効になっている場合は、アドレスのローカル部分に ASCII 文字のみが含まれていることを確認し、SMTP 設定で使用できない電子メールの登録を回避します。
レルムに SMTP サーバーが設定されている場合は、アップグレード後に次の移行を実行してください。
- SMTP サーバーが SMTPUTF8 をサポートする場合は、Allow UTF- 8 オプションを有効にします。
SMTP サーバーが SMTPUTF8 をサポートしていない場合:
- Allow UTF-8 オプションは無効のままにしておきます。
- ユーザーのメールアドレスのローカル部分に非 ASCII 文字が含まれていないことを確認します。ローカル部分で ASCII 以外の文字を含むメールを検出する場合は、Verify Profile アクションを使用して、アップグレード後にユーザーに電子メールを強制的に修正できます。
2.5.30. ユーザーの数と、検索から返されたユーザーの実際の数を調整する
管理コンソールまたはユーザー API でユーザーを検索する場合、/admin/realms/{realm}/users /count エンドポイントから返されるユーザーの数は、/admin/realms/{realm} /users による検索の実行時に返される実際のユーザー 数と同じになりました。
ユーザー数のエンドポイントに依存する場合は、ユーザーが検索から返される実際のユーザー数に合致することが予想されるようにクライアントを確認してください。
2.5.31. ユーザーの認証情報が異なれば、異なる名前を付ける必要がある
OTP、WebAuthn、またはその他の 2FA 認証情報を追加する場合、ユーザーがこの認証情報に割り当てる名前は、特定のユーザーに対して一意である必要があります。これにより、ユーザーはこれらの認証情報を区別し、後で更新または削除できます。ユーザーが既存の名前で認証情報を作成しようとすると、エラーメッセージが表示され、ユーザーが新しい認証情報の名前を変更するように求められます。
2.5.32. 管理者ロールのマッピングをサーバー管理者に制限する
セキュリティーを強化するために、master レルムで admin ロールを持つユーザー (サーバー管理者) のみが管理者ロールを割り当てることができます。これにより、重要な権限がレルムレベルの管理者によって委譲されなくなります。
2.5.33. 信頼電子メールで OpenID Connect ブローカーを使用し、Sync Mode が FORCEの場合、電子メール 検証が自動的に設定されるようになりました。
これまで、OpenID Connect ブローカーは、OpenID Connect プロバイダーによって発行された ID トークンから利用可能な標準の email_verified 要求をサポートしていませんでした。
このリリースでは、ブローカーは、このクレームの値を考慮して、フェデレーション（ローカル）ユーザーアカウントのメール検証ステータスを設定するように更新されました。ユーザーが初めてフェデレーションされたとき、または再認証するときは、Trust email 設定が有効で、Sync Mode が FORCE に設定されている場合は、ユーザーアカウントが検証済み（アン）にメールにマークを付けます。プロバイダーが要求を送信しない場合は、デフォルトで元の動作に設定され、メールが検証されるように設定します。
今後は、ユースケースやコミュニティーからの需要に応じて、フェデレーションされたユーザーアカウントの電子メール検証ステータスの自動更新を回避するために、この特定の設定の変更を評価する可能性があります。
2.5.34. Verify Existing Account By Email は、アイデンティティープロバイダーから送信されたメールとユーザー名に対してのみ実行される
Verify Existing Account By Email という実行は、First Login Flow がブローカー経由のアカウントを既存の Red Hat build of Keycloak ユーザーにリンクさせるために提供する、選択肢の 1 つです。このステップは、ユーザーが初めてブローカー経由で Red Hat build of Keycloak にログインし、かつそのアイデンティティープロバイダーのアカウントが Red Hat build of Keycloak 内にすでに存在する場合に実行されます。この実行では、ユーザーがそのアカウントを管理していることを確認するため、Red Hat build of Keycloak の現在のアドレスにメールが送信されます。
このリリース以降、外部アイデンティティープロバイダーによって送信されたリンク属性 (メールとユーザー名) がレビュープロセス中にユーザーによって変更されていない場合にのみ、First Login Flow で Verify Existing Account By Email という実行が試行されます。この新しい動作により、誤ってリンクを受け入れる可能性のある既存の Red Hat build of Keycloak アカウントに検証メールが送信されることが回避されます。
プロバイダーがアイデンティティープロバイダーから送信された情報を変更する必要がある場合 (ブローカー内のメールまたはユーザー名が異なるため)、新しいアカウントを既存の Red Hat build of Keycloak ユーザーにリンクするには、他の選択肢である Verify Existing Account By Re-authentication のみを使用できます。
アイデンティティープロバイダーから受信したデータが必須であり、変更できない場合は、ユーザーの介入を回避するために、First Login Flow の Review Profile のステップを無効化できます。
詳細は、First login flow を参照してください。
2.5.35. 他のデバイスからの署名がデフォルトで無効になりました
以前は、ユーザーがパスワードの変更や OTP や Passkey などの別の要素の追加など、認証情報を更新すると、デフォルトでチェックされている 他のデバイスからの Sign out out チェックボックスがありました。このリリースでは、Red Hat build of Keycloak に、デフォルトでチェックされていない 他のデバイスからの Sign out チェックボックスが表示されます。このチェックボックスは、同じユーザーに関連付けられた他のすべての関連セッションをログアウトするために、意図的に有効にするはずです。
2.5.36. 他のデバイスからサインアウトするオフラインセッション
前のポイントに関連する Sign out from other devices チェックボックスは、通常のセッションのみをログアウトしていました。このリリースから、現在の画面設計ではユーザーが行うことが予想されるため、オフラインセッションもログアウトされるようになりました。
以前の動作に戻すには、非推奨の機能 logout-all-sessions:v1 を有効にします。この非推奨の機能は今後のバージョンで削除される予定です。
2.5.37. Welcome ページの変更
Welcome ページは、一時的なユーザーではなく、通常の管理ユーザーを作成します。
2.5.38. 粒度の細かい管理者権限：ユーザーの新しい reset-password スコープ
FGAP （粒度の細かい管理者権限）機能に、reset-password という新しいスコープが含まれるようになりました。このスコープを使用すると、管理者が広範な 管理 スコープを付与することなく、ユーザーのパスワードをリセットできるように特定のパーミッションを付与できます。
デフォルトでは、USERS リソースタイプの既存のより広範な 管理 範囲を持つユーザーには、ユーザーのパスワードをリセットするパーミッションを暗黙的に付与できます。システムは最初に明示的な reset-password スコープをチェックします。そのパーミッションが見つからない場合は、管理者が manage スコープを持っているかどうかをチェックすることにフォールバックします。これにより、manage スコープを持つ既存の管理者は、パーミッションを変更せずにパスワードをリセットできるようになります。
この暗黙的なフォールバックメカニズムにより、すでに粒度の細かいパーミッションを使用してデプロイメントのアップグレードプロセスをスムーズに行うことができます。フォールバックは非推奨になり、今後のリリースで削除されるため、管理者権限を確認して更新して、必要に応じて新しい reset-password スコープを使用することが推奨されます。
詳細は、詳細 な管理者権限 を参照してください。
2.5.39. LDAP からユーザーを検索するときのエラーは、要求に失敗しず、ローカルユーザーが返されます。
これまで、LDAP ユーザーフェデレーションプロバイダーからユーザーを検索する際に失敗すると、要求全体が失敗し、ユーザーは返されませんでした。このリリースでは、検索中にエラーが発生すると、ローカルユーザーは引き続き返され、エラーが ERROR レベルでログに記録されます。これにより、管理者は問題の原因を調査し、LDAP 設定の問題や LDAP サーバーへの接続を修正できます。
この変更により、LDAP サーバーに一時的な問題があった場合にシステムの耐障害性が改善され、LDAP 検索が失敗してもローカルユーザーに引き続きアクセスできるようになりました。ローカルユーザーが失敗した LDAP プロバイダーにリンクされている場合、ユーザーは LDAP サーバーが再び使用可能になるまで無効および読み取り専用としてマークされます。
2.5.40. serverinfo エンドポイントは、管理者レルムの管理者情報のみを返します。
このバージョン以降、管理コンソールが Red Hat build of Keycloak インストールの一般情報を取得するために使用する serverinfo エンドポイントは、管理（マスター）レルムの管理者向けのシステム情報のみを返します。この変更は、セキュリティー上の理由で行われました。
何らかの理由で、共通のレルムの管理者が serverinfo 応答の systemInfo、cpuInfo、または memoryInfo フィールドにアクセスする必要がある場合は、その管理者ユーザーに新しい view-system ロールを作成して割り当てる必要があります。
- 影響を受けるレルムで、管理クライアントの realm-management を選択し、Roles タブで view-system という名前の新規ロールを作成します。
- Users で administrator account を選択し、Role mapping タブで、作成したばかりの view-system クライアントロールを admin ユーザーに割り当てます。
以前の回避策は非推奨とマークされており、Red Hat build of Keycloak の今後のバージョンでは削除される可能性があります。
2.5.41. SimpleHttpへのリファクタリング
server-spi-private モジュールの SimpleHttp ユーティリティーがリファクタリングされ、org.keycloak.http.simple パッケージに移動されました。
2.5.42. user-profile-commons.ftl テーマテンプレートへの更新
ローカリゼーションのサポートを改善するために、user-profile-commons.ftl が変更されました。その結果、このテンプレートを拡張すると、ページが ロケール フィールドを表示し始める可能性があります。これを回避するには、上記の変更でテーマテンプレートを更新します。
2.5.43. サブグループ数がキャッシュされなくなりました
グループのサブグループを返す場合、グループの各サブグループのサブグループの数はキャッシュされなくなります。Fine-Grained Admin Permissions の導入により、レルムに定義されたパーミッションに基づいて結果セットがデータベースレベルでフィルタリングされ、これらのパーミッションに合わせてカウントが変更されます。
カウントをキャッシュする代わりに、管理者がアクセスできるグループの数を取得するために、クエリーが毎回実行されます。
ほとんどの場合、この変更は、API にクエリーを実行してグループのサブグループをフェッチするクライアントには影響しません。ただし、そうでない場合には、以下のエンドポイントに新しいパラメーター subGroupsCount が導入されました。
-
/realms/{realm}/groups/{id}/children -
/realms/{realm}/groups
このパラメーターを使用すると、クライアントは、返された各グループにカウントを返すかどうかを決定できます。既存のデプロイメントを中断しないように、このパラメーターはデフォルトで true になり、パラメーターが設定されていない場合にカウントが返されます。
2.5.44. デフォルトのブラウザーフロー変更 2FA に WebAuthn およびリカバリーコードを含める
以前のリリースでは、デフォルトの ブラウザー フローには、One-Time Password (OTP)を 2nd Factor Authentication (2FA)として有効化する Browser - Conditional OTP 条件付きサブフローがありました。このバージョン以降、サブフローの名前が Browser - Conditional 2FA に、OTP Form は Alternative に、WebAuthn Authenticator と Recovery Authentication Code Form の 2 つ以上の 2FA メソッドが含まれるようになりました。新しい実行はいずれもデフォルトでは 無効 にされていますが、Alternative に設定してフローに含めることができます。
アップグレードされたレルムは変更されません。更新されたフローは、新しいレルムでのみ使用できます。レルムの作成を自動化した場合は、この変更を考慮してください。
2.5.45. プロトコルに基づいて syslog カウント機能が有効になりました
tcp （または ssl-tcp）プロトコルを介して送信される Syslog メッセージは、デフォルトでカウントフレームを使用し、メッセージの前に一部の Syslog サーバーで必要なサイズの接頭辞を使用するようになりました。
この動作を変更するには、protocol オプションを使用します。
-dependent （デフォルト）、true、または false のいずれかの値で--log-syslog-counting-framing
2.5.46. 削除された機能と非推奨となった機能
バージョン 26.4.1 では、特定の機能が削除され、今後のリリースで削除されるようにその他の機能は非推奨としてマークされています。これらの変更の詳細は、リリースノート を参照してください。
第3章 Red Hat build of Keycloak サーバーのアップグレード
アダプターをアップグレードする前にサーバーをアップグレードします。
3.1. アップグレードの準備
サーバーをアップグレードする前に、次の手順を実行します。
手順
- Red Hat build of Keycloak をシャットダウンします。
- 設定やテーマなどの古いインストールをバックアップします。
-
XA トランザクションが有効になっている場合は、開いているトランザクションを処理し、
data/transaction-logs/トランザクションディレクトリーを削除します。 - お使いのリレーショナルデータベースのドキュメントの説明に従い、データベースをバックアップします。
アップグレード後は、データベーススキーマは古いサーバーとの互換性がなくなります。Red Hat build of Keycloak はデータベースの変更のロールバックをサポートしていないため、以前のバージョンにロールバックする必要がある場合は、まず古いインストールを復元し、次にバックアップコピーからデータベースを復元します。
現在のセットアップで persistent-user-sessions 機能が無効になっており、サーバーがアップグレードされた場合、オフラインユーザーセッションを除くすべてのユーザーセッションが失われます。これらのセッションを持つユーザーは、再度ログインする必要があります。Red Hat build of Keycloak サーバーの 26.0.0 より前のリリースでは、persistent-user-sessions 機能がデフォルトで無効になっていることに注意してください。
ブルートフォース検出の失敗したログインと現在進行中の認証フローに関する情報は、Red Hat build of Keycloak がシャットダウンされるとクリアされる内部キャッシュにのみ保存されます。現時点で、認証、パスワードの変更、またはパスワードのリセットを行っているユーザーは、Red Hat build of Keycloak が再び稼働したら、認証フローを再開する必要があります。
3.2. Red Hat build of Keycloak のダウンロード
アップグレードの準備が整ったら、サーバーをダウンロードできます。
手順
Red Hat build of Keycloak の Web サイトから rhbk-26.4.6.zip をダウンロードして展開します。
このファイルを解凍すると、
rhbk-26.4.6 という名前のディレクトリーがなければなりません。- このディレクトリーを希望の場所に移動します。
-
以前のインストールから
providers/とthemes/を新規インストールにコピーします。 -
以前のインストールの
conf/から、cache-ispn.xml以外のすべてのファイルを新しいインストールにコピーします。 cache-ispn.xmlを変更した場合、またはカスタムキャッシュ設定ファイルを作成した場合、以下を実行します。-
新しいインストールに同梱されている
cache-ispn.xmlファイルに基づいて変更を再度適用し、新しいインストールに配置します。 - キャッシュサイズとトランスポートスタックに関する最新の Red Hat build of Keycloak 設定オプションを変更の代わりに使用できる場合、それらを確認します。より適切なドキュメント、追加の検証と機能、使いやすいアップグレード操作が提供されています。
-
新しいインストールに同梱されている
3.3. データベースの移行
Red Hat build of Keycloak では、データベーススキーマを自動的に移行することも、手動で移行することもできます。デフォルトでは、新規インストールを初めて起動すると、データベースが自動的に移行されます。
データベースを移行する前に、古いバージョンの Red Hat build of Keycloak を実行しているすべての Red Hat build of Keycloak ノードをシャットダウンします。
デフォルトの H2 ベースの dev-file データベースタイプの場合、移行はサポートされていません。
3.3.1. リレーショナルデータベースの自動移行
自動移行を実行するには、目的のデータベースに接続されているサーバーを起動します。新しいサーバーバージョンでデータベーススキーマが変更すると、データベースのレコード数が多すぎない限り、移行が自動的に開始されます。
たとえば、数百万件のレコードを含むテーブルにインデックスを作成すると、時間がかかり、サービスの大きな中断を引き起こす可能性があります。したがって、自動移行には 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=3000003.3.2. 手動によるリレーショナルデータベース移行
データベーススキーマを手動でアップグレードするには、デフォルトの 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>このファイルをデータベースに適用する方法の詳細は、使用しているリレーショナルデータベースのドキュメントを参照してください。変更がファイルに書き込まれると、サーバーは終了します。
3.4. テーマの移行
カスタムテーマを作成した場合は、そのテーマを新しいサーバーに移行する必要があります。また、カスタマイズした部分によっては、組み込みテーマへの変更をカスタムテーマに反映することが必要になる場合があります。
手順
-
カスタムテーマを古いサーバーの
themesディレクトリーから新しいサーバーのthemesディレクトリーにコピーします。 次のセクションを使用して、テンプレート、メッセージ、およびスタイルを移行します。
- 移行の変更 に挙げられている更新されたテンプレートのいずれかをカスタマイズした場合は、ベーステーマのテンプレートと比較して、適用する必要のある変更があるかどうかを確認します。
- メッセージをカスタマイズした場合は、鍵または値を変更したり、追加のメッセージを追加したりする必要がある場合があります。
- スタイルをカスタマイズ済みで、Red Hat build of Keycloak のテーマを拡張する場合は、スタイルの変更を確認します。ベーステーマを拡張する場合は、この手順をスキップできます。
3.4.1. テンプレートの移行
テンプレートをカスタマイズした場合は、そのテンプレートの新しいバージョンと比較します。この比較により、カスタマイズしたテンプレートに適用する必要がある変更が示されます。差分ツールを使用してテンプレートを比較できます。次のスクリーンショットは、Login テーマの info.ftl テンプレートとカスタムテーマの例を比較したものです。
更新バージョンの Login テーマテンプレートとカスタムの Login テーマテンプレートの比較
この比較から、1 つ目の変更点 (Hello world!!) はカスタマイズであり、2 つ目の変更点 (if pageRedirectUri) はベーステーマの変更点であることがわかります。2 つ目の変更点をカスタムテンプレートにコピーすると、カスタマイズしたテンプレートが正常に更新されます。
別の方法として、次のスクリーンショットは、古いインストールの info.ftl テンプレートと新しいインストールの更新された info.ftl テンプレートを比較したものです。
古いインストールの Login テーマテンプレートと更新された Login テーマテンプレート
この比較から、ベーステンプレートの変更点がわかります。これをもとに、変更したテンプレートに同じ変更を手動で加えることができます。この方法はより複雑であるため、最初の方法が実行不可能な場合にのみ使用してください。
3.4.2. メッセージの移行
別の言語のサポートを追加した場合は、上記の変更点をすべて適用する必要があります。別の言語のサポートを追加していない場合は、何も変更する必要がない可能性があります。テーマ内の影響を受けるメッセージを変更した場合にのみ、変更を加える必要があります。
手順
- 追加された値は、ベーステーマのメッセージ値を確認し、メッセージをカスタマイズする必要があるかどうかを判断します。
- 名前が変更された鍵の場合は、カスタムテーマの鍵の名前を変更します。
- 変更された値は、ベーステーマの値を確認して、カスタムテーマに変更を加えなければならないかどうかを判断します。
3.4.3. スタイルの移行
組み込みテーマのスタイルに加えた変更を反映するには、カスタムスタイルを更新する必要がある場合があります。差分ツールを使用して、古いサーバーインストールと新しいサーバーインストール間のスタイルシートの変更を比較することを検討してください。
以下に例を示します。
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変更を確認し、それらがカスタムスタイルに影響するかどうかを判断します。
第4章 Red Hat build of Keycloak アダプターのアップグレード
Red Hat build of Keycloak サーバーをアップグレードした後、アダプターをアップグレードします。アダプターと Red Hat build of Keycloak のバージョンは分離され、異なるスケジュールでリリースされるようになりました。したがって、次のルールを使用してアップグレードするアダプターを決定します。
- 以前のバージョンのアダプターは、新しいバージョンの Red Hat build of Keycloak サーバーで動作する可能性があります。
- 以前のバージョンの Red Hat build of Keycloak サーバーは、新しいバージョンのアダプターで動作しない可能性があります。
各アダプターのアップグレードセクションでは、サポート対象のアダプターバージョンの詳細を説明しています。
4.1. JBoss EAP SAML アダプターのアップグレード
Red Hat build of Keycloak 26.0 以降、JBoss EAP SAML アダプターは Red Hat build of Keycloak とともにリリースされなくなりました。バージョン 6.x または 7.x のアダプターを使用してアプリケーションをデプロイした場合、Red Hat build of Keycloak ではサポートされません。これらのバージョンのアダプターは、Red Hat Single Sign-On 7.6 と組み合わせて使用する場合にのみサポートされます。
完全にサポートされている SAML 用のアダプターは、Keycloak SAML Adapter 機能パックまたは JBoss EAP 8.0 の RPM です。
Web アプリケーションにコピーされた JBoss EAP SAML アダプターをアップグレードするには、次の手順を実行します。
手順
-
EAP_HOME/modules/system/add-ons/keycloak/ディレクトリーを削除して、以前のアダプターモジュールを削除します。 - 新しいバージョンのアダプターをインストールします。詳細は、RPM インストール方法を使用した JBoss EAP のインストール を参照してください。
4.2. JBoss EAP OpenID Connect アダプターのアップグレード
Red Hat build of Keycloak 26.0 以降では、JBoss EAP OpenID connect (OIDC) アダプターは Red Hat build of Keycloak とともにリリースされなくなりました。このアダプターのライフサイクルは終了し、Red Hat Single Sign-On 7.6 と組み合わせて使用する場合に限りサポートされます。OIDC でサポートされるアダプターは、JBoss EAP 8.0 によって提供されます。
Web アプリケーションにコピーされた JBoss EAP OIDC アダプターをアップグレードするには、次の手順を実行します。
手順
-
EAP_HOME/modules/system/add-ons/keycloak/ディレクトリーを削除して、以前のアダプターモジュールを削除します。 - JBoss EAP 8.0 が提供する OIDC クライアントをインストールします。詳細は、OIDC によるアプリケーションの保護 を参照してください。
4.3. JavaScript アダプターのアップグレード
このリリースの Red Hat build of Keycloak では、サポートされるアダプターのサポートされるバージョンは 26.2.1 です。Web アプリケーションにコピーされた JavaScript アダプターをアップグレードするには、以下の手順を実行します。
手順
- 以前のバージョンの JavaScript アダプターを削除します。
これらの NPM コマンドを使用して、アダプターの 26.2.1 バージョンをインストールします。
npm config set @redhat:registry https://npm.registry.redhat.com install: npm install @redhat/keycloak-js@latest
npm config set @redhat:registry https://npm.registry.redhat.com install: npm install @redhat/keycloak-js@latestCopy to Clipboard Copied! Toggle word wrap Toggle overflow
4.4. Node.js アダプターのアップグレード
Red Hat build of Keycloak のこのリリースでは、このアダプターのサポート対象バージョンは 26.1.1 です。Web アプリケーションにコピーされた Node.js アダプターをアップグレードするには、以下の手順を実行します。
手順
- 以前のバージョンの Node.js アダプターを削除します。
次の NPM コマンドを使用して、Node.js アダプターの 26.1.1 バージョンをインストールします。
npm config set @redhat:registry https://npm.registry.redhat.com npm install @redhat/keycloak-connect@latest
npm config set @redhat:registry https://npm.registry.redhat.com npm install @redhat/keycloak-connect@latestCopy to Clipboard Copied! Toggle word wrap Toggle overflow -
アプリケーションの
package.jsonで keycloak-connect の依存関係を変更します。
'%20d='M201.5%20305.5c-13.8%200-24.9-11.1-24.9-24.6%200-13.8%2011.1-24.9%2024.9-24.9%2013.6%200%2024.6%2011.1%2024.6%2024.9%200%2013.6-11.1%2024.6-24.6%2024.6zM504%20256c0%20137-111%20248-248%20248S8%20393%208%20256%20119%208%20256%208s248%20111%20248%20248zm-132.3-41.2c-9.4%200-17.7%203.9-23.8%2010-22.4-15.5-52.6-25.5-86.1-26.6l17.4-78.3%2055.4%2012.5c0%2013.6%2011.1%2024.6%2024.6%2024.6%2013.8%200%2024.9-11.3%2024.9-24.9s-11.1-24.9-24.9-24.9c-9.7%200-18%205.8-22.1%2013.8l-61.2-13.6c-3-.8-6.1%201.4-6.9%204.4l-19.1%2086.4c-33.2%201.4-63.1%2011.3-85.5%2026.8-6.1-6.4-14.7-10.2-24.1-10.2-34.9%200-46.3%2046.9-14.4%2062.8-1.1%205-1.7%2010.2-1.7%2015.5%200%2052.6%2059.2%2095.2%20132%2095.2%2073.1%200%20132.3-42.6%20132.3-95.2%200-5.3-.6-10.8-1.9-15.8%2031.3-16%2019.8-62.5-14.9-62.5zM302.8%20331c-18.2%2018.2-76.1%2017.9-93.6%200-2.2-2.2-6.1-2.2-8.3%200-2.5%202.5-2.5%206.4%200%208.6%2022.8%2022.8%2087.3%2022.8%20110.2%200%202.5-2.2%202.5-6.1%200-8.6-2.2-2.2-6.1-2.2-8.3%200zm7.7-75c-13.6%200-24.6%2011.1-24.6%2024.9%200%2013.6%2011.1%2024.6%2024.6%2024.6%2013.8%200%2024.9-11.1%2024.9-24.6%200-13.8-11-24.9-24.9-24.9z'/%3e%3c/svg%3e){kind=small}