Chapter 2. Migrating a Red Hat Single Sign-On 7.6 server

In contrast to Red Hat Single Sign-On 7.6, Red Hat build of Keycloak has built-in support for the supported databases removing the need to manually install and configure the database drivers. The exception is Oracle and Microsoft SQL Server, which still require manual installation of the drivers.

In terms of configuration, consider the datasource subsystem from your existing Red Hat Single Sign-On 7.6 installation and map those configurations to the options available from the Database configuration category in Red Hat build of Keycloak . For example, a previous configuration appears as follows:

<datasource jndi-name="java:jboss/datasources/KeycloakDS" pool-name="KeycloakDS" enabled="true" use-java-context="true" statistics-enabled="true">
    <connection-url>jdbc:postgresql://mypostgres:5432/mydb?currentSchema=myschema</connection-url>
    <driver>postgresql</driver>
    <pool>
        <min-pool-size>5</min-pool-size>
        <max-pool-size>50</max-pool-size>
    </pool>
    <security>
        <user-name>myuser</user-name>
        <password>myuser</password>
    </security>
</datasource>

In Red Hat build of Keycloak , the equivalent configuration using CLI parameters would be:

kc.sh start
   --db postgres
   --db-url-host mypostgres
   --db-url-port 5432
   --db-url-database mydb
   --db-schema myschema
   --db-pool-min-size 5 --db-pool-max-size 50
   --db-username myser --db-password myuser

HTTP is disabled and TLS configuration is required by default, whenever the production mode (represented by the start option) is used.

You can enable HTTP with the --http-enabled=true configuration option, but it is not recommended unless the Red Hat build of Keycloak server is within a fully isolated network, and no risk exists of internal or external attackers being able to observe networking traffic.

A Red Hat build of Keycloak instance has a different context root (URL path) as it uses the root of the server while Red Hat Single Sign-On 7.6 by default appends /auth. To mimic the old behavior, the --http-relative-path=/auth configuration option can be used. The default ports remain the same, but they can also be changed by the --http-port and --https-port options.

Two ways exist to configure TLS, either through files in the PEM format or with a Java Keystore. For example, a previous configuration by Java Keystore appears as follows:

<tls>
	<key-stores>
            <key-store name="applicationKS">
                 <credential-reference
		 clear-text="password"/>
		 <implementation type="JKS"/>
                 <file
   path="/path/to/application.keystore”/>
            </key-store>
     </key-stores>
     <key-managers>
        <key-manager name="applicationKM"
         key-store="applicationKS">
               <credential-reference
          clear-text="password"/>
        </key-manager>
     </key-managers>
     <server-ssl-contexts>
         <server-ssl-context name="applicationSSC"
     key-manager="applicationKM"/>
     </server-ssl-contexts>
</tls>

In Red Hat build of Keycloak , the equivalent configuration using CLI parameters would be as follows:

kc.sh start
   --https-key-store-file /path/to/application.keystore
   --https-key-store-password password

In Red Hat build of Keycloak , you can configure TLS by providing certificates in PEM format as follows:

kc.sh start
   --https-certificate-file /path/to/certfile.pem
   --https-certificate-key-file /path/to/keyfile.pem

Red Hat Single Sign-On 7.6 provided distinct operating modes for running the server as standalone, standalone clustered, and domain clustered. These modes differed in the start script and configuration files. Red Hat build of Keycloak offers a simplified solution with a single start script: kc.sh.

To run the server as standalone or standalone clustered, use the kc.sh script:

The default values for the --cache parameter is start mode aware:

In Red Hat Single Sign-On 7.6, clustering and cache configuration was done through the Infinispan subsystem, while in Red Hat build of Keycloak the majority of the configuration is done through a separate Infinispan configuration file. For example, a previous configuration of Infinispan appears as follows:

<subsystem xmlns="urn:jboss:domain:infinispan:13.0">
<cache-container name="keycloak" marshaller="JBOSS" modules="org.keycloak.keycloak-model-infinispan">
                <local-cache name="realms">
                    <heap-memory size="10000"/>
                </local-cache>
                <local-cache name="users">
                    <heap-memory size="10000"/>
                </local-cache>
                <local-cache name="sessions"/>
                <local-cache name="authenticationSessions"/>
                <local-cache name="offlineSessions"/>
			...
</cache-container>
</subsystem>

In Red Hat build of Keycloak , the default Infinispan configuration file is located in the conf/cache-ispn.xml file. You can provide your own Infinispan configuration file and specify it using the CLI parameter as follows:

kc.sh start --cache-config-file my-cache-file.xml

The only improvement is the possibility to override the stack defined in the cache configuration file by providing a CLI option cache-stack, which takes precedence. Consider a part of the Infinispan configuration file my-cache-file.xml, specified above, with the custom JGroups transport stack as follows:

You can notice the transport stack for the keycloak cache container is set to tcp, but it can be overridden using the CLI option as follows:

<jgroups>
	<stack name=”my-encrypt-udp” extends=”udp”>
		…
	</stack>
</jgroups>

<cache-container name=”keycloak”>
	<transport stack=”tcp”/>
	…
</cache-container>

kc.sh start
   --cache-config-file my-cache-file.xml
   --cache-stack my-encrypt-udp

After executing the above commands, the my-encrypt-udp transport stack is used.

In Red Hat build of Keycloak, you are now obligated to configure the Hostname SPI in order to set how front and back end URLs are going to be created by the server when redirecting users or communicating with their clients.

For example, consider if you have a configuration similar as the follows in your Red Hat Single Sign-On 7.6 installation:

