第2章 リリース固有の変更

古いホスト名オプションが削除されたため、ホスト名 v2 オプションがデフォルトでサポートされます。

必要な移行のリスト:

ご覧のとおり、hostname および hostname-admin オプションの *-url 接尾辞は削除されました。オプション hostname は、ホスト名と URL の両方を受け入れますが、hostname-admin は現在完全な URL のみを受け入れます。

また、path や port を個別に設定する方法はありません。これは、hostname と hostname-admin オプションの完全な URL を指定することで実現できます。

ポートが URL の一部でない場合は、受信リクエストヘッダーから動的に解決されます。

HTTPS は、hostname および hostname-admin URL の一部でない限り、強制されなくなりました。指定されていない場合、使用されるプロトコル (http/https) は受信リクエストから動的に解決されます。hostname-strict-https オプションは削除されました。

# Hostname v1
bin/kc.[sh|bat] start --hostname=mykeycloak.org --https-port=8543 --hostname-path=/auth --hostname-strict-https=true

# Hostname v2
bin/kc.[sh|bat] start --hostname=https://mykeycloak.org:8543/auth

# Hostname v1
bin/kc.[sh|bat] start --hostname=mykeycloak.org --hostname-strict-backchannel=true

# Hostname v2
bin/kc.[sh|bat] start --hostname=mykeycloak.org --hostname-backchannel-dynamic=false

kcadm と kcreg がオプションとパラメーターを解析して処理する方法が変更されました。使用方法エラー、間違ったオプションまたはパラメーターからのエラーメッセージは、以前のバージョンとは若干異なる場合があります。また、使用方法エラーの場合、終了コードは 1 ではなく 2 になります。

Red Hat build of Keycloak はグループパス内のスラッシュをエスケープしたことはありません。そのため、top の子である group/slash という名前のグループは、完全なパス /top/group/slash を使用しますが、これは明らかに誤解を招きます。このバージョンから、サーバーを起動して名前内のスラッシュをエスケープできるようになりました。

bin/kc.[sh|bat] start --spi-group-jpa-escape-slashes-in-group-path=true

エスケープ文字はチルダ文字 ~ です。前の例では、パスは /top/group~/slash になります。エスケープは、最後のスラッシュを階層区切りではなく、名前の一部としてマークします。

エスケープは動作の変更を表すため、現在デフォルトでは無効になっています。ただし、エスケープを有効にすることが推奨されており、今後のバージョンではこれがデフォルトになる可能性があります。

マスターレルムが存在する前に、--import-realm オプションを指定して start または start-dev コマンドを実行すると、インポートマテリアルにマスターレルムが存在する場合はインポートされます。以前の動作では、マスターレルムが最初に作成され、その後そのインポートがスキップされていました。

--optimized 起動オプションでは、最初に最適化されたサーバーイメージをビルドすることが必要になりました。これは、最初に kc.sh|bat build を実行するか、--optimized フラグなしで他の任意のサーバーコマンド (start、export、import など) を実行することによって実現できます。

オプション cache、cache-stack、cache-config-file はビルドオプションではなくなり、ランタイム時のみ指定できます。これにより、ビルドフェーズを実行してイメージを再ビルドする必要がなくなります。これらは build フェーズでは認識されないため、build フェーズから削除して runtime フェーズに追加する必要があることに注意してください。現在のキャッシュオプションを runtime フェーズに追加しない場合、Red Hat build of Keycloak はデフォルトのキャッシュ設定に戻ります。

ブローカリングなどの一部のシナリオでは、Red Hat build of Keycloak は HTTP を使用して外部サーバーと通信します。これらのプロバイダーが大量のデータを送信した場合にサービス拒否が発生するのを回避するために、Red Hat build of Keycloak では、デフォルトで応答が 10 MB に制限されるようになりました。

ユーザーは、プロバイダー設定オプション spi-connections-http-client-default-max-consumed-response-size を設定することでこの制限を設定できます。

bin/kc.[sh|bat] --spi-connections-http-client-default-max-consumed-response-size=1000000

kc.[sh|bat] import コマンドでプレースホルダーの置換が有効になりました。以前は、プレースホルダーの置換は起動時のレルムのインポートに対してのみ有効になっていました。

import コマンドのプレースホルダー置換を無効にする場合は、システムプロパティー -Dkeycloak.migration.replace-placeholders=false を追加します。