第3章 Red Hat Single Sign-On サーバーのアップグレード
Red Hat Single Sign-On サーバーのアップグレードまたは移行プロセスは、以前のバージョンのソフトウェアによって異なります。
- 新規のマイナーリリース (例: 7.0.0 から 7.1.0) にアップグレードする場合は、「マイナーアップグレード」の手順を行います。
- Keycloak 9.0.x から移行する場合は、「マイナーアップグレード」の手順に従います。
- 新しいマイクロリリース (例: 7.1.0 から 7.1.1) にアップグレードする場合は、「マイクロアップグレード」の手順を行います。
3.1. マイナーアップグレード
3.1.1. アップグレードの準備
アップグレードする前に、アップグレード手順を実行する必要があります。また、アップグレードプロセス内で発生する可能性のある問題にも注意してください。通常、最初に Red Hat Single Sign-On サーバーをアップグレードしてから、アダプターをアップグレードする必要があります。
- アップグレードを適用する前に、開かれたトランザクションをすべて処理し、data/tx-object-store/ トランザクションディレクトリーを削除します。
- 以前のインストール (設定、テーマなど) をバックアップします。
- データベースをバックアップします。データベースのバックアップ方法の詳細は、使用しているリレーショナルデータベースのドキュメントを参照してください。
Red Hat Single Sign-On サーバーをアップグレードします。
- インストールの問題が本番環境で公開されないように、最初に非本番環境でアップグレードをテストすることが推奨されます。
- アップグレード後に、データベースと古いサーバーとの互換性がなくなることに注意してください。
- 実稼働環境でアダプターをアップグレードする前に、アップグレードしたサーバーが機能していることを確認します。
- アップグレードを元に戻す必要がある場合は、まず古いインストールを復元してから、バックアップコピーからデータベースを復元します。
- アダプターをアップグレードします。
3.1.2. Red Hat Single Sign-On サーバーのアップグレード
アダプターをアップグレードする前に、Red Hat Single Sign-On サーバーをアップグレードすることが重要です。
Red Hat Single Sign-On サーバーをアップグレードするには、以下の手順を実行します。
- アップグレードを適用する前に、開かれたトランザクションをすべて処理し、data/tx-object-store/ トランザクションディレクトリーを削除します。
- 新しいサーバーアーカイブのダウンロード
- ダウンロードしたアーカイブを任意の場所に移動します。
- アーカイブを展開します。この手順では、最新の Red Hat Single Sign-On リリースのクリーンインスタンスをインストールします。
スタンドアロンインストールの場合は、以前のインストールの RHSSO_HOME/standalone/ ディレクトリーを新しいインストールのディレクトリーにコピーします。
ドメインのインストールでは、以前のインストールの RHSSO_HOME/domain/ ディレクトリーを、新しいインストールのディレクトリーにコピーします。
ドメインのインストールでは、空のディレクトリー RHSSO_HOME/domain/deployments を作成します。
注記: bin ディレクトリーのファイルは、以前のバージョンのファイルで上書きしないでください。変更は手動で行う必要があります。
- modules ディレクトリーに追加されたカスタムモジュールをコピーします。
- 以下の適切なアップグレードスクリプトを実行します。
Red Hat Single Sign-On サーバー RPM ディストリビューションをアップグレードするには、以下の手順を実行します。
- アップグレードを適用する前に、開かれたトランザクションをすべて処理し、/var/opt/rh/rh-sso7/lib/keycloak/standalone/data/tx-object-store/ トランザクションディレクトリーを削除します。
JBOSS EAP および Red Hat Single Sign-On を含む適切なリポジトリーにサブスクライブしていることを確認してください。
subscription-manager repos --enable=jb-eap-7.1-for-rhel-7-server-rpms subscription-manager repos --enable=rh-sso-7.2-for-rhel-7-server-rpms
注記JBOSS EAP と Red Hat Single Sign-On の両方の古い製品リポジトリーを無効にするには、以下を実行します。
subscription-manager repos --disable=<OLDER_PRODUCT_REPO>
リポジトリーの使用を確認するには、以下を実行します。
yum repolist
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.2.1. スタンドアロンモードアップグレードスクリプトの実行
スタンドアロンモードでアップグレードスクリプトを実行するには、以下の手順を実行します。
- デフォルトの設定ファイルとは異なる設定ファイルを使用している場合は、移行スクリプトを編集して新しいファイル名を指定します。
- サーバーを停止します。
アップグレードスクリプトを実行します。
bin/jboss-cli.sh --file=bin/migrate-standalone.cli
3.1.2.2. スタンドアロン高可用性モードのアップグレードスクリプトの実行
スタンドアロン高可用性 (HA) モードでは、すべてのインスタンスを同時にアップグレードする必要があります。
standalone-HA モードのアップグレードスクリプトを実行するには、以下の手順を行います。
- デフォルトの設定ファイルとは異なる設定ファイルを使用している場合は、移行スクリプトを編集して新しいファイル名を指定します。
- サーバーを停止します。
アップグレードスクリプトを実行します。
bin/jboss-cli.sh --file=bin/migrate-standalone-ha.cli
3.1.2.3. ドメインモードアップグレードスクリプトの実行
ドメインモードでは、すべてのインスタンスを同時にアップグレードする必要があります。
ドメインモードのアップグレードスクリプトを実行するには、以下の手順を実行します。
- プロファイル名を変更した場合は、アップグレードスクリプトを編集して、スクリプトの最初の方にある変数を変更する必要があります。
- ドメインスクリプトを編集して、keycloak-server.json ファイルの場所を追加します。
- サーバーを停止します。
ドメインコントローラーでのみアップグレードスクリプトを実行します。
bin/jboss-cli.sh --file=bin/migrate-domain.cli
3.1.3. データベースの移行
Red Hat Single Sign-On は、データベーススキーマを自動的に移行するか、手動で行うこともできます。デフォルトでは、新規インストールを初めて起動すると、データベースが自動的に移行されます。
3.1.3.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)
この設定でサーバーを起動すると、データベーススキーマが新規バージョンで変更されると、データベースが自動的に移行します。
3.1.3.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.4. テーマの移行
カスタムテーマを作成している場合は、それらを新しいサーバーに移行する必要があります。組み込みテーマへの変更は、カスタマイズした内容によっては、カスタムテーマに反映する必要がある場合があります。
カスタムテーマを古いサーバーの「themes」ディレクトリーから新しいサーバーの「themes」ディレクトリーにコピーする必要があります。以下の変更を確認し、変更をカスタムテーマに適用する必要があるかどうかを考慮してください。
つまり、以下のようになります。
- 以下に挙げられている変更されたテンプレートのいずれかをカスタマイズした場合は、基本テーマのテンプレートを比較して、適用する必要のある変更があるかどうかを確認する必要があります。
- スタイルをカスタマイズし、Red Hat Single Sign-On を拡張する場合は、スタイルへの変更を確認する必要があります。ベーステーマを拡張する場合は、この手順を省略できます。
- メッセージをカスタマイズする場合は、キーまたは値を変更するか、追加メッセージの追加が必要になる場合があります。
各ステップについて、変更のリストをより詳細に説明しています。
3.1.4.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.4.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.4.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.4.4. テンプレートの移行
テンプレートのいずれかをカスタマイズする場合は、テンプレートに加えた変更を慎重に確認して、カスタマイズされたテンプレートにこれらの変更を適用する必要があるかどうかを判断します。カスタマイズされたテンプレートに同じ変更を適用する必要がある可能性が高いです。一覧表示されたテンプレートをカスタマイズしていない場合は、このセクションを飛ばすことができます。
ベストプラクティスとして、diff ツールを使用してテンプレートを比較し、カスタマイズされたテンプレートに実行する必要のある変更を確認できます。マイナーな変更のみを行った場合は、更新されたテンプレートをカスタマイズされたテンプレートと比較することが簡単になります。ただし、多くの変更を加えた場合は、新しいテンプレートをカスタマイズされた古いテンプレートと比較することが容易になるかもしれません。これにより、どのような変更が必要になるかが分かります。
次のスクリーンショットは、ログインテーマの info.ftl テンプレートとサンプルのカスタムテーマを比較しています。
ログインテーマテンプレートの更新バージョンとサンプルのカスタムログインテーマテンプレートの比較
この比較から、最初の変更 ("Hello world!!") がカスタマイズされ、2 番目の変更 ("if pageRedirectUri") がベーステーマに変更されていることを簡単に特定することができます。2 つ目の変更をカスタムテンプレートにコピーすることにより、カスタマイズされたテンプレートが正常に更新されました。
別の方法としては、以下のスクリーンショットでは、古いインストールの info.ftl テンプレートと、新しいインストールから更新された info.ftl テンプレートを比較します。
サンプルのカスタムログインテーマテンプレートと、更新されたログインテーマテンプレートの比較
この比較から、ベーステンプレートで変更されたものを簡単に特定できます。次に、変更したテンプレートに対して同じ変更を加える必要があります。このアプローチは最初のアプローチほど単純ではないため、最初のアプローチが実行可能でない場合にのみこのアプローチを使用してください。
3.1.4.5. メッセージの移行
別の言語のサポートを追加する場合は、上記のすべての変更を適用する必要があります。別の言語のサポートを追加していなかった場合は、何も変更する必要がない可能性があります。自身のテーマで影響を受けるメッセージを変更した場合に限り、変更を加える必要があります。
追加された値については、ベーステーマのメッセージ値を確認し、メッセージをカスタマイズする必要があるかどうかを判断します。
名前が変更された鍵の場合は、カスタムテーマのキーの名前を変更します。
変更された値については、ベーステーマの値を確認して、カスタムテーマに変更を加えなければならないかどうかを判断します。
3.1.4.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
変更を確認し、それらがカスタムスタイルに影響するかどうかを判断します。