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.
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.
- 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
.
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 in the copy of the<OLD_IS_HOME>/repository/conf/identity
folder:captcha-config.properties
identity-event.properties
- 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. Open the
output-event-adapters.xml
file found in the<NEW_IS_HOME>/repository/conf
folder and configure the relevant email configurations.<adapterConfig type="email"> <!-- Comment mail.smtp.user and mail.smtp.password properties to support connecting SMTP servers which use trust based authentication rather username/password authentication --> <property key="mail.smtp.from">abcd@gmail.com</property> <property key="mail.smtp.user">abcd</property> <property key="mail.smtp.password">xxxx</property> <property key="mail.smtp.host">smtp.gmail.com</property> <property key="mail.smtp.port">587</property> <property key="mail.smtp.starttls.enable">true</property> <property key="mail.smtp.auth">true</property> <!-- Thread Pool Related Properties --> <property key="minThread">8</property> <property key="maxThread">100</property> <property key="keepAliveTimeInMillis">20000</property> <property key="jobQueueSize">10000</property> </adapterConfig>
Tip: This email configuration is similiar to the email configuration shown in the code block below, which is found in the
<IS_HOME>/repository/conf/axis2/axis2.xml
file. This configuration is used for email-enabled features. You can configure the same values in theoutput-event-adapters.xml
file for email-enabled features using REST APIs in IS 5.3.0.Email configuration in axis2.xml file<transportSender name="mailto"class="org.apache.axis2.transport.mail.MailTransportSender"> <parameter name="mail.smtp.from">sampleemail@gmail.com</parameter> <parameter name="mail.smtp.user">sampleemail</parameter> <parameter name="mail.smtp.password">password</parameter> <parameter name="mail.smtp.host">smtp.gmail.com</parameter> <parameter name="mail.smtp.port">587</parameter> <parameter name="mail.smtp.starttls.enable">true</parameter> <parameter name="mail.smtp.auth">true</parameter> </transportSender>
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.If you have done custom changes to the config files in your previous version of WSO2 IS, see the table below.
The table below lists out all the configuration changes from IS 5.2.0 to IS 5.3.0. You can 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.
Mandatory configuration changes: Click here to view the table..
Replace the
<NEW_IS_HOME>/repository/conf
folder with the modified copy of the<OLD_IS_HOME>/repository/conf
folder.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.
- Once the migration is successful, stop the server and start using the appropriate command.
Linux/Unix:
sh wso2server.sh
Windows:
wso2server.bat