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

段階的な認証は新しい機能です。この機能は、トークンに acr 要求を追加する必要があるプロトコルマッパーが含まれる acr クライアントスコープを提供します。acr 要求は、このバージョンよりも前のように自動的に追加されなくなりましたが、このクライアントスコープおよびプロトコルマッパーを使用して追加されます。

クライアントスコープはレルムのデフォルトクライアントスコープとして追加されるため、新規に作成されるすべてのクライアントに追加されます。パフォーマンス上の理由から、クライアントスコープは移行時に既存のすべてのクライアントに自動的に追加されません。移行後に、クライアントにはデフォルトで acr 要求がありません。以下のアクションの実行について検討してください。

insert into CLIENT_SCOPE_CLIENT (CLIENT_ID, SCOPE_ID, DEFAULT_SCOPE) select CLIENT.ID as CLIENT_ID, CLIENT_SCOPE.ID as SCOPE_ID, true as DEFAULT_SCOPE
from CLIENT_SCOPE, CLIENT where CLIENT_SCOPE.REALM_ID='test' and CLIENT_SCOPE.NAME='acr' and CLIENT.REALM_ID='test' and CLIENT.PROTOCOL='openid-connect';

以前のバージョンの Red Hat Single Sign-On は、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 パラメーターを使用できる後方互換性のオプションがあります。

standalone-*.xml ファイルに以下の設定を含めると、このパラメーターを有効にすることができます。

<spi name="login-protocol">
    <provider name="openid-connect" enabled="true">
        <properties>
            <property name="legacy-logout-redirect-uri" value="true"/>
        </properties>
    </provider>
</spi>

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

以前のバージョンの Red Hat Single Sign-On は、管理コンソールや REST API などの管理インターフェイスを介して JavaScript コードの管理をサポートしていました。このバージョン以降はこれは不可能になり、以下のプロバイダーを設定するためにスクリプトをサーバーにデプロイしなければならなくなりました。

サーバーにスクリプトをデプロイする方法は、ドキュメント を参照してください。スクリプトを使用するには、テクノロジープレビュー機能の scripts を有効にする必要がある点に注意してください。

./standalone.sh -Dkeycloak.profile=preview

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

通常、レルムを更新する手順は次のとおりです。

Patternfly (PF) React ライブラリーが更新され、@patternfly/react-core が v3.153.3 から v4.147.0、@patternfly/react-icons が v3.15.16 から v 4.11.8 に、@patternfly/react-styles が v3.7.14 から v4.11.8 に更新されました。アカウントコンソールを PF 設計標準に合わせるために、マイナーな UI 更新が加えられました。

PF の重大な変更により、カスタム開発アカウント UI は、これらの更新と互換性がない場合があります。PF コンポーネントに対する提案の更新により、ほとんどの重大な変更が解決可能です。

リソース:

重大な変更が含まれることがわかっているコンポーネント:

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

Liquibase はバージョン 3.5.5 から 4.6.2 に更新されました。これには、いくつかのバグ修正や、ServiceLoader を使用してカスタム拡張機能を登録する新しい方法などが含まれます。

アップグレードガイド (特に、アップグレード前の既存データベースのバックアップ) に厳密に従います。最善の努力で Liquibase のアップグレードの結果をテストしましたが、一部のインストールで不明な特定のセットアップを使用している可能性があります。

今回のリリースにより、Red Hat Single Sign-On Operator の Keycloak CR で podDisruptionBudget フィールドが非推奨になりました。このオプションフィールドは、Operator が OCP 4.12 以降のバージョンにデプロイされると無視されます。

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

apiVersion: policy/v1
kind: PodDisruptionBudget
metadata:
  labels:
    app: keycloak
  name: keycloak
spec:
  maxUnavailable: 1
  selector:
    matchLabels:
      component: keycloak

Kubernetes のドキュメント も参照してください。

以前のバージョンの Operator で発生した 重要なバグ が原因で、RH-SSO StatefulSet の Selector フィールドが誤設定されていました。設定が間違っていると、7.5 から 7.6 のアップグレードプロセスで問題が発生し、RH-SSO デプロイメントが正常に実行されない可能性があります。

Operator パッチリリースでは修正が導入されました。修正の一環として、Operator は 7.5 から 7.6 へのアップグレード時に RH-SSO StatefulSet を削除および再作成 する可能性があることに注意してください。修正を適切に機能させるには、recreate アップグレードストラテジーを使用するようにしてください。サーバーのインストールおよび設定ガイド の関連の章を参照してください。

7.6.2 で導入された Red Hat Single Sign-On OpenShift イメージの変更に合わせて、Operator はカスタムプローブを使用する代わりに、イメージに存在するデフォルトの liveness および readiness プローブを利用するようになりました。既存の Red Hat Single Sign-On デプロイメントの場合、Operator はアップグレード中にプローブを自動的に更新しようとします。ただし、keycloak-probes ConfigMap を手動で変更してプローブをカスタマイズした場合、Operator はユーザーの変更を上書きしないようにプローブを更新しません。この状況では、プローブを手動で更新する (または Operator が再作成するために ConfigMap を削除する) 必要があります。そうしないと、アップグレードされた Red Hat Single Sign-On 7.6.2 デプロイメントは準備ができていないと表示されます。

FIPS が有効な環境での実行を許可するために、プローブ認証ハッシュアルゴリズムが変更されました。プローブのデフォルトタイムアウトが 1 秒で、CPU 制限も 1 未満に指定されているテンプレートベースのインストールでは、プローブが継続的に失敗する可能性があります。これらの失敗により再起動が行われた場合は、DeploymentConfig を変更するか、Operator で使用されているものと一致するより大きなタイムアウト値を持つ新しくリリースされたテンプレートに再調整して、プローブのタイムアウトを増やす必要があります。

ステップアップ認証に関連して、アカウントコンソール V1 には制限があります。問題は、ユーザーがパスワードを使用してアカウントコンソールバージョン 1 に対して認証し、ユーザーに TOTP 認証情報を追加するか、既存の TOTP 認証情報を削除できることです。この状況は、ユーザーのパスワードを盗んだ人が別の TOTP を追加することで、ユーザーの 2 番目の認証をバイパスできることを意味します。この問題は、アカウントコンソールバージョン 2 では発生しません(Red Hat Single Sign-On 7.6.8 でサポート)。そのバージョンでは、ユーザーの追加または削除に関する、対応するレベルのクレデンシャルを使用して、ユーザーが常に認証されます。

最善の軽減策は、ステップアップ認証を使用するときにアカウントコンソールバージョン 1 を使用しないようにすることです。アカウントコンソールバージョン 1 は、アカウントテーマが明示的に keycloak テーマに切り替わると機能します。

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"]