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.2.0 to WSO2 Identity Server 5.3.0. In this topic, <OLD_IS_HOME>
is the directory that Identity Server 5.2.0 resides in and <NEW_IS_HOME>
is the directory that Identity Server 5.3.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.3.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.2.0 - 5.4.0), you can skip this step and migrate to 5.3.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.
- 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.3.0. For more information on how to do this, see Updating WSO2 Products.
If you have added any custom claims, expand the section below and follow the steps before migrating to WSO2 IS 5.3.0.
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.2.0 LDAP user store to IS 5.3.0.
- Copy the
<OLD_IS_HOME>/repository/data
folder to<NEW_IS_HOME>/repository/data
folder. - 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.
It is recommended that you run the cleanup scripts before migration to clean the expired, inactive, and revoked tokens/codes. This reduces the time taken for migration.
- Download Identity Server 5.3.0 and unzip it in the
<NEW_IS_HOME>
directory. - Take a backup of the existing database used by Identity Server 5.2.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
<IS5.3.0_MIGRATION_TOOL_HOME>
.Copy the DB script files in the
<IS5.3.0_MIGRATION_TOOL_HOME>/dbscripts/identity
directory to the<NEW_IS_HOME>/dbscripts/identity/migration-5.2.0_to_5.3.0/
directory.- Copy the
org.wso2.carbon.is.migrate.client-5.3.0.jar
file in the<IS5.3.0_MIGRATION_TOOL_HOME>/dropins
directory to the<NEW_IS_HOME>/repository/components/dropins
directory. - 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 -
DidentityOracleUser
and user management database owner name with -DumOracleUser
.
- Copy any custom OSGI bundles that were added manually from the
<OLD_IS_HOME>/repository/components/dropins
folder and paste it in the<NEW_IS_HOME>/repository/components/dropins
folder. Copy any added JAR files from the
<OLD_IS_HOME>/repository/components/lib
folder and paste it in the<NEW_IS_HOME>/repository/components/lib
folder.Copy the
.jks
files from the<OLD_IS_HOME>/repository/resources/security
folder and paste them in<NEW_IS_HOME>/repository/resources/security
folder.- If you have created tenants in the previous WSO2 Identity Server version and if there are any resources in the
<OLD_IS_HOME>/repository/tenants
directory, copy the content to the<NEW_IS_HOME>/repository/tenants
directory. If you have created secondary user stores in the previous WSO2 IS version, copy the content in the
<OLD_IS_HOME>/repository/deployment/server/userstores
directory to the<NEW_IS_HOME>/repository/deployment/server/userstores
directory.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 environment.
Migrate by applying custom configurations to 5.3.0
This approach is recommended if:
You have done very few configuration changes in your previous version of WSO2 IS. These configuration changes have been tracked and are easy to redo.
Steps:
- If you have made configurations in the config files of your previous version of WSO2 IS, reconfigure the files in the
<NEW_IS_HOME>/repository/conf
folder with your configurations. - Proceed to step 11 to run the migration client.
Migrate by updating the existing configurations with what's new in 5.3.0
This approach is recommended if:
- You have done many custom changes in your previous version of WSO2 IS.
These configuration changes have not been tracked completely and/or are difficult to redo.
Steps:
- Make a copy of the
<OLD_IS_HOME>/repository/conf
folder. (Do not change the original configs. You may use it as a backup in case there are any issues) Copy the following files from the
<NEW_IS_HOME>/repository/conf/identity
folder and paste it into the copy of the<OLD_IS_HOME>/repository/conf/identity
folder:captcha-config.properties
identity-event.properties
Open the
output-event-adapters.xml
file found in the<NEW_IS_HOME>/repository/conf
folder and configure the relevant email configurations.The table below lists out all the configuration changes from IS 5.2.0 to IS 5.3.0. Scroll through the table and change the relevant configurations according to the features you are using. Any step which is not explicitly mentioned as “optional” is mandatory for the migration.
Tip: Scroll left/right to view the entire table below.
Proceed to step 11 to run the migration client.
Note: Note that if you followed this approach for migration, the migration client will map all claims to a local claim in the wso2 claims dialect. This is done by matching the attribute IDs. If there is a claim with no matching attribute ID, the migration client will create a new local claim to create the association.
For example:
If the following two claims were mapped in WSO2 IS 5.2.0, the migration client may not identify this because the attribute IDs are different.
<Dialect dialectURI="http://wso2.org/claims"> <ClaimURI>http://wso2.org/claims/streetaddress</ClaimURI> <DisplayName>Address</DisplayName> <AttributeID>streetAddress</AttributeID> <Dialect dialectURI="http://wso2.org/oidc/claim"> <ClaimURI>street_address</ClaimURI> <DisplayName>Street Address</DisplayName> <AttributeID>street</AttributeID>
As a result, the migration client will create a new local claim like "http://wso2.org/claims/migration__street__73622 " and map the OIDC claim to the new local claim.
Start the Identity Server 5.3.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.
Linux/Unix:
sh wso2server.sh -Dmigrate -Dcomponent=identity
Windows:
wso2server.bat -Dmigrate -Dcomponent=identity
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.
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.
Linux/Unix:
sh wso2server.sh
Windows:
wso2server.bat
If the database script has not run properly, there might be an error when trying to login to the management console. If you are faced with the following error, follow the steps given below to fix it.
ERROR {org.wso2.carbon.core.services.authentication.AuthenticationAdmin} - System error while Authenticating/Authorizing User : Error when handling event : PRE_AUTHENTICATION
- Stop the WSO2 IS server.
Set the following IdentityMgtEventListener with
orderId=95
to enable=false in the<IS_HOME>/repository/conf/identity/identity.xml
file.<EventListener type="org.wso2.carbon.user.core.listener.UserOperationEventListener" name="org.wso2.carbon.identity.governance.listener.IdentityMgtEventListener" orderId="95" enable="false" />
Start the WSO2 IS server and login to the management console.
- Click Add under Claims and click Add Local Claim.
- Enter the following values and click Add.
- Claim URL:
http://wso2.org/claims/identity/accountDisabled
- Display Name: Account Disabled
- Description: Account Disabled
- User Store Domain Name: PRIMARY
- Mapped Attribute: Ref
- Claim URL:
- Stop the WSO2 IS server.
Set the following IdentityMgtEventListener with
orderId=95
to enable=true in the<IS_HOME>/repository/conf/identity/identity.xml
file.<EventListener type="org.wso2.carbon.user.core.listener.UserOperationEventListener" name="org.wso2.carbon.identity.governance.listener.IdentityMgtEventListener" orderId="95" enable="true" />
Start the WSO2 IS server. You should now be able to login to the management console.