1 Mar, 2022 | 3 min read

How to Migrate from the Open Source WSO2 Identity Server to the Subscription Version?

  • Dinali Dabarera
  • Senior Solutions Engineer - WSO2


WSO2 Identity Server is the most popular open-source CIAM system on the market, and it is widely used by educational institutions and government agencies as an on-premise CIAM solution. Single sign-on/sign-out (SSO), identity federation, strong authentication, identity administration, account management, identity provisioning, fine-grained access control, API security, monitoring, reporting, and auditing are all possible with WSO2 Identity Server's seamless integration capabilities. As a result, WSO2 Identity Server is becoming more well-known in the open-source community as an extensible product that can meet any business need. Nonetheless, protecting your critical systems is always more important than letting your valuable consumer data and information fall into the wrong hands. 

Therefore, you always need WSO2 assurance through subscription.

The difference between the open-source and subscribed versions of WSO2 Identity Server

While the open-source and subscribed versions are similar in terms of major features, there are also significant differences.

  • Subscribed versions include all bug fixes and security fixes reported by subscribers, whereas the open-source version will receive these fixes in the next release.
  • The subscribed version receives real-time WSO2 updates (fixes) to the installation itself, whereas the open-sources version does not.
  • Subscribed versions receive 24x7x365 WSO2 support (unlimited production/incident support and limited query support proportionate to subscription paid) via the WSO2 support channel, whereas open-source versions only receive community support via slack, GitHub, and Stackoverflow.

Another significant benefit of having a WSO2 subscription is that you will receive technical advice and guidance from a technical owner who will assist you with solution design when your team requires it.

Furthermore, the subscription entitles you to WSO2 paid services for architectural reviews, quick start programs, workshops, product training, and deployment implementations.

Why should you switch from open-source to subscription-based WSO2 Identity Server?

You need to move away from open-source and get the subscription quickly, 

  • If your CIAM system is critical and handles business data such as financial data, consumer data, or healthcare data, we recommend getting a WSO2 subscription because of regular bug fixes and security fixes - the most recent example being Apache Log4j Security Vulnerabilities, which resulted in the compromise of large amounts of data. 
  • If your team lacks WSO2 experts who can troubleshoot when an issue arises.
  • If you require WSO2 support to maintain your system and ensure 99.9% uptime.
  • If you want WSO2 to assist you in deploying WSO2 Identity Server in a cloud environment while adhering to all security and best practices.
  • If there is a requirement for insurance on strict SLA level support when an issue occurs in your product setup, depending on the system's criticality.

Prerequisites before migration

  • Validate your deployment size with a WSO2 Solutions Architect and receive a subscription to the WSO2 products you use.
  • Download the binaries or Docker images using the credentials you received after subscribing.
  • Identify all of the customizations and changes you've made to the WSO2 community version.
  • When you migrate the product to the subscription version, make sure you have a way to test the existing behavior.
  • Get the same open source WSO2 Identity Server version as the subscribed WSO2 Identity Server.
  • If you intend to do a DB migration to a separate database identical to the community version you use, obtain a DB dump or backup and use it to duplicate the databases for the migrated product version.

Please keep in mind that there will be no database schema changes in the subscription or enterprise versions when compared to the community versions. However, if there are any, they are mentioned in the WSO2 Update summary.

Step-by-step instructions for migrating to version 5.9 and above

Naming convention 

 Open Source WSO2 Identity Server -> OS_WSO2IS

 Subscription based (U2 ready WUM) WSO2 Identity Server -> SUB_WSO2IS

Note:All versions of jars and libraries are the same if you take two Identity Server products of the same version from open source and subscription.

Follow the below steps to migrate your Open Source WSO2 Identity Server product to WSO2 WUM U2 Updated WSO2 Identity Server of the same version

  1. Copy the configurations from deployment.toml file in OS_WSO2IS and add them in the deployment.toml file in SUB_WSO2IS

Note: If you are having WSO2 Identity Server older than 5.9.0 - you need to migrate all the configurations in the OS_WSO2IS/repository/conf folder to the SUB_WSO2IS/repository/conf folder files.

  1. If any configuration changes such as JVM parameters, have been done in the <OS_WSO2IS>/bin directory, then merge the changes in the relevant files in <SUB_WSO2IS>/bin 
  2. If any external custom jar are added to OS_WSO2IS/repository/components/libs and OS_WSO2IS/repository/components/dropins folders, migrate them to matching SUB_WSO2IS, /repository/components/libs and SUB_WSO2IS, /repository/components/dropins folders.
  1. If there are any patches in the OS_WSO2IS/repository/components/patches folder, Get an official WUM update for that from the WSO2 team. We do not recommend applying patches in production environments.

Note: When WUM updates are applied, all the fixes will be overridden by the jar files in the patches folder. If you customize the product through patches the WSO2 SLAs would not apply . Hence, contact the WSO2 Team when you have such requirements.

  1. Copy the changes done to webapps in OS_WSO2IS/repository/deployment/server/webapps such as authenticationendpoint and accountrecoveryendpoint, to SUB_WSO2IS/repository/deployment/server/webapps files through a tool or manually.

Note:Do not directly copy paste OS_WSO2IS/repository/deployment/server/webapps files to SUB_WSO2IS/repository/deployment/server/webapps, because SUB_WSO2IS/repository/deployment/server/webapps contains bug fixes, security fixes and improvements.

  1. If you have any secondary userstores in OS_WSO2IS/repository/deployment/server/userstores/, copy them and paste them to SUB_WSO2IS/repository/deployment/server/userstores/ folder
  2. If you have any tenants, copy all the folders in OS_WSO2IS/repository/tenants/ folder and paste them inside SUB_WSO2IS/repository/tenants/ folder.
  3. If there are any workflow related artifacts copy them to SUB_WSO2IS/repository/humantasks or SUB_WSO2IS/repository/bpel
  4. Copy the keystores and certificates used in OS_WSO2IS/repository/resources/security/ folder to SUB_WSO2IS/repository/resources/security folder
  5. Other than above, if you have any other code level customizations please contact WSO2 for further assistance.
  6. After finishing all steps above, you can start the new SUB_WSO2IS which is migrated. 
  7. Test all your scenarios, before you try this in production. 


With a WSO2 subscription, you can now get our WSO2 Support for all of your migration journeys. If you have any questions, please contact WSO2 via our support portal through Jira or directly contact your account Manager.

Migrating from open source to subscribed WSO2 Identity Server is a simple process, and it is yet another wise strategic decision and investment for your future digital transformation journey.