Note that these instructions have been tested for migration from WSO2 IS 5.0.0 to 5.4.0 only with the ORACLE database.
The following sections provide instructions that enable you to upgrade from older versions of WSO2 Identity Server (from version 5.0.0 onwards) to the latest version of WSO2 Identity Server. In this topic,
<OLD_IS_HOME> is the directory that the older version of WSO2 Identity Server resides in, and
<NEW_IS_HOME> is the directory that the latest version of WSO2 Identity Server resides in.
Before you begin
This release is a WUM-only release. This means that there are no manual patches. Any further fixes or latest updates for this release can be updated through WSO2 Update Manager (WUM).
- If you are upgrading to use this version in your production environment, use the WSO2 Update Manager to get the latest updates available for WSO2 IS. For more information on how to do this, see Updating WSO2 Products.
Migrating the embedded LDAP user store
It is not generally recommended to use the embedded LDAP user store that is shipped with WSO2 Identity Server in production setups. 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 configurations
You can use one of the following approaches to migrate depending on your production evironment.
Migrating by updating the custom configurations
Migrating by updating the new configurations in 5.2.0
Migrating the custom components
Any custom OSGI bundles which were added manually should be recompiled with new dependency versions that are relevant to the new WSO2 IS version. All custom OSGI components reside in the
- Get the source codes of the custom OSGI components located in the
Change the dependency versions in the relevant POM files according to the WSO2 IS version that you are upgrading to, and compile them. The compatible dependency versions for each release of WSO2 IS is given below.
If you come across any compile time errors, refer to the WSO2 IS code base and make the necessary changes related to that particular component version.
<OLD_IS_HOME>/repository/components/libdirectory, add newly compiled versions of those components to the
Migrating the data
To upgrade the version of WSO2 Identity Server, the user store database should be upgraded. Note that there are no registry schema changes between versions.
Follow the steps below as needed to complete the migration process.
Download the latest version of WSO2 Identity Server and unzip it in the
- Take a backup of the existing database used by the
<OLD_IS>.This backup is necessary in case the migration causes issues in the existing database.
Make the following database updates as indicated below.
Download the migration resources and unzip it to a local directory. This folder is referred to as
snakeyaml-1.16.0.wso2v1.jarfound in the
<IS_MIGRATION_TOOL_HOME>folder, and paste it in the
Copy migration-resources folder to the
Set the following property values accordingly in the
migration-config.yamlfile found in the
<NEW_IS_HOME>/migration-resourcesfolder. Specify the current WSO2 Identity Server version as the
currentVersionvalue and specify the new version of WSO2 Identity Server that you want to migrate to, as the
- Copy any custom OSGI bundles that were added manually from the
<OLD_IS_HOME>/repository/components/dropinsfolder and paste it in the
Copy any added JAR files from the
<OLD_IS_HOME>/repository/components/libfolder and paste it in the
.jksfiles from the
<OLD_IS_HOME>/repository/resources/securityfolder and paste them in
- 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
Note: If your current version is 5.0.0, run the following queries on the database that is referenced in the
identity.xmlfile in order to identify if there is any corrupted data.
Start WSO2 Identity Server with the following command to perform the data migration for all components.
Once the migration is successful, stop the server and remove the following files and folders from the