2.6. その他の変更点

org.keycloak.representations.idm.UserRepresentation と org.keycloak.representations.account.UserRepresentation の両方の表現クラスが変更されました。これにより、ルートユーザー属性 (username、email、firstName、lastName、locale など) が、それぞれ Admin API と Account API から表現ペイロードを取得または送信するときに一貫した表現を使用するようになりました。

username、email、firstName、lastName、locale 属性が、新しい org.keycloak.representations.idm.AbstractUserRepresentation ベースクラスに移動しました。

なお、getAttributes メソッドはカスタム属性のみを表すことを目的としたものです。そのため、このメソッドによって返されるマップにルート属性が含まれることを期待しないでください。このメソッドは主に、特定のユーザーのカスタム属性を更新または取得するクライアントを対象としています。

ルート属性を含むすべての属性を解決するために、新しい getRawAttributes メソッドが追加されました。これにより、結果のマップにルート属性も含まれるようになりました。ただし、このメソッドは表現ペイロードからは利用できません。ユーザープロファイルを管理するときにサーバーによって使用されることを目的としたものです。

オプション https-client-auth は、実行時のオプションとして扱われていましたが、これは Quarkus ではサポートされていません。代わりに、このオプションはビルド時に処理する必要があります。

このリリースから、Red Hat build of Keycloak クラスターの最初のメンバーが、リモートセッションを並行してではなく順番にロードするようになります。オフラインセッションのプリロードが有効になっている場合は、それらも順番にロードされます。

以前のコードでは、起動時にクラスター全体でリソース消費量が多くなり、実稼働環境での分析が困難で、ロード中にノードが再起動した場合に複雑な障害が発生する可能性がありました。そのため、セッションの順次ロードに変更になりました。

このバージョンおよび以前のバージョンの Red Hat build of Keycloak では、デフォルトでオフラインセッションをオンデマンドでロードします。これにより、オフラインセッションが多数ある場合は、それらを並行してプリロードするよりもスケーラビリティーが向上します。このデフォルト設定を使用するセットアップは、オフラインセッションのロードストラテジーの変更による影響を受けません。オフラインセッションの事前ロードが有効なセットアップは、オフラインセッションのプリロードが無効なセットアップに移行する必要があります。

Red Hat build of Keycloak の組み込みキャッシュのメトリクスを有効にしたときに、メトリクスがキャッシュマネージャーとキャッシュ名のラベルを使用するようになりました。

vendor_cache_manager_keycloak_cache_sessions_statistics_approximate_entries_in_memory{cache="sessions",node="..."}

vendor_statistics_approximate_entries_in_memory{cache="sessions",cache_manager="keycloak",node="..."}

インストールに対する変更を元に戻すには、カスタム Infinispan XML 設定を使用して、次のように設定を変更します。

<metrics names-as-tags="false" />

このリリース以降、Red Hat build of Keycloak は、以前は制限されていた 255 文字を超えるユーザー属性値の保存と検索をサポートします。

ユーザーがアカウントコンソールなどを使用して属性を更新できるセットアップでは、検証を追加してサービス拒否攻撃を防止してください。管理対象外の属性が許可されていないこと、およびすべての編集可能な属性に入力長を制限する検証があることを確認してください。

管理対象外の属性の場合、最大長は 2048 文字です。管理対象の属性の場合、デフォルトの最大長は 2048 文字です。管理者は、length タイプのバリデーターを追加することでこれを変更できます。

この変更により、テーブル USER_ATTRIBUTE および FED_USER_ATTRIBUTE に新しいインデックスが追加されます。これらのテーブルに 300000 を超えるエントリーが含まれている場合、Red Hat build of Keycloak は、デフォルトで自動スキーマ移行中にインデックスの作成をスキップし、Red Hat build of Keycloak の起動後に手動で適用できるように、代わりに移行中にコンソールに SQL ステートメントを記録します。異なる制限を設定する方法の詳細は、アップグレードガイド を参照してください。

