Migration Guide

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

With Red Hat build of Keycloak, you can specify additional datasources in case you need to access another database from your extensions. This option is useful if the main Red Hat build of Keycloak datasource is not viable for storing custom data, such as users.

For more details on how to connect to your own users database, see the User Storage SPI. Defining multiple datasources is similar to defining a single datasource with a key difference. You specify a name for each datasource as part of the config option name.

To use additional datasources, you first set up the JPA Persistence layer by using the

persistence.xml

For the

persistence.xml

The following is the previous configuration of the

persistence.xml

 <?xml version="1.0" encoding="UTF-8"?>
<persistence version="2.0"
             xmlns="http://java.sun.com/xml/ns/persistence" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
             xsi:schemaLocation="
        http://java.sun.com/xml/ns/persistence
        http://java.sun.com/xml/ns/persistence/persistence_2_0.xsd">
    <persistence-unit name="user-storage-jpa-example">
        <jta-data-source>java:jboss/datasources/UsersXADS</jta-data-source>

        <class>org.keycloak.quickstart.storage.user.UserEntity</class>

        <properties>
            <property name="hibernate.hbm2ddl.auto" value="update" />
            <property name="hibernate.show_sql" value="false" />
        </properties>
    </persistence-unit>
</persistence>

In Red Hat build of Keycloak, the equivalent

persistence.xml

<?xml version="1.0" encoding="UTF-8"?>
<persistence xmlns="https://jakarta.ee/xml/ns/persistence"
             xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
             xsi:schemaLocation="https://jakarta.ee/xml/ns/persistence https://jakarta.ee/xml/ns/persistence/persistence_3_0.xsd"
             version="3.0">
    <persistence-unit name="user-storage-jpa-example" transaction-type="JTA">
        <class>org.keycloak.quickstart.storage.user.UserEntity</class>
        <properties>
            <property name="jakarta.persistence.jtaDataSource" value="user-store" />
            <property name="hibernate.hbm2ddl.auto" value="update" />
            <property name="hibernate.show_sql" value="false" />
        </properties>
    </persistence-unit>
</persistence>

For example, a previous configuration of additional datasources inside the datasource subsystem might have appeared as follows:

<xa-datasource jndi-name="java:jboss/datasources/UsersXADS" pool-name="UsersXADS" enabled="true">
    <connection-url>jdbc:postgresql://mypostgres:5444/users</connection-url>
    <driver>postgresql</driver>
    <security>
        <user-name>myuser</user-name>
        <password>myuser</password>
    </security>
</xa-datasource>

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

kc.sh start
   --db-kind-user-store postgres
   --db-url-full-user-store jdbc:postgresql://mypostgres:5444/users
   --db-username-user-store myuser
   --db-password-user-store myuser

HTTP is disabled and TLS configuration is required by default, whenever the production mode (represented by the

start

You can enable HTTP with the

--http-enabled=true

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

--http-relative-path=/auth

--http-port

--https-port

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

./kc.sh start --cache=local

./standalone.sh

./kc.sh start [--cache=ispn]

./standalone.sh --server-config=standalone-ha.xml

The default values for the

--cache

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>

The most relevant configuration options are available as configuration options. For example, use the option

cache-embedded-realms-max-count

jdbc-ping

jdbc-ping

cache-embedded-network-bind-address

cache-embedded-network-external-port

cache-embedded-network-external-address

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

hostname-admin

Red Hat build of Keycloak allows you to configure which reverse proxy headers should be reflected. You can use either the

Forwarded

X-Forwarded-*

kc.sh start --proxy-headers xforwarded

--hostname-strict=false

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. Since the Java

keytool

openssl

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

${vault.realm-name_alias}

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

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

When only an append of a particular Java property is required, you specify the

JAVA_OPTS_APPEND

JAVA_OPTS

./kc.sh

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

kc.sh start --spi-connections-jpa-quarkus-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

To change the path and name of the exported SQL file, set the

migration-export

connections-jpa

kc.sh start
   --spi-connections-jpa-quarkus-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

start-dev

Red Hat build of Keycloak can use the same database instance as was previously used by Red Hat Single Sign-On 7.6. The database schema will be migrated automatically the first time Red Hat build of Keycloak connects to it.

In the Red Hat Single Sign-On 7.6 Operator, the external database connection was configured using a Secret, for example:

apiVersion: v1
kind: Secret
metadata:
  name: keycloak-db-secret
  namespace: keycloak
  labels:
    app: sso
stringData:
  POSTGRES_DATABASE:  kc-db-name
  POSTGRES_EXTERNAL_ADDRESS: my-postgres-hostname
  POSTGRES_EXTERNAL_PORT: 5432
  POSTGRES_USERNAME: user
  POSTGRES_PASSWORD: pass
type: Opaque

In Red Hat build of Keycloak , the database is configured directly in the Keycloak CR with credentials referenced as Secrets, for example:

apiVersion: k8s.keycloak.org/v2alpha1
kind: Keycloak
metadata:
  name: example-kc
spec:
  db:
    vendor: postgres
    host: my-postgres-hostname
    port: 5432
    usernameSecret:
      name: keycloak-db-secret
      key: username
    passwordSecret:
      name: keycloak-db-secret
      key: password
  ...

apiVersion: v1
kind: Secret
metadata:
  name: keycloak-db-secret
stringData:
  username: "user"
  password: "pass"
type: Opaque

Red Hat Single Sign-On 7.6 Operator by default configured the server to use the TLS Secret generated by OpenShift CA. Red Hat build of Keycloak Operator does not make any assumptions around TLS to meet production best practices and requires users to provide their own TLS certificate and key pair, for example:

apiVersion: k8s.keycloak.org/v2alpha1
kind: Keycloak
metadata:
  name: example-kc
spec:
  http:
    tlsSecret: example-tls-secret
  ...

The expected format of the secret referred to in tlsSecret should use the standard Kubernetes TLS Secret (

kubernetes.io/tls

The Red Hat Single Sign-On 7.6 Operator used the reencrypt TLS termination strategy by default on Route. Red Hat build of Keycloak Operator uses the passthrough strategy by default. Additionally, the Red Hat Single Sign-On 7.6 Operator supported configuring TLS termination. Red Hat build of Keycloak Operator does not support TLS termination in the current release.

If the default Operator-managed Route does not meet desired TLS configuration, a custom Route needs to be created by the user and the default one disabled as:

apiVersion: k8s.keycloak.org/v2alpha1
kind: Keycloak
metadata:
  name: example-kc
spec:
  ingress:
    enabled: false
  ...

To reflect best practices and support immutable containers, the Red Hat build of Keycloak Operator no longer supports specifying extensions in the Keycloak CR. In order to deploy an extension, an optimized custom image must be built. Keycloak CR now includes a dedicated field,

image

apiVersion: k8s.keycloak.org/v2alpha1
kind: Keycloak
metadata:
  name: example-kc
spec:
  image: quay.io/my-company/my-keycloak:latest
  ...

The Red Hat Single Sign-On 7.6 Operator supported recreate and rolling strategies when performing a server upgrade. This approach was not practical. It was up to the user to choose if the Red Hat Single Sign-On 7.6 Operator should scale down the deployment before performing an upgrade and database migration. It was not clear to the users when the rolling strategy could be safely used.

Therefore, the Red Hat build of Keycloak Operator will by default perform the recreate strategy, which scales down the whole deployment before creating Pods with the new server container image to ensure only a single server version accesses the database.

Users can configure two alternative update strategies Auto and Explicit which allows rolling updates in some cases. Note that also with these update strategies, only a single server version must access the database at any time.

Related to this topic, a Technology Preview Feature was introduced at version 26.4 of Red Hat build of Keycloak. For more details, see Rolling updates for patch releases.

Red Hat build of Keycloak configures the server to expose health endpoints by default that are used by OpenShift probes. The endpoints are exposed on the management interface that uses a dedicated port (9000 by default) and is accessible from within OpenShift, but not exposed by the Operator as a Route.

The Red Hat Single Sign-On 7.6 Operator exposed multiple low-level fields for deployment configuration, such as volumes. Red Hat build of Keycloak Operator is more opinionated and does not expose most of these fields. However, you can still configure any desired deployment fields specified as the

podTemplate

apiVersion: k8s.keycloak.org/v2alpha1
kind: Keycloak
metadata:
  name: example-kc
spec:
  unsupported:
    podTemplate:
      metadata:
        labels:
          foo: "bar"
      spec:
        containers:
          - volumeMounts:
              - name: test-volume
                mountPath: /mnt/test
        volumes:
          - name: test-volume
            secret:
              secretName: test-secret
  ...

spec.unsupported.podTemplate

spec.unsupported.podTemplate.spec.imagePullSecrets

spec.imagePullSecrets

The Red Hat Single Sign-On 7.6 Operator supported connecting to an external instance of Red Hat Single Sign-On 7.6. For example, creating clients within an existing realm through Client CRs is no longer supported in the Red Hat build of Keycloak Operator.

To use a Horizontal Pod Autoscaler (HPA) with Red Hat Single Sign-On 7.6, it was necessary to set the

disableReplicasSyncing: true

POSTGRESQL_IMAGE_STREAM_TAG, POSTGRESQL_MAX_CONNECTIONS, VOLUME_CAPACITY and POSTGRESQL_SHARED_BUFFERS will need to be migrated to whatever replacement you have chosen creating the database deployment.

.spec.hostname.hostname

.spec.http.httpEnabled=true.

.spec.http.tlsSecret

.spec.hostname.hostname

.spec.http.tlsSecret

.spec.hostname.hostname

.spec.http.tlsSecret

.spec.http.tlsSecret

kubernetes.io/tls

tls.crt

tls.key

.spec.truststores

Note that the Red Hat build of Keycloak Operator does not currently support a way to configure the TLS termination. By default, the passthrough strategy is used. Therefore, the proxy option is not yet exposed as a first-class citizen option field, because it does not matter whether the passthrough or reencrypt strategy is used. However, if you need this option, you can replace the default Ingress Operator certificate and manually configure a Route in order to trust Red Hat build of Keycloak’s certificate.

The default behavior of the Red Hat build of Keycloak Operator can be then overridden by:

additionalOptions:
   name: proxy
   value: reencrypt

JGROUPS_ENCRYPT_SECRET, JGROUPS_ENCRYPT_KEYSTORE, JGROUPS_ENCRYPT_NAME, JGROUPS_ENCRYPT_PASSWORD, and JGROUPS_CLUSTER_PASSWORD have no first-class representation in the Keycloak CR. The default clustering with

jdbc-ping

The supported adapter for OIDC is supplied by JBoss EAP 8.0. To upgrade a JBoss EAP OIDC adapter that has been copied to your web application, perform the following procedure.

The

Valid Post Logout Redirect URIs

+

Valid Post Logout Redirect URIs

Valid Redirect URIs

The following sections describe the UserInfo endpoint changes.

Your applications no longer need any additional dependency to integrate with Red Hat build of Keycloak or any other OpenID Provider.

Instead, you can leverage the OpenID Connect support from the JBoss EAP native OpenID Connect Client. For details, see Securing Applications with OIDC.

The JBoss EAP native adapter relies on a configuration schema very similar to the Red Hat build of Keycloak Adapter JSON Configuration. For instance, a deployment using a

keycloak.json

{
  "realm": "quickstart",
  "auth-server-url": "http://localhost:8180",
  "ssl-required": "external",
  "resource": "jakarta-servlet-authz-client",
  "credentials": {
    "secret": "secret"
  }
}

For examples about integrating Jakarta-based applications using the JBoss EAP native adapter with Red Hat build of Keycloak, see the following examples at the Red Hat build of Keycloak Quickstart Repository:

It is strongly recommended to migrate to JBoss EAP native OpenID Connect client as it is the best candidate for Jakarta applications deployed to JBoss EAP 8 and newer.

As Red Hat JBoss Enterprise Application Platform 7.x is close to ending full support, Red Hat build of Keycloak will not provide support for it. For existing applications deployed to Red Hat JBoss Enterprise Application Platform 7.x adapters with maintenance support are available through Red Hat Single Sign-On 7.6.

Red Hat Single Sign-On 7.6 adapters are supported to be used in combination with the Red Hat build of Keycloak 26.4 server.

As Red Hat JBoss Enterprise Application PlatformJBoss EAP 6.x has reached end of maintenance support, going forward neither Red Hat Single Sign-On 7.6 or Red Hat build of Keycloak will provide support for it.

As of Red Hat build of Keycloak 26.0, the JBoss EAP adapter for SAML is no longer shipped with Red Hat build of Keycloak. If you deployed an application with version 6.x or 7.x of that adapter, that adapter is not supported by Red Hat build of Keycloak. These adapters are only supported to be used in combination with the Red Hat Single Sign-On 7.6.

The fully supported adapter for SAML is the Keycloak SAML Adapter feature pack or RPM for JBoss EAP 8.0.

(

o.k.

org.keycloak.

Red Hat build of Keycloak undergoes a large refactoring to simplify the API usage, which impacts existing code. Some of these changes require updates to existing code. The following sections provide more detail.

KeycloakSession

server-spi

server-spi-private

services

KeycloakSession

KeycloakSession

KeycloakSession

UserProvider

users()

userLocalStorage()

userCache()

userStorageManager()

userFederatedStorage()

users()

KeycloakSession

clients()

groups()

*StorageManager()

*LocalStorage()

The existing providers need no migration if they do not call a removed method, which should be the case for most providers.

If the provider uses removed methods, but does not rely on local versus non-local storage, changing a call from the now removed

userLocalStorage()

users()

This before migration example shows how accessing a removed API does not compile.

session.userLocalStorage();

This post migration example shows accessing the new API when the caller does not depend on the storage API.

session.users();

In the rare case when a custom provider needs to distinguish between the mode of a particular provider, access to the deprecated objects is provided by using the

StoreManagers

This before migration example shows accessing a removed API.

session.userLocalStorage();

This post migration example shows accessing the new functionality by the StoreManagers API.

((DatastoreProvider) session.getProvider(DatastoreProvider.class)).userLocalStorage();

Some user storage related APIs have been wrapped in

org.keycloak.storage.UserStorageUtil

The methods

getUserStorageProviders

getUserStorageProvidersStream

getClientStorageProviders

getClientStorageProvidersStream

getRoleStorageProviders

getRoleStorageProvidersStream

This before migration code example will not compile due to the changed API.

realm.getClientStorageProvidersStream()...;

This post migration example casts the instance to the legacy interface.

((LegacyRealmModel) realm).getClientStorageProvidersStream()...;

Similarly, code that used to implement the interface

RealmModel

LegacyRealmModel

RealmModel

This before migration code example implements the old interface.

public class MyClass extends RealmModel {
    /* might not compile due to @Override annotations for methods no longer present
       in the interface RealmModel. / / ... */
}

This post migration code example implements the new interface.

public class MyClass extends LegacyRealmModel {
    /* ... */
}

As the caching status of objects will be transparent to services, the interface

UserCache

keycloak-storage-legacy

Code that depends on the legacy implementation should access the

UserCache

This before migration code example will not compile.

session.userCache().evict(realm, user);

This post migration example shows using the API directly.

UserStorageUitl.userCache(session);

To trigger the invalidation of a realm, instead of using the

UserCache

This before migration code example uses the cache API.

UserCache cache = session.getProvider(UserCache.class);
if (cache != null) cache.evict(realm)();

session.invalidate(InvalidationHandler.ObjectType.REALM, realm.getId());

Credentials for users were previously managed using

session.userCredentialManager().method(realm, user, ...)

user.credentialManager().method(...)

The old APIs have been removed.

Before migration: accessing a removed API.

session.userCredentialManager().createCredential(realm, user, credentialModel)

This post migration example shows accessing the new API.

user.credentialManager().createStoredCredential(credentialModel)

For a custom

UserStorageProvider

credentialManager()

UserModel

UserCredentialManager

This before migration code example will not compile due to the new method credentialManager() required by UserModel.

public class MyUserStorageProvider implements UserLookupProvider, ... {
    /* ... */
    protected UserModel createAdapter(RealmModel realm, String username) {
        return new AbstractUserAdapter(session, realm, model) {
            @Override
            public String getUsername() {
                return username;
            }
        };
    }
}

This post migration example shows the implementation of the API UserModel.credentialManager() for the store.

public class MyUserStorageProvider implements UserLookupProvider, ... {
    /* ... */
    protected UserModel createAdapter(RealmModel realm, String username) {
        return new AbstractUserAdapter(session, realm, model) {
            @Override
            public String getUsername() {
                return username;
            }

            @Override
            public SubjectCredentialManager credentialManager() {
                return new LegacyUserCredentialManager(session, realm, this);
            }
        };
    }
}