<spi name="hostname">
      <default-provider>default</default-provider>
      <provider name="default" enabled="true">
           <properties>
              <property name="frontendUrl" value="myFrontendUrl"/>
              <property name="forceBackendUrlToFrontendUrl" value="true"/>
           </properties>
      </provider>
</spi>

You can translate it to the following configuration options in Red Hat build of Keycloak:

kc.sh start
    --hostname myFrontendUrl

The hostname configuration option allows you to set the base URL where the cluster is exposed to the public from an ingress layer running in front of your cluster. You can also set the URL for administration resources by setting the hostname-admin configuration option.

Red Hat build of Keycloak allows you to configure which reverse proxy headers should be reflected. You can use either the Forwarded header or the set of X-Forwarded-* headers. For example:

kc.sh start --proxy-headers xforwarded

The truststore is used for external TLS communication, for example HTTPS requests and LDAP servers. To use a truststore, you import the remote server’s or CA’s certificate into the trustore. Then, you can start the Red Hat build of Keycloak server specifying the system truststore.

For example, a previous configuration appears as follows:

<spi name="truststore">
    <provider name="file" enabled="true">
        <properties>
            <property name="file" value="path/to/myTrustStore.jks"/>
            <property name="password" value="password"/>
            <property name="hostname-verification-policy" value="WILDCARD"/>
        </properties>
    </provider>
</spi>

Red Hat build of Keycloak supports truststores in the following formats: PEM files, or PKCS12 files with the extensions .p12 and .pfx. For the PKCS12 files, the certs must be unencrypted, which means that no password is expected. The JKS truststores need to be converted. For example:

keytool -importkeystore -srckeystore path/to/myTrustStore.jks \
   -destkeystore path/to/myTrustStore.p12 \
   -srcstoretype jks \
   -deststoretype pkcs12
   -srcstorepass password
   -deststorepass “”

In this example, the resulting CLI parameter would be as follows:

kc.sh start
    --truststore-paths path/to/myTrustStore.p12
    --tls-hostname-verifier WILDCARD

The Keystore Vault is an implementation of the Vault SPI and it is useful for storing secrets in bare metal installations. This vault is a replacement of the Elytron Credential Store in Red Hat Single Sign-On 7.6..

<spi name="vault">
     <provider name="elytron-cs-keystore" enabled="true">
        <properties>
            <property name="location" value="path/to/keystore.p12"/>
             <property name="secret" value="password"/>
     </properties>
   </provider>
</spi>

In Red Hat build of Keycloak, the equivalent configuration using CLI parameters would be:

kc.sh start
   --vault keystore
   --vault-file /path/to/keystore.p12
   --vault-pass password

Secrets stored in the vault can be then accessed at multiple places within the Admin Console. When it comes to the migration from the existing Elytron vault to the new Java KeyStore-based vault, no realm configuration changes are required. If a newly created Java keystore contains the same secrets, your existing realm configuration should work.

Given that you use the default REALM_UNDERSCORE_KEY key resolver, the secret can be accessed by ${vault.realm-name_alias} (for example, in your LDAP User federation configuration) the same way as before.

The approach for JVM settings in Red Hat build of Keycloak is similar to the Red Hat Single Sign-On 7.6 approach. You still need to set particular environment variables, however, the /bin folder contains no configuration files, such as standalone.conf.

Red Hat build of Keycloak provides various default JVM arguments, which proved to be suitable for the majority of deployments as it provides good throughput and efficiency in memory allocation and CPU overhead. Also, other default JVM arguments ensure a smooth run of the Red Hat build of Keycloak instance, so use caution when you change the arguments for your use case.

To change JVM arguments or GC settings, you set particular environment variables, which are specified as Java options. For a complete override of these settings, you specify the JAVA_OPTS environment variable.

When only an append of a particular Java property is required, you specify the JAVA_OPTS_APPEND environment variable. When no JAVA_OPTS environment variable is specified, the default Java properties are used and can be found inside the ./kc.sh script.

For instance, you can specify a particular Java option as follows:

export JAVA_OPTS_APPEND=-XX:+HeapDumpOnOutOfMemoryError
kc.sh start

Configuration for SPI providers is available through the new configuration system. This is the old format:

<spi name="<spi-id>">
    <provider name="<provider-id>" enabled="true">
        <properties>
            <property name="<property>" value="<value>"/>
        </properties>
    </provider>
</spi>

This is the new format:

spi-<spi-id>-<provider-id>-<property>=<value>

Use these commands for troubleshooting:

To perform an automatic migration, start the server connected to the desired database. If the database schema has changed for the new version of the server, it will be migrated.

To enable manual upgrading of the database schema, set the migration-strategy property value to manual for the default connections-jpa provider:

kc.sh start --spi-connections-jpa-legacy-migration-strategy manual

When you start the server with this configuration, it checks if the database needs to be migrated. The required changes are written to the bin/keycloak-database-update.sql SQL file that you can review and manually run against the database.

To change the path and name of the exported SQL file, set the migration-export property for the default connections-jpa provider:

kc.sh start
   --spi-connections-jpa-legacy-migration-export <path>/<file.sql>

For further details on how to apply this file to the database, see the documentation for your relational database. After the changes have been written to the file, the server exits.

To try out Red Hat build of Keycloak without worrying about supplying any properties, you can start the distribution in the development mode as described in the table below. However, note that this mode is strictly for development and should not be used in production.

Red Hat build of Keycloak has a dedicated start mode for production: ./kc.sh start. The difference from running with start-dev is different default configuration values. It automatically uses a strict and by-default secured configuration setup. In the production mode, HTTP is disabled, and explicit TLS and hostname configuration is required.