We recommend migrating directly to one of the latest stable releases of WSO2 Identity Server (i.e., version 5.6.0 or a later version). For instructions on migrating directly to a later version, see Upgrading From an Older Version of WSO2 IS.
The following instructions guide you through upgrading from WSO2 Identity Server 5.1.0 to WSO2 Identity Server 5.2.0.
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). Please note the following:
- 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.2.0. For more information on how to do this, see Updating WSO2 Products.
- If you are upgrading to this version only to do an incremental upgrade to the next available version (e.g., if you are upgrading from WSO2 IS 5.1.0 - 5.3.0), you can skip this step and migrate to 5.2.0 by following the steps given in this document. You do not need to use WUM in this instance because the WUM updates available for this version will be included in the WSO2 IS pack of the next version.
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.1.0 LDAP user store to IS 5.2.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.
In this topic,
<OLD_IS_HOME> is the directory that Identity Server 5.1.0 resides in and
<NEW_IS_HOME> is the directory that Identity Server 5.2.0 resides in.
- Download Identity Server 5.2.0 and unzip it in the
- Take a backup of the existing database used by Identity Server 5.1.0. This backup is necessary in case the migration causes issues in the existing database.
- Make a copy of the
- Copy the following files from the
<NEW_IS_HOME>/repository/conffolder and paste it in the copy of the
<OLD_IS_HOME>/repository/confdirectory in the relevant sub folder:
<NEW_IS_HOME>/repository/conffolder with the modified copy of the
- Configure the <NEW_IS_HOME>/repository/conf/carbon.xml file with the same configurations made in the <OLD_IS_HOME>/repository/conf/carbon.xml file.
<NEW_IS_HOME>/repository/conf/identity/identity.xmlfile and add the
<PoolSize>tag under the
<SessionDataPersist>tag with the default value as 200, if you have not already done so. If <SessionDataPersist> is commented out, be sure to uncomment it.
<NEW_IS_HOME>/repository/conf/claim-config.xmlfile and add the following new claims.
- Copy any custom OSGI bundles that were added manually from the
<OLD_IS_HOME>/repository/components/dropinsfolder and paste it in the
- Copy the
.jksfiles from the
<OLD_IS_HOME>/repository/resources/securityfolder and paste them in
- If you have created tenants in the previous Identity Server copy content in the
- If you have created secondary user stores in the previous Identity Server copy content in the
Download the migration resources and unzip it to a local directory. This folder is referred to as
<IS5.2.0_MIGRATION_TOOL_HOME>/dbscripts/identity/migration-5.1.0_to_5.2.0folder and paste it in the
- Copy the
<IS5.2.0_MIGRATION_TOOL_HOME>/dbscripts/migration-5.1.0_to_5.2.0folder and paste it in the
- Copy the
org.wso2.carbon.is.migrate.client-5.2.0.jarfile in the
<IS5.2.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 -
Run the respective migration script against your database.
Note: The db scripts add the following new claims and claim mappings to your database. If you have already mapped the carLicense and/or businessCategory attributes to a claim, follow the steps below to update the SQL with a different attribute value.
Claim Mapped Attribute http://wso2.org/claims/identity/lastLoginTime carLicense http://wso2.org/claims/identity/lastPasswordUpdateTime businessCategory
Open the relevant db script in an editor.
Change the relevant SQL commands to add a suitable attribute.SQL for lastLoginTime Claim
Change the '
carLicense' attribute value to a different attribute that is not mapped to a claim.SQL for lastPasswordUpdateTime Claim
Change the 'businessCategory' attribute value to a different attribute that is not mapped to a claim.
To avoid a known issue related to OpenID Connect requested claims, update WSO2 IS using the WSO2 Update Manager (WUM). To do this, follow the instructions on the Updating WSO2 Products page and update the WSO2 Identity Server using WUM.
Start the Identity Server 5.2.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 User Management Database
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. This also includes migration of the super tenant.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.
Configuration changes in IS 5.2.0
The table below lists out all the configuration changes from IS 5.1.0 to IS 5.2.0. You can scroll through the table and change the relevant configurations according to the features you are using.