PUT /admin/realms/{realm}/users/{id}/send-verify-email

このリリースでは、この API は executeActions.ftl の代わりに email-verification.ftl テンプレートを使用します。

Perform the following action(s): Verify Email

Confirm validity of e-mail address email@example.org.

この API を使用したユーザーのメールアドレスの検証方法を変更するために executeActions.ftl テンプレートをカスタマイズした場合は、変更内容を新しいテンプレートに移してください。

デフォルトの有効期間の値 (12 時間) をオーバーライドできるように、lifespan という新しいパラメーターが導入されます。

以前の動作を希望する場合は、次のように execute-actions-email API を使用してください。

PUT /admin/realms/{realm}/users/{id}/execute-actions-email

["VERIFY_EMAIL"]

このリリースでは、パスワードハッシュ化のデフォルトを、パスワード保存に関する OWASP の推奨事項 に合わせて調整しました。

この変更の一環として、デフォルトのパスワードハッシュ化プロバイダーが pbkdf2-sha256 から pbkdf2-sha512 に変更になりました。また、pbkdf2 ベースのパスワードハッシュ化アルゴリズムのデフォルトハッシュ反復回数が次のように変更になりました。

レルムが hashAlgorithm と hashIterations を使用してパスワードポリシーを明示的に設定していない場合、新しい設定は次回のパスワードベースのログイン時、またはユーザーパスワードが作成または更新されたときに有効になります。

マップストアの削除後に、次の設定オプションの名前が変更されました。

ブルートフォースプロテクターによってユーザーが一時的にロックアウトされた場合に、新しいイベント USER_DISABLED_BY_TEMPORARY_LOCKOUT が発生するようになりました。新しいイベントは情報を構造化された形式で提供するため、ID KC-SERVICES0053 のログは削除されました。

これは成功イベントであるため、新しいイベントはデフォルトで DEBUG レベルでログに記録されます。すべての成功イベントのログレベルを変更するには、サーバー管理ガイドのイベントリスナーの章 で説明されているように、spi-events-listener-jboss-logging-success-level 設定を使用します。

カスタムアクションまたはカスタムログエントリーをトリガーするには、サーバー開発者ガイド のイベントリスナー SPI の説明に従って、カスタムイベントリスナーを作成します。

Keycloak JS を Red Hat build of Keycloak から直接ロードする場合は、このセクションを無視しても問題ありません。NPM パッケージから Keycloak JS をロードし、Webpack、Vite などのバンドラーを使用している場合は、コードにいくつかの変更を加える必要がある可能性があります。Keycloak JS パッケージは、package.json ファイルの exports フィールド を使用するようになりました。つまり、インポートを変更する必要がある可能性があります。

// Before
import Keycloak from 'keycloak-js/dist/keycloak.js';
import AuthZ from 'keycloak-js/dist/keycloak-authz.js';

// After
import Keycloak from 'keycloak-js';
import AuthZ from 'keycloak-js/authz';

Red Hat build of Keycloak が内部トークン (Red Hat build of Keycloak 自体によって消費される JWT、たとえばリフレッシュトークンやアクショントークン) に署名するために使用するアルゴリズムが、HS256 からよりセキュアな HS512 に変更されます。hmac-generated-hs512 という名前の新しいキープロバイダーがレルムに追加されました。移行されたレルムでは、古い hmac-generated プロバイダーと古い HS256 キーが維持され、アップグレード前に発行されたトークンが引き続き検証されることに注意してください。古いトークンが存在しなくなったら、鍵のローテーションガイドライン に従って、HS256 プロバイダーを手動で削除できます。

コンテナー内で実行する場合の JVM オプション -Xms および -Xmx が、-XX:InitialRAMPercentage と -XX:MaxRAMPercentage に置き換えられました。Red Hat build of Keycloak は、静的な最大ヒープサイズ設定ではなく、コンテナーメモリーの合計の 70% に最大値を指定します。

