This section walks you through the steps you need to follow to upgrade from WSO2 Identity Server 5.7.0 to WSO2 Identity Server 5.8.0. In this section,
<OLD_IS_HOME> is the directory that Identity Server 5.7.0 resides in, and
<NEW_IS_HOME> is the directory that Identity Server 5.8.0 resides in.
Should I migrate?
WSO2 recommends upgrading to the latest version in order to ensure that users receive the latest updates for the product.
- For a high level overview of what has been added, changed, or deprecated in this release, see About this release.
- For a detailed overview of behavioral changes in this release, see Understanding What Has Changed.
Preparing for migration
Follow this guide before you begin migration.
Review what has been changed in this release. For a detailed list of the behavioral and architectural changes from 5.7.0 to 5.8.0, see Behavioral Changes.
This release is a WUM-only release. This means that there are no manual patches. You can use WSO2 Update Manager (WUM) to get any fixes or latest updates for this release.
If you are upgrading to use this version in your production environment, use WSO2 Update Manager to get the latest updates available for WSO2 IS 5.8.0. For more information on how to use WSO2 Update Manager, see Updating WSO2 Products.
- Take a backup of the existing database used by Identity Server 5.7.0. This backup is necessary in case the migration causes issues in the existing database.
- We recommend running the cleanup scripts before migration to clean the expired, inactive, and revoked tokens/codes. This reduces the time taken for migration.
CONN_APP_KEYunique constraint has been modified in the 5.8.0 release for Oracle and PostgreSQL databases. See the note below only for details. This step is only required if you are using an Oracle or PostgreSQL database.
Migrating the configurations
You can use one of the following approaches to migrate depending on your production environment.
Migrate by applying custom configurations to 5.8.0
Migrate by updating existing configurations with what's new in 5.7.0
Migrating the embedded LDAP user store
WSO2 does not recommend using the embedded LDAP userstore that is shipped with WSO2 Identity Server in a production environment. However, if migration of the embedded LDAP is required, follow the instructions below to migrate the existing WSO2 IS LDAP user store to the new version of WSO2 IS.
- Copy the
- Restart the server to save the changes.
Migrating the data
To upgrade to the latest version of WSO2 Identity Server, you need to upgrade the userstore database. Note that there are no registry schema changes between versions.
Follow the steps below to perform the upgrade.
- Download Identity Server 5.8.0 and unzip it in the
If you are using a DB2 environment, move indexes to the the TS32K Tablespace. The index tablespace in the '
IDN_OAUTH2_ACCESS_TOKEN' and '
IDN_OAUTH2_AUTHORIZATION_CODE' tables need to be moved to the existing TS32K tablespace in order to support newly added table indexes. To do this, execute the following stored procedure call.
Note: SQLADM or DBADM authority is required in order to invoke the
ADMIN_MOVE_TABLEstored procedure. You must also have the appropriate object creation authorities, including authorities to issue the SELECT statement on the source table and to issue the INSERT statement on the target table.
- Do the following database updates:
wso2is-migration-x.x.x.zipfile from the latest release tag of the migration resources. Unzip it to a local directory.
This folder is referred to as
org.wso2.carbon.is.migration-x.x.x.jarfile in the
<IS_MIGRATION_TOOL_HOME>/dropinsfolder into the
Copy migration-resources directory to the
Ensure that the following property values are as follows in the
migration-config.yamlfile found in the
- If you manually added any custom OSGI bundles to the
<OLD_IS_HOME>/repository/components/dropinsdirectory, copy those to the
If you manually added any JAR files to the
<OLD_IS_HOME>/repository/components/libdirectory, copy those and paste in the
.jksfiles from the
<OLD_IS_HOME>/repository/resources/securitydirectory and paste in the
- If you have created tenants in the previous WSO2 Identity Server version and if there are any resources in the
<OLD_IS_HOME>/repository/tenantsdirectory, copy the content to the
If you have created secondary user stores in the previous WSO2 IS version, copy the content in the
<OLD_IS_HOME>/repository/deployment/server/userstoresdirectory to the
Start the Identity Server 5.8.0 with the following command to perform the data migration for all components.
- Once the migration is successful, stop the server and start using the appropriate command.
Verifying the migration
Follow the steps below to verify if the migration has been completed successfully.
Go through the logs and check if each migration step has completed successfully without any error logs.
- Run functional tests against the migrated deployment to verify that all functionality is working as expected.