第3章 Red Hat Single Sign-On サーバーのアップグレード

スタンドアロンモードでアップグレードスクリプトを実行するには、以下の手順を実行します。

スタンドアロン高可用性 (HA) モードでは、すべてのインスタンスを同時にアップグレードする必要があります。

standalone-HA モードのアップグレードスクリプトを実行するには、以下の手順を行います。

ドメインモードでは、すべてのインスタンスを同時にアップグレードする必要があります。

ドメインモードのアップグレードスクリプトを実行するには、以下の手順を実行します。

データベーススキーマの自動アップグレードを有効にするには、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)

この設定でサーバーを起動すると、データベーススキーマが新規バージョンで変更されると、データベースが自動的に移行します。

データベーススキーマを手動でアップグレードするには、デフォルトの 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 ファイルに書き込まれます。このファイルをデータベースに適用する方法の詳細は、使用しているリレーショナルデータベースのドキュメントを参照してください。変更がファイルに書き込まれると、サーバーは終了します。

Templates

Messages

Styles

Templates

Messages

Styles

Templates

Messages

Styles

テンプレートのいずれかをカスタマイズする場合は、テンプレートに加えた変更を慎重に確認して、カスタマイズされたテンプレートにこれらの変更を適用する必要があるかどうかを判断します。カスタマイズされたテンプレートに同じ変更を適用する必要がある可能性が高いです。一覧表示されたテンプレートをカスタマイズしていない場合は、このセクションを飛ばすことができます。

ベストプラクティスとして、diff ツールを使用してテンプレートを比較し、カスタマイズされたテンプレートに実行する必要のある変更を確認できます。マイナーな変更のみを行った場合は、更新されたテンプレートをカスタマイズされたテンプレートと比較することが簡単になります。ただし、多くの変更を加えた場合は、新しいテンプレートをカスタマイズされた古いテンプレートと比較することが容易になるかもしれません。これにより、どのような変更が必要になるかが分かります。

次のスクリーンショットは、ログインテーマの info.ftl テンプレートとサンプルのカスタムテーマを比較しています。

この比較から、最初の変更 ("Hello world!!") がカスタマイズされ、2 番目の変更 ("if pageRedirectUri") がベーステーマに変更されていることを簡単に特定することができます。2 つ目の変更をカスタムテンプレートにコピーすることにより、カスタマイズされたテンプレートが正常に更新されました。

別の方法としては、以下のスクリーンショットでは、古いインストールの info.ftl テンプレートと、新しいインストールから更新された info.ftl テンプレートを比較します。

この比較から、ベーステンプレートで変更されたものを簡単に特定できます。次に、変更したテンプレートに対して同じ変更を加える必要があります。このアプローチは最初のアプローチほど単純ではないため、最初のアプローチが実行可能でない場合にのみこのアプローチを使用してください。

別の言語のサポートを追加する場合は、上記のすべての変更を適用する必要があります。別の言語のサポートを追加していなかった場合は、何も変更する必要がない可能性があります。自身のテーマで影響を受けるメッセージを変更した場合に限り、変更を加える必要があります。

追加された値については、ベーステーマのメッセージ値を確認し、メッセージをカスタマイズする必要があるかどうかを判断します。

名前が変更された鍵の場合は、カスタムテーマのキーの名前を変更します。

変更された値については、ベーステーマの値を確認して、カスタムテーマに変更を加えなければならないかどうかを判断します。

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

変更を確認し、それらがカスタムスタイルに影響するかどうかを判断します。