第3章 Red Hat Single Sign-On サーバーのアップグレード
Red Hat Single Sign-On サーバーのアップグレードまたは移行プロセスは、以前のバージョンのソフトウェアによって異なります。
- 新規のマイナーリリース (例: 7.5.x から 7.6) にアップグレードする場合は、マイナーアップグレード の手順に従います。
- Keycloak 18.0.0 から移行する場合は、マイナーアップグレード の手順に従います。
- 新しいマイクロリリース (例: 7.5.2 から 7.5.3) にアップグレードする場合は、マイクロアップグレード の手順に従います。
3.1. マイナーアップグレードの実行
3.1.1. アップグレードの準備
アップグレードする前に、アップグレード手順を実行する必要があります。特に、アダプターをアップグレードする前に Red Hat Single Sign-On サーバーをアップグレードするようにしてください。
Red Hat Single Sign-On のマイナーアップグレードでは、すべてのユーザーセッションが失われます。アップグレード後に、すべてのユーザーは再度ログインする必要があります。
手順
- 以前のインストール (設定、テーマなど) をバックアップします。
- お使いのリレーショナルデータベースのドキュメントの説明に従い、データベースをバックアップします。
Red Hat Single Sign-On サーバーをアップグレードします。
アップグレード後は、データベースは古いサーバーと互換性がありません。
- アップグレードを元に戻す必要がある場合は、まず古いインストールを復元してから、バックアップコピーからデータベースを復元します。
- アダプターをアップグレードします。
3.1.2. Red Hat Single Sign-On サーバーのアップグレード
以下のガイドラインに従って、サーバーが正常にアップグレードされるようにします。
- アップグレードを実稼働以外の環境で最初にテストし、実稼働環境でインストールの問題が発生しないようにします。
- アダプターをアップグレードする前に、Red Hat Single Sign-On サーバーをアップグレードします。また、アダプターをアップグレードする前に、実稼働環境でアップグレードしたサーバーが機能していることを確認します。
このアップグレード手順では、インストールに固有の手動変更により変更が必要になる場合があります。アップグレードに影響する可能性のある手動の変更に関する詳細は、リリース固有の変更 を参照してください。
インストールに使用した方法に基づいて、サーバーを ZIP ファイル または RPM からアップグレードします。
3.1.2.1. ZIP ファイルからのサーバーのアップグレード
前提条件
- 開かれたトランザクションをすべて処理し、data/tx-object-store/ トランザクションディレクトリーを削除します。
手順
- 新しいサーバーアーカイブをダウンロードします。
- ダウンロードしたアーカイブを任意の場所に移動します。
- アーカイブをデプロイメントします。この手順では、最新の Red Hat Single Sign-On リリースのクリーンインスタンスをインストールします。
スタンドアロンインストールの場合は、以前のインストールの
RHSSO_HOME/standalone/ディレクトリーを新しいインストールのディレクトリーにコピーします。ドメインのインストールでは、以前のインストールの
RHSSO_HOME/domain/ディレクトリーを、新しいインストールのディレクトリーにコピーします。ドメインのインストールでは、空のディレクトリー
RHSSO_HOME/domain/deploymentsを作成します。注記: bin ディレクトリーのファイルは、以前のバージョンのファイルで上書きしないでください。変更は手動で行う必要があります。
- modules ディレクトリーに追加されたカスタムモジュールをコピーします。
- サーバーのアップグレードスクリプトの実行 セクションに進みます。
3.1.2.2. RPM からのサーバーのアップグレード
前提条件
- 開かれたトランザクションをすべて処理し、/var/opt/rh/rh-sso7/lib/keycloak/standalone/data/tx-object-store/ トランザクションディレクトリーを削除します。
手順
Red Hat Single Sign-On を含む適切なリポジトリーにサブスクライブします。
Red Hat Enterprise Linux 7 の場合:
subscription-manager repos --enable=rh-sso-7.6-for-rhel-7-x86_64-rpms
Red Hat Enterprise Linux 8 の場合:
subscription-manager repos --enable=rh-sso-7.6-for-rhel-8-x86_64-rpms
Red Hat Single Sign-On の古い製品リポジトリーを無効にします。
subscription-manager repos --disable=rh-sso-7.5-for-rhel-8-x86_64-rpms
リポジトリーのリストを確認します。
dnf repolist
Updating Subscription Management repositories. repo id repo name rh-sso-7.6-for-rhel-8-x86_64-rpms Single Sign-On 7.6 for RHEL 8 x86_64 (RPMs) rhel-8-for-x86_64-appstream-rpms Red Hat Enterprise Linux 8 for x86_64 - AppStream (RPMs) rhel-8-for-x86_64-baseos-rpms Red Hat Enterprise Linux 8 for x86_64 - BaseOS (RPMs)
- 変更した設定ファイルとカスタムモジュールをバックアップします。
dnf upgradeを使用して、新しい Red Hat Single Sign-On バージョンにアップグレードします。RPM のアップグレードプロセスでは、変更した設定ファイルは置き換えられません。代わりに、このプロセスで、新しい Red Hat Single Sign-On バージョンのデフォルト設定に .rpmnew ファイルを作成します。
- 新しいサブシステムなど、新リリースの新機能をアクティベートするには、各 .rpmnew ファイルを既存の設定ファイルに手動でマージする必要があります。
- modules ディレクトリーに追加されたカスタムモジュールをコピーします。
サーバーのアップグレードスクリプトの実行 セクションに進みます。
注記Red Hat Single Sign-On RPM サーバーディストリビューションが使用している
RHSSO_HOME=/opt/rh/rh-sso7/root/usr/share/keycloak以下の移行スクリプトを呼び出す場合に使用します。
3.1.3. サーバーのアップグレードスクリプトの実行
以前のインストールに基づいて、お使いの状況に適した適切なアップグレードスクリプトを実行します。
3.1.3.1. スタンドアロンモードのアップグレードスクリプトの実行
手順
- デフォルトの設定ファイルとは異なる設定ファイルを使用している場合は、移行スクリプトを編集して新しいファイル名を指定します。
- サーバーを停止します。
アップグレードスクリプトを実行します。
bin/jboss-cli.sh --file=bin/migrate-standalone.cli
3.1.3.2. スタンドアロン高可用性モードのアップグレードスクリプトの実行
スタンドアロン高可用性 (HA) モードでは、すべてのインスタンスを同時にアップグレードする必要があります。
手順
- デフォルトの設定ファイルとは異なる設定ファイルを使用している場合は、移行スクリプトを編集して新しいファイル名を指定します。
- サーバーを停止します。
アップグレードスクリプトを実行します。
bin/jboss-cli.sh --file=bin/migrate-standalone-ha.cli
3.1.3.3. ドメインモードアップグレードスクリプトの実行
ドメインモードでは、すべてのインスタンスを同時にアップグレードする必要があります。
手順
- プロファイル名を変更した場合は、アップグレードスクリプトを編集して、スクリプトの最初の方にある変数を変更する必要があります。
- ドメインスクリプトを編集して、keycloak-server.json ファイルの場所を追加します。
- サーバーを停止します。
ドメインコントローラーでアップグレードスクリプトを実行します。
bin/jboss-cli.sh --file=bin/migrate-domain.cli
3.1.3.4. ドメインクラスター化されたモードアップグレードスクリプトの実行
ドメインクラスター化されたモードでは、すべてのインスタンスを同時にアップグレードする必要があります。
手順
- プロファイル名を変更した場合は、アップグレードスクリプトを編集して、スクリプトの最初の方にある変数を変更する必要があります。
- ドメインクラスター化されたスクリプトを編集して、keycloak-server.json ファイルの場所を追加します。
- サーバーを停止します。
ドメインコントローラーでのみアップグレードスクリプトを実行します。
bin/jboss-cli.sh --file=bin/migrate-domain-clustered.cli
3.1.4. データベースの移行
Red Hat Single Sign-On は、データベーススキーマを自動的に移行するか、手動で行うこともできます。デフォルトでは、新規インストールを初めて起動すると、データベースが自動的に移行されます。
3.1.4.1. リレーショナルデータベースの自動移行
データベーススキーマの自動アップグレードを有効にするには、migrationStrategy プロパティーの値をデフォルトの connectionsJpa プロバイダーに対して update に設定します。
<spi name="connectionsJpa">
<provider name="default" enabled="true">
<properties>
...
<property name="migrationStrategy" value="update"/>
</properties>
</provider>
</spi>または、この CLI コマンドを実行します。
/subsystem=keycloak-server/spi=connectionsJpa/provider=default/:map-put(name=properties,key=migrationStrategy,value=update)
この設定でサーバーを起動すると、データベーススキーマが新規バージョンで変更されると、データベースが自動的に移行します。
数百万のレコードを含む大規模テーブルのインデックスを作成すると、簡単に時間がかかる可能性があり、アップグレード時に主要なサービスが中断される可能性があります。このような場合は、自動インデックス作成のしきい値 (レコード数) を追加しています。デフォルトでは、このしきい値は 300000 レコードです。レコードの数がしきい値を上回る場合、インデックスは自動的に作成されず、後で手動で適用できる SQL コマンドを含む、サーバーログに警告メッセージが表示されます。
しきい値を変更するには、indexCreationThreshold プロパティー、デフォルトの connectionsLiquibase プロバイダーの値を設定します。
<spi name="connectionsLiquibase">
<provider name="default" enabled="true">
<properties>
<property name="indexCreationThreshold" value="300000"/>
</properties>
</provider>
</spi>または、この CLI コマンドを実行します。
/subsystem=keycloak-server/spi=connectionsLiquibase/:add(default-provider=default)
/subsystem=keycloak-server/spi=connectionsLiquibase/provider=default/:add(properties={indexCreationThreshold => "300000"},enabled=true)3.1.4.2. 手動によるリレーショナルデータベース移行
データベーススキーマを手動でアップグレードするには、デフォルトの connectionJpa プロバイダーについて migrationStrategy プロパティーの値を manual に設定します。
<spi name="connectionsJpa">
<provider name="default" enabled="true">
<properties>
...
<property name="migrationStrategy" value="manual"/>
</properties>
</provider>
</spi>または、この CLI コマンドを実行します。
/subsystem=keycloak-server/spi=connectionsJpa/provider=default/:map-put(name=properties,key=migrationStrategy,value=manual)
この設定でサーバーを起動すると、データベースの移行が必要であるかどうかを確認します。必要な変更は、データベースに対して手動で確認および実行できる SQL ファイルに書き込まれます。このファイルをデータベースに適用する方法の詳細は、使用しているリレーショナルデータベースのドキュメントを参照してください。変更がファイルに書き込まれると、サーバーは終了します。
3.1.5. テーマの移行
カスタムテーマを作成している場合は、それらを新しいサーバーに移行する必要があります。組み込みテーマへの変更は、カスタマイズした内容によっては、カスタムテーマに反映する必要がある場合があります。
カスタムテーマを古いサーバーの themes ディレクトリーから新しいサーバーの themes ディレクトリーにコピーする必要があります。以下の変更を確認し、変更をカスタムテーマに適用する必要があるかどうかを考慮してください。
つまり、以下のようになります。
- 以下に挙げられている変更されたテンプレートのいずれかをカスタマイズした場合は、基本テーマのテンプレートを比較して、適用する必要のある変更があるかどうかを確認する必要があります。
- スタイルをカスタマイズし、Red Hat Single Sign-On を拡張する場合は、スタイルへの変更を確認する必要があります。ベーステーマを拡張する場合は、この手順を省略できます。
- メッセージをカスタマイズする場合は、キーまたは値を変更するか、追加メッセージの追加が必要になる場合があります。
各ステップについて、変更のリストをより詳細に説明しています。
3.1.5.1. Theme changes RH-SSO 7.3
Templates
- Account: account.ftl
- Account: applications.ftl
- Account: resource-detail.ftl (new)
- Account: resources.ftl (new)
- Account: template.ftl
- Account: totp.ftl
- Email-html: email-test.ftl
- Email-html: email-verification-with-code.ftl (new)
- Email-html: email-verification.ftl
- Email-html: event-login_error.ftl
- Email-html: event-removed_totp.ftl
- Email-html: event-update_password.ftl
- Email-html: event-update_totp.ftl
- Email-html: executeActions.ftl
- Email-html: identity-provider-link.ftl
- Email-html: password-reset.ftl
- Email-text: email-verification-with-code.ftl (new)
- Email-text: email-verification.ftl
- Email-text: executeActions.ftl
- Email-text: identity-provider-link.ftl
- Email-text: password-reset.ftl
- Login: cli_splash.ftl (new)
- Login: code.ftl
- Login: error.ftl
- Login: info.ftl
- Login: login-config-totp-text.ftl (new)
- Login: login-config-totp.ftl
- Login: login-idp-link-confirm.ftl
- Login: login-idp-link-email.ftl
- Login: login-oauth-grant.ftl
- Login: login-page-expired.ftl
- Login: login-reset-password.ftl
- Login: login-totp.ftl
- Login: login-update-password.ftl
- Login: login-update-profile.ftl
- Login: login-verify-email-code-text.ftl (new)
- Login: login-verify-email.ftl
- Login: login-x509-info.ftl
- Login: login.ftl
- Login: register.ftl
- Login: template.ftl
- Login: terms.ftl
- Welcome: index.ftl (new)
Messages
- Account: messages_en.properties
- Admin: admin-messages_en.properties
- Email: messages_en.properties
- Login: messages_en.properties
Styles
- Login: login-rhsso.css (new)
- Welcome: welcome-rhsso.css
3.1.5.2. Theme changes RH-SSO 7.2
Templates
- Account: account.ftl
- Account: applications.ftl
- Account: federatedIdentity.ftl
- Account: password.ftl
- Account: sessions.ftl
- Account: template.ftl
- Account: totp.ftl
- Admin: index.ftl
- Email: email-test.ftl (new)
- Email: email-verification.ftl
- Email: event-login_error.ftl
- Email: event-removed_totp.ftl
- Email: event-update_password.ftl
- Email: event-update_totp.ftl
- Email: executeActions.ftl
- Email: identity-provider-link.ftl
- Email: password-reset.ftl
- Login: bypass_kerberos.ftl (removed)
- Login: error.ftl
- Login: info.ftl
- Login: login-config-totp.ftl
- Login: login-idp-link-email.ftl
- Login: login-oauth-grant.ftl
- Login: login-page-expired.ftl (new)
- Login: login-reset-password.ftl
- Login: login-totp.ftl
- Login: login-update-password.ftl
- Login: login-update-profile.ftl
- Login: login-verify-email.ftl
- Login: login-x509-info.ftl (new)
- Login: login.ftl (new)
- Login: register.ftl (new)
- Login: template.ftl (new)
- Login: terms.ftl (new)
Messages
- Account: messages_en.properties
- Admin: admin-messages_en.properties
- Admin: messages_en.properties
- Email: messages_en.properties
- Login: messages_en.properties
Styles
- Account: account.css
- Login: login.css
3.1.5.3. Theme changes RH-SSO 7.1
Templates
- Account: account.ftl
- Account: federatedIdentity.ftl
- Account: totp.ftl
- Login: info.ftl
- Login: login-config-totp.ftl
- Login: login-reset-password.ftl
- Login: login.ftl
Messages
- Account: editAccountHtmlTtile renamed to editAccountHtmlTitle
- Account: role_uma_authorization added
- Login: loginTotpStep1 value changed
- Login: invalidPasswordGenericMessage added
- Login: invlidRequesterMessage renamed to invalidRequesterMessage
- Login: clientDisabledMessage added
Styles
- Account: account.css
- Login: login.css
3.1.5.4. テンプレートの移行
テンプレートのいずれかをカスタマイズする場合は、テンプレートに加えた変更を慎重に確認して、カスタマイズされたテンプレートにこれらの変更を適用する必要があるかどうかを判断します。カスタマイズされたテンプレートに同じ変更を適用する必要がある可能性が高いです。リスト表示されたテンプレートをカスタマイズしていない場合は、このセクションを飛ばすことができます。
ベストプラクティスとして、diff ツールを使用してテンプレートを比較し、カスタマイズされたテンプレートに実行する必要のある変更を確認できます。マイナーな変更のみを行った場合は、更新されたテンプレートをカスタマイズされたテンプレートと比較することが簡単になります。ただし、多くの変更を加えた場合は、新しいテンプレートをカスタマイズされた古いテンプレートと比較することが容易になるかもしれません。これにより、どのような変更が必要になるかが分かります。
次のスクリーンショットは、ログインテーマの info.ftl テンプレートとサンプルのカスタムテーマを比較しています。
ログインテーマテンプレートの更新バージョンとサンプルのカスタムログインテーマテンプレートの比較
この比較から、最初の変更 (Hello world!!) がカスタマイズされ、2 番目の変更 (if pageRedirectUri) がベーステーマに変更されていることを簡単に特定することができます。2 つ目の変更をカスタムテンプレートにコピーすることにより、カスタマイズされたテンプレートが正常に更新されました。
別の方法としては、以下のスクリーンショットでは、古いインストールの info.ftl テンプレートと、新しいインストールから更新された info.ftl テンプレートを比較します。
ログインテーマテンプレートと、更新されたログインテーマテンプレートの比較
この比較から、ベーステンプレートで変更されたものを簡単に特定できます。次に、変更したテンプレートに対して同じ変更を加える必要があります。このアプローチは最初のアプローチほど単純ではないため、最初のアプローチが実行可能でない場合にのみこのアプローチを使用してください。
3.1.5.5. メッセージの移行
別の言語のサポートを追加する場合は、上記のすべての変更を適用する必要があります。別の言語のサポートを追加していなかった場合は、何も変更する必要がない可能性があります。自身のテーマで影響を受けるメッセージを変更した場合に限り、変更を加える必要があります。
追加された値については、ベーステーマのメッセージ値を確認し、メッセージをカスタマイズする必要があるかどうかを判断します。
名前が変更された鍵の場合は、カスタムテーマのキーの名前を変更します。
変更された値については、ベーステーマの値を確認して、カスタムテーマに変更を加えなければならないかどうかを判断します。
3.1.5.6. スタイルの移行
keycloak または rh-sso テーマからスタイルを継承している場合は、組み込みテーマからスタイルに加えられた変更を反映するようにカスタムスタイルの更新が必要になる場合があります。
ベストプラクティスは、diff ツールを使用して、古いサーバーインストールと新しいサーバーインストールとの間でスタイルシートへの変更を比較することです。
たとえば、diff コマンドを使用します。
$ diff RHSSO_HOME_OLD/themes/keycloak/login/resources/css/login.css \ RHSSO_HOME_NEW/themes/keycloak/login/resources/css/login.css
変更を確認し、それらがカスタムスタイルに影響するかどうかを判断します。