ヒープサイズはコンテナーの合計メモリーに基づいて動的に計算されるため、コンテナーの メモリー制限を必ず設定 してください。

詳細は、異なるメモリー設定を指定する を参照してください。

RFC 9207 OAuth 2.0 Authorization Server Issuer Identification 仕様で、セキュアな認証応答を実現するために、OAuth 2.0/OpenID Connect Authentication Response に iss パラメーターが追加されました。

過去のリリースにはこのパラメーターはありませんでしたが、仕様の要求に従って、Red Hat build of Keycloak にはデフォルトでこのパラメーターが追加されました。

ただし、一部の OpenID Connect/OAuth2 アダプター、特に Red Hat build of Keycloak の古いアダプターでは、この新しいパラメーターで問題が発生する可能性があります。

たとえば、クライアントアプリケーションへの認証に成功すると、パラメーターは常にブラウザー URL に表示されます。このような場合は、認証応答への iss パラメーターの追加を無効にすると役立つことがあります。これは、「古いアダプターとの互換性」 で説明されているとおり、Red Hat build of Keycloak 管理コンソールで、OpenID Connect Compatibility Modes を含むセクション内のクライアントの詳細で特定のクライアントに対して行うことができます。専用の Exclude Issuer From Authentication Response スイッチが存在します。これをオンにすると、認証応答に iss パラメーターが追加されるのを防ぐことができます。

JPA では検索時にワイルドカード % と _ を使用できますが、LDAP などの他のプロバイダーでは * のみを使用できます。* は、LDAP では自然なワイルドカード文字であるため、すべての場所で機能しますが、JPA では検索文字列の先頭と末尾でのみ機能していました。このリリース以降、ワイルドカード文字 * だけが、検索文字列内のすべての場所で、すべてのプロバイダーで一貫して機能するようになりました。JPA の % や _ など、特定のプロバイダー内のすべての特殊文字はエスケープされます。引用符を追加した完全一致検索 (例: "w*ord") の動作は、以前のリリースと同じままです。

このリリースより前は、Multivalued 設定が無効になっていると、レルム (User Realm Role) とクライアント (User Client Role) の両方のプロトコルマッパーが、文字列化された JSON 配列をマッピングしていました。

しかし、Multivalued 設定は、クレームをリストとしてマッピングするか、同じ値リストからの単一の値のみをマッピングするか (設定が無効な場合) を示すものです。

このリリースでは、ロールマッパーとクライアントマッパーが、単一値とマークされている場合 (Multivalued が無効な場合) に、ユーザーの有効なロールからの単一の値にマッピングされるようになりました。

このバージョンでは、パスワード入力を非表示/表示を切り替えるトグルを導入する予定です。

一般的に、すべての <input type="password" name="password"/> が div 内にカプセル化されるようになりました。input 要素の後に、パスワード入力の表示を切り替えるボタンが続きます。

以前のコードの例:

<input type="password" id="password" name="password" autocomplete="current-password" style="display:none;"/>

新しいコードの例:

<div class="${properties.kcInputGroup!}">
    <input type="password" id="password" name="password" autocomplete="current-password" style="display:none;"/>
    <button class="pf-c-button pf-m-control" type="button" aria-label="${msg('showPassword')}"
            aria-controls="password" data-password-toggle
            data-label-show="${msg('showPassword')}" data-label-hide="${msg('hidePassword')}">
        <i class="fa fa-eye" aria-hidden="true"></i>
    </button>
</div>

kc.sh が、パラメーターおよび環境変数 JAVA_OPTS_APPEND と JAVA_ADD_OPENS に対して追加のシェル eval を使用しなくなりました。そのため、二重のエスケープ/引用符の使用を継続すると、パラメーターが誤解されることになります。以下に例を示します。

bin/kc.sh start --db postgres --db-username keycloak --db-url "\"jdbc:postgresql://localhost:5432/keycloak?ssl=false&connectTimeout=30\"" --db-password keycloak --hostname localhost

このような場合は、代わりに単一のエスケープを使用してください。

bin/kc.sh start --db postgres --db-username keycloak --db-url "jdbc:postgresql://localhost:5432/keycloak?ssl=false&connectTimeout=30" --db-password keycloak --hostname localhost

また、この変更により、すべての引数を単一の引用符で囲んだ値を使用して kc.sh を呼び出すことができなくなります。たとえば、以下は使用できなくなりました。

bin/kc.sh "start --help"

個別の引数を使用する必要があります。

bin/kc.sh start --help

同様に、以下は使用できなくなりました。

bin/kc.sh build "--db postgres"

個別の引数を使用する必要があります。

bin/kc.sh build --db postgres

Dockerfile 実行コマンドでも個別の引数の使用が必要です。

最上位レベルのグループを検索して参照できるようにする新しいメソッドが追加されました。このインターフェイスを実装する場合は、次のメソッドを実装する必要があります。

Stream<GroupModel> getTopLevelGroupsStream(RealmModel realm,
                                           String search,
                                           Boolean exact,
                                           Integer firstResult,
                                           Integer maxResults)

ページネーションをサポートする特定のグループのサブグループを取得する方法として、エンドポイント GET {keycloak server}/realms/{realm}/groups/{group_id}/children が追加されました。

RESTEasy Classic が利用不可になり、選択することができなくなりました。RESTEasy Classic および org.jboss.resteasy.spi.* に含まれる関連パッケージに依存している SPI およびコードは、移行が必要になります。

エンドポイント POST {keycloak server}/realms/{realm}/partial-export と、管理コンソールの対応するアクションの実行に必要な権限が、view-realm ではなく manage-realm になりました。このエンドポイントはレルム設定を JSON ファイルにエクスポートするものであるため、新しい権限のほうが適切です。パラメーター exportGroupsAndRoles と exportClients は、同じ権限 (query-groups と view-clients) を引き続き管理します。これらのパラメーターは、それぞれレルムグループ/ロールとクライアントをエクスポートに追加します。

バージョン 1.8.0 で、リダイレクト URI をクライアントの指定された有効なリダイレクトと比較する際に、ホスト名とスキームに小文字が導入されました。ただし、これはすべてのプロトコルで完全に機能したわけではありません。たとえば、ホストが http では小文字で、https では小文字ではない場合がありました。OAuth 2.0 セキュリティーの現在のベストプラクティス では、厳密な文字列照合を使用して URI を比較するよう推奨しています。そのため、Red Hat build of Keycloak はこの推奨事項に従い、現時点では、ホスト名とスキームについても、大文字と小文字を厳密に区別して有効なリダイレクトを比較しています。

古い動作に依存しているレルムの場合は、クライアントの有効なリダイレクト URI に、サーバーによって認識される URI ごとに個別のエントリーが保持されるようになりました。

クライアントを設定する際の手順と詳細度は増加しますが、新しい動作により、よりセキュアなデプロイメントが可能になります。パターンベースのチェックがセキュリティー問題の原因となることが多いためです。チェックの実装方法だけでなく、設定方法も原因となります。

バージョン 23.0.0 で、Groups リソースに新しいエンドポイント getSubGroups ("children") が導入されましたが、パラメーターの briefRepresentation が、サブグループの完全な表現を取得することを意味していました。この意味が、短い表現を返すように変更になりました。

jboss-logging メッセージの値が、引用符 (デフォルトでは文字 ") で囲まれ、改行を防ぐためにサニタイズされるようになりました。プロバイダーに、新しい動作をカスタマイズできる 2 つの新しいオプション (spi-events-listener-jboss-logging-sanitize と spi-events-listener-jboss-logging-quotes) があります。たとえば、サニタイズと引用符の付加の両方を回避するには、次のようにしてサーバーを起動します。

./kc.sh start --spi-events-listener-jboss-logging-sanitize=false --spi-events-listener-jboss-logging-quotes=none ...

オプションの詳細は、すべてのプロバイダー設定 を参照してください。