Chapter 3. Upgrading Red Hat Single Sign-On Server

To run the upgrade script for standalone mode, complete the following steps:

For standalone-high availability (HA) mode, all instances must be upgraded at the same time.

To run the upgrade script for standalone-HA mode, complete the following steps:

For domain mode, all instances must be upgraded at the same time.

To run the upgrade script for domain mode, complete the following steps:

For domain-clustered mode, all instances must be upgraded at the same time.

To run the upgrade script for domain-clustered mode, complete the following steps:

To enable automatic upgrading of the database schema, set the migrationStrategy property value to "update" for the default connectionsJpa provider:

 <spi name="connectionsJpa">
    <provider name="default" enabled="true">
        <properties>
            ...
            <property name="migrationStrategy" value="update"/>
        </properties>
    </provider>
</spi>

Or run this CLI command:

/subsystem=keycloak-server/spi=connectionsJpa/provider=default/:map-put(name=properties,key=migrationStrategy,value=update)

When you start the server with this setting your database is automatically migrated if the database schema has changed in the new version.

To enable manual upgrading of the database schema, set the migrationStrategy property value to "manual" for the default connectionsJpa provider:

 <spi name="connectionsJpa">
    <provider name="default" enabled="true">
        <properties>
            ...
            <property name="migrationStrategy" value="manual"/>
        </properties>
    </provider>
</spi>

Or run this CLI command:

/subsystem=keycloak-server/spi=connectionsJpa/provider=default/:map-put(name=properties,key=migrationStrategy,value=manual)

When you start the server with this configuration it checks if the database needs to be migrated. The required changes are written to an SQL file that you can review and manually run against the database. For further details on how to apply this file to the database, see the documentation for the relational database you’re using. After the changes have been written to the file, the server exits.

If you have customized any of the templates listed above you need to carefully review the changes that have been made to the templates for RH-SSO 7.1 to decide if you need to apply these changes to your customized templates. Most likely you will need to apply the same changes to your customized templates. If you have not customized any of the listed templates you can skip this section.

A best practice is to use a diff tool to compare the templates to see what changes you might need to make to your customized template. If you have only made minor changes it is simpler to compare the updated RH-SSO 7.1 template to your customized template. However, if you have made many changes it might be easier to compare the RH-SSO 7.1 template to your customized RH-SSO 7.0 template from the RH-SSO 7.0 installation, as this will show you what changes you need to make.

The following screenshot compares the info.ftl template from the Login theme and an example custom theme:

From this comparison it is easy to identify that the first change (“Hello world!!”) was a customization, while the second change (“if pageRedirectUri”) is a change to the base theme. By copying the second change to your custom template, you have successfully updated your customized template.

For the alternative approach the following screenshot compares the info.ftl template from the RH-SSO 7.0 server installation with the updated info.ftl template from the RH-SSO 7.1 server installation:

From this comparison it is easy to identify what has been changed in the base template. You will then manually have to make the same changes to your modified template. Since this approach is not as simple as the first approach, only use this approach if the first one is not feasible.

If you have added support for another language, you need to apply all the changes listed above. If you have not added support for another language, you might not need to change anything; you only have to make changes if you have changed an affected message in your theme.

For added values, review the value of the message in the base theme to determine if you need to customize that message.

For renamed keys, rename the key in your custom theme.

For changed values, check the value in the base theme to determine if you need to make changes to your custom theme.

If you are inheriting styles from the keycloak or rh-sso themes you might need to update your custom styles to reflect changes made to the styles from the built-in themes.

A best practice is to use a diff tool to compare the changes to stylesheets between the RH-SSO 7.0 server installation and the RH-SSO 7.1 server installation.

For example, using the diff command: $ diff rh-sso-7.0/themes/keycloak/login/resources/css/login.css \

rh-sso-7.1/themes/keycloak/login/resources/css/login.css

Review the changes and determine if they affect your custom styling.

You can apply downloaded patches to a RH-SSO server using either the management CLI or the management console.

You can roll back a previously applied RH-SSO patch using either the management CLI or the management console.

When patches are applied to a RH-SSO server, the content and history of the patches are preserved for use in rollback operations. If multiple cumulative patches are applied, the patch history may use a significant amount of disk space.

You can use the following management CLI command to remove all older patches that are not currently in use. When using this command, only the latest cumulative patch is preserved along with the GA release. This is only useful for freeing space if multiple cumulative patches have previously been applied.

/core-service=patching:ageout-history