This documentation is for WSO2 Identity Server 5.5.0 . View documentation for the latest release.

All docs This doc
Skip to end of metadata
Go to start of metadata

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.4.0 to WSO2 Identity Server 5.5.0. In this topic, <OLD_IS_HOME> is the directory that Identity Server 5.4.0 resides in and <NEW_IS_HOME> is the directory that Identity Server 5.5.0 resides in.

Before you begin

This release is a WUM-only release. This means that there are no manual patches. 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.5.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.4.0 LDAP user store to IS 5.5.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.

  1. Download Identity Server 5.5.0 and unzip it in the <NEW_IS_HOME> directory.
  2. Take a backup of the existing database used by Identity Server 5.4.0. This backup is necessary in case the migration causes issues in the existing database.
  3. Make the following database updates as indicated below.
    1. Download the migration resources and unzip it to a local directory. This folder is referred to as <IS5.5.0_MIGRATION_TOOL_HOME>.

    2. Copy the and the snakeyaml-1.16.0.wso2v1.jar found in the <IS5.5.0_MIGRATION_TOOL_HOME> folder, and paste it in the <NEW_IS_HOME>/repository/components/dropins directory. 

    3. Copy migration-resources folder to the <NEW_IS_HOME> root folder. 

    4. Ensure that the following property values are as follows in the migration-config.yaml file found in the <NEW_IS_HOME>/migration-resources folder. 

      migrationEnable: "true"
      currentVersion: "5.4.0"
      migrateVersion: "5.5.0"
  4. 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. 
  5. 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. 

  6. Copy the .jks files from the <OLD_IS_HOME>/repository/resources/security folder and paste them in <NEW_IS_HOME>/repository/resources/security folder. 

  7. 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.
  8. 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.

  9. You can use one of the following approaches to migrate depending on your production evironment. 

    • Migrate by applying custom configurations to 5.5.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.  


      1. If you have made configuration changes to the config files in your previous version of WSO2 IS, update the files in the <NEW_IS_HOME>/repository/conf folder with your own configurations. 
      2. Proceed to step 10 to run the migration client.
    • Migrate by updating existing configurations with what's new in 5.5.0

      This approach is recommended if:

      • You have done many configuration changes in your previous version of WSO2 IS.
      • These configurations have not been tracked completely and/or are difficult to redo.  


      1. 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)
      2. Copy the following configuration files from the <NEW_IS_HOME> and paste it in the copy of the <OLD_IS_HOME> in the relevant path.
        • <IS_HOME>/repository/conf/

        • <IS_HOME>/repository/conf/consent-mgt-config.xml

      3. The table below lists out all the configuration changes from IS 5.4.0 to IS 5.5.0. You can scroll through the table and change the relevant configurations according to the features you are using.

        Tip: Scroll left/right to view the entire table below.

        Note: The configuration changes listed below will not affect the existing system because these configurations are applied only at first start up and new tenant creation.
        If you wish to change the configurations for the existing tenants, configure it through the management console user interface.

         Configuration changes: Click here to view the table..
        Configuration FileChanges
        carbon.xml file stored in the <IS_HOME>/repository/conf folder.

        Change the version property value to 5.5.0.


        application-authentication.xml file stored in the <IS_HOME>/repository/conf/identity folder.

        Replace the following property found within the <Extensions> list.

        If you are using a custom <StepBasedSequenceHandler>, skip this step.


        with the one given below.


        If you are using a custom authorization handler, see Migrating Custom Authorization Handlers.

        The OpenIDAuthenticator is no longer available. Remove the following configurations that are related to it.

        Remove the following property found within the <AuthenticatorNameMappings> tag.

        <AuthenticatorNameMapping name="OpenIDAuthenticator" alias="openid" /> 

        Remove the whole configuration block that starts with the config given below found within the <AuthenticatorConfigs> tag.

        <AuthenticatorConfig name="OpenIDAuthenticator" enabled="true">

        Replace the AuthenticatorConfig block for the MobileConnectAuthenticator found within the <AuthenticatorConfigs> tag, with the following configuration.

        <AuthenticatorConfig name="MobileConnectAuthenticator" enabled="true">
            <Parameter name="MCAuthenticationEndpointURL">mobileconnectauthenticationendpoint/mobileconnect.jsp</Parameter>
            <Parameter name="MCDiscoveryAPIURL"></Parameter>
            <Parameter name="redirectToMultiOptionPageOnFailure">false</Parameter>

        Remove the following property found within the <AuthenticatorNameMappings> tag. The AuthorizationHandler property has been removed from this file for newer versions of this product.


 file stored in the <IS_HOME>/repository/conf/identity folder.

        Add the following properties that are required for Request Object Support. For more information about the feature, see Request Object Support.

        Add the following properties to enable the user event handler used to delete user consents when users are deleted.
        identity.xml file stored in the <IS_HOME>/repository/conf/identity folder.

        Remove the <ClientAuthHandlers> code block found within the <OAuth> tag. From WSO2 IS 5.5.0 onwards, client authentication is handled differently. For more information, see the introduction of the Writing A New OAuth Client Authenticator topic.

            <ClientAuthHandler Class="org.wso2.carbon.identity.oauth2.token.handlers.clientauth.BasicAuthClientAuthHandler">
                <Property Name="StrictClientCredentialValidation">false</Property>

        Add the following property within the <ScopeValidators> tag. For more information about the XACML based scope validator, see Validating the Scope of OAuth Access Tokens using XACML Policies.

        Tip: To migrate custom scope validators, see Migrating Custom Scope Validators.

        <ScopeValidator class="org.wso2.carbon.identity.oauth2.validators.xacml.XACMLScopeValidator"/>

        Add the following property within the <OpenIDConnect> tag to enable the service provider wise audience configuration. For more information about this, see

        This feature requires a new database table that is created when running the migration script. If you do not wish to use this feature, you can set the value of the property given below to false.


        Add the following property within the <OpenIDConnect> tag.


        Add the following property within the <EventListeners> tag.

        <EventListener type="org.wso2.carbon.user.core.listener.UserOperationEventListener"
                               orderId="98" enable="false"/>

        Add the following code block within the root tag after the <EventListeners> code block. For more information about this configuration, see Tracking user deletion on deleting a user.

            <UserDeleteEventRecorder name="org.wso2.carbon.user.mgt.recorder.DefaultUserDeletionEventRecorder" enable="false">
                <!-- Un comment below line if you need to write entries to a separate .csv file. Otherwise this will be
                    written in to a log file using a separate appender. -->
                <!--<Property name="path">${carbon.home}/repository/logs/delete-records.csv</Property>-->

        Do the following configuration changes to enable fine grained access control introduced with Identity Server 5.5.0

        Remove the following property found within the <ResourceAccessControl> tag.

        <Resource context="(.*)/api/identity/user/(.*)" secured="true" http-method="all"/>

        Add the following set of resources within the < ResourceAccessControl> tag.

        <Resource context="(.*)/api/identity/user/v1.0/validate-code" secured="true" http-method="all"/>
        <Resource context="(.*)/api/identity/user/v1.0/resend-code" secured="true" http-method="all"/>
        <Resource context="(.*)/api/identity/user/v1.0/me" secured="true" http-method="POST"/>
        <Resource context="(.*)/api/identity/user/v1.0/me" secured="true" http-method="GET"/>
        <Resource context="(.*)/api/identity/user/v1.0/pi-info" secured="true" http-method="all">
        <Resource context="(.*)/api/identity/user/v1.0/pi-info/(.*)" secured="true" http-method="all">
        <Resource context="(.*)/api/identity/consent-mgt/v1.0/consents" secured="true" http-method="all"/>
        <Resource context="(.*)/api/identity/consent-mgt/v1.0/consents/receipts/(.*)" secured="true" http-method="all"/>
        <Resource context="(.*)/api/identity/consent-mgt/v1.0/consents/purposes" secured="true" http-method="POST">
        <Resource context="(.*)/api/identity/consent-mgt/v1.0/consents/purposes(.*)" secured="true" http-method="GET"/>
        <Resource context="(.*)/api/identity/consent-mgt/v1.0/consents/purposes(.+)" secured="true" http-method="DELETE">
        <Resource context="(.*)/api/identity/consent-mgt/v1.0/consents/pii-categories" secured="true" http-method="POST">
        <Resource context="(.*)/api/identity/consent-mgt/v1.0/consents/pii-categories(.*)" secured="true" http-method="GET"/>
        <Resource context="(.*)/api/identity/consent-mgt/v1.0/consents/pii-categories(.+)" secured="true" http-method="DELETE">
        <Resource context="(.*)/api/identity/consent-mgt/v1.0/consents/purpose-categories" secured="true" http-method="POST">
        <Resource context="(.*)/api/identity/consent-mgt/v1.0/consents/purpose-categories(.*)" secured="true" http-method="GET"/>
        <Resource context="(.*)/api/identity/consent-mgt/v1.0/consents/purpose-categories(.+)" secured="true" http-method="DELETE">

        Replace the following property found within the <WebApp> tag under the <TenantContextsToRewrite> tag.


        with the one given below


        Add the following new property within the <WebApp> tag found under the <TenantContextsToRewrite> tag.


        Add the following code block within the root tag after the <SSOService> code block.

        This configuration specifies whether consent management should be enabled during single sign-on authentication. For more information, see Consent Management with Single-Sign-On.

            <!--Specify whether consent management should be enable during SSO.-->

        Add the following code block within the  <OAuth>  tag. This configuration is used  to specify the grant types that filter claims based on user consents. The grant types given below are out-of-the-box grant types that prompt the user for consent.

        <!--Defines the grant types that will filter user claims based on user consent in their responses such as id_token or user info response.Default grant types that filter user claims based on user consent are 'authorization_code' and 'implicit'.
        Supported versions: IS 5.5.0 onwards. -->
 file stored in the <IS_HOME>/repository/conf folder.

        Add the following properties.

        log4j.appender.DELETE_EVENT_LOGFILE.layout.ConversionPattern=%m %n
        provisioning-config.xml file stored in the <IS_HOME>/repository/conf/identity folder.

        Remove the <scim-providers> and <scim-consumers> code blocks from the file.

      4. Replace the <NEW_IS_HOME>/repository/conf folder with the modified copy of the <OLD_IS_HOME>/repository/conf folder.

      5. Proceed to step 10 to run the migration client.

  10. Start the Identity Server 5.5.0 with the following command to perform the data migration for all components. 

    1. Linux/Unix:

      sh -Dmigrate -Dcomponent=identity
    2. Windows:

      wso2server.bat -Dmigrate -Dcomponent=identity
  11. Once the migration is successful, stop the server and start using the appropriate command.
    1. Linux/Unix:

    2. Windows:

  • No labels