Close
Identity Service

Upgrade Identity Service

Use the following information to upgrade the Identity Service to version 2.0.

Important:

  • Upgrading the Identity Service requires downtime and should be performed in a test environment before being attempted in a production environment.
  • After the upgrade the database will no longer be compatible with the old server.

Before performing an upgrade, make sure you review the recommended guidelines in the following sections:

For Keycloak’s upgrade documentation, see the Upgrading Guide.

Upgrade from version 1.2

If you are currently using the Identity Service 1.2 you must first modify the First Broker Login authentication before upgrading to version 1.8.

  1. Log into the Keycloak administration console and select the Alfresco realm.

  2. Select Authentication from the menu on the left to open the authentication configuration page.

  3. Select First Broker Login from the dropdown menu.

  4. Ensure Create User If Unique (create unique user config) flow is set to ALTERNATIVE.

Result: You can now upgrade directly to version 1.8.

Remove SmallRye references

You must manually remove all the SmallRye modules in the standalone.xml file before upgrading to version 1.8.

Important: From Keycloak 13.0.0 the modules called SmallRye have been removed from the WildFly application. The server will not start if your configuration references them.

See the Keycloak documentation Migrating to 13.0.0 for more information.

Upgrade from version 1.8

Upgrading from Identity Service 1.8.x to >= 2.0.0 implies migrating from a Wildfly to a Quarkus-based Keycloak distribution. The way Keycloak is structured, configured, and started up changed so it is recommended to go through the official Keycloak documentation to upgrade your current installation without losing critical data.

You can find the full list of potentially relevant migration changes in the Keycloak site, Migration changes, starting with the Migrating to 19.0.0 section.

Some of the most noticeable changes are:

Change Mitigation
The /auth default HTTP context path has been removed. The server should be started with --http-relative-path="/auth" to restore the context path.
The userinfo endpoint now requires the provided Access Token to have the openid scope. If you were relying on the userinfo endpoint you should make sure that your Access Tokens include the openid scope.
The userinfo endpoint error responses have changed according to Upgrading Guide. If you were relying on parsing error responses coming from this endpoint, the relevant code should be reviewed and adapted to the new behavior.
RSA_SHA1 and DSA_SHA1 algorithms have been deprecated and aren’t valid algorithms to sign SAML responses anymore. Adapt the configuration of your SAML identity provider so that it uses a valid algorithm such as SHA256 instead.

If the mitigation is not applicable, you can override the $JAVA_HOME/conf/security/java.security file and remove the relevant disallowed algorithms within jdk.xml.dsig.secureValidationPolicy instead.
The embedded H2 database has been upgraded from 1.x to 2.x, making it impossible to simply copy a previous H2 database file and use it in the newer version of Keycloak to retain the data. If you need to retain the data that was present in an H2 1.x database file, you’ll need to migrate it first to an H2 2.x compatible version before copying it into the new installation.

Upgrade ZIP installation

Use the following information to upgrade your ZIP installation:

  1. Download the alfresco-identity-service-2.0.0.zip file from Hyland Community.

  2. Unzip the ZIP file and configure your installation using the Keycloak documentation: Upgrading Keycloak.

Upgrade Kubernetes deployment with PostgreSQL database

Upgrade from chart >=1.1.0 to 2.1.0

The upgrade should be seamless.

Upgrade to chart >=3.0.0

  1. Identify your chart release name and namespace and save them into variables.

     export RELEASENAME=<Your-Release-Name>
 export RELEASENAMESPACE=<Your-Release-Namespace>

  2. Delete the postgresql StatefulSets.

     kubectl delete statefulsets.apps $RELEASENAME-postgresql-id --cascade=false --namespace $RELEASENAMESPACE

  3. Upgrade Identity Service.

     helm upgrade $RELEASENAME alfresco-stable/alfresco-identity-service --version=3.0.0 --namespace $RELEASENAMESPACE

  4. Delete the postgresql pod.

     kubectl delete pod $RELEASENAME-postgresql-id-0 --namespace $RELEASENAMESPACE

Upgrade to chart >=8.0.0

The Helm charts are now based on the newer keycloakx codecentric charts which are significantly different from the previous version and include several breaking changes. Refer to the Keycloak-X documentation to get a clearer understanding of the structure of the new charts. It’s also recommended to go through some of the examples to get familiar with the new way of enabling persistence.

You’ll find additional documentation specific to this version of Identity Service by following these links: README, helm README.

Edit this page

Suggest an edit on GitHub
By clicking "Accept Cookies", you agree to the storing of cookies on your device to enhance site navigation, analyze site usage, and assist in our marketing efforts. View Cookie Policy.