This document is work in progress and will be released with the 5.4.0 GA release.
The following instructions guide you through upgrading from WSO2 Identity Server 5.3.0 to WSO2 Identity Server 5.4.0. In this topic,
<OLD_IS_HOME> is the directory that Identity Server 5.3.0 resides in and
<NEW_IS_HOME> is the directory that Identity Server 5.4.0 resides in.
Before you begin
This release is a WUM-only release. This means that there are no manual patches and any further fixes or latest updates for this release can be updated through the WSO2 Update Manager (WUM).
- If you are upgrading to this version to use this version in your production environment, use the WSO2 Update Manager and get the latest available updates for WSO2 IS 5.4.0. 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 IS 5.3.0 LDAP user store to IS 5.4.0.
- Copy the
- Restart the server to save the changes.
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 Identity Server 5.4.0 and unzip it in the
- Take a backup of the existing database used by Identity Server 5.3.0. This backup is necessary in case the migration causes issues in the existing database.
- Make the database script updates as indicated below.
Download the migration resources and unzip it to a local directory. This folder is referred to as
migration-dbscriptsfolder in the
<IS5.4.0_MIGRATION_TOOL_HOME>/dbscripts/directory to the
- Copy the
org.wso2.carbon.is.migrate.client-5.4.0.jarfile in the
<IS5.4.0_MIGRATION_TOOL_HOME>/dropinsdirectory to the
- Alternatively, if you are using Oracle database, you can either provide the database owner credentials in the datasource configurations (identity and user management databases) or pass the identity database owner name with -
DidentityOracleUserand user management database owner name with -
- 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
The ClaimManagementService API is not recommended for use with WSO2 IS 5.3.0. If you are using the ClaimManagementService API and have written any clients using the service, convert the clients to the new and improved ClaimMetaDataManagementService API that is packaged with WSO2 IS 5.3.0.
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.4.0
Start the Identity Server 5.4.0 with the following command to perform the data migration for all components.
See the notes below to perform migration for individual components or for active tenants only.
Migrate individual components
Optional: To migrate certain components only, use the relevant commands in the table below.
Warning! Unless specifically required, it is recommended to perform the full data migration by executing the command given above. Component migration is intended for certain special cases only, and may cause errors due to incomplete migration, if done incorrectly.Click here to view the commands
Component Linux/Unix Windows Identity Database Schema Claim Data Email Template Data Permission Data Challenge Question Data Resident IdP MetaData OIDC Scope Data
Migrate active tenants only
Optional:If you have any disabled/inactive tenants in your previous version of WSO2 IS that you do not want to bring forward to the next version, do a complete migration for all components with active tenants only.Click here to view the command
Start the server against the migration client jar located in the
<IS_HOME>/repository/components/dropinsdirectory using the
-DmigrateActiveTenantsOnlyflag, as shown below.
- Once the migration is successful, stop the server and start using the appropriate command.
If you have switched off the account disabling feature, open the identity.xml file and ensure that this property exists.
If not, add the property to the file.
As this property will only apply at first startup of the server or for new tenant creations, switch off the account disabling feature via the management console as well. For more information on how to do this, see Account Disabling.