This documentation is for WSO2 Identity Server 5.1.0. View documentation for the latest release.
Page Comparison - Upgrading from the Previous Release (v.69 vs v.70) - Identity Server 5.1.0 - WSO2 Documentation

Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

...

  1. Download Identity Server 5.1.0 and unzip it in the <NEW_IS_HOME> directory.
  2. Take a backup of the existing database used by Identity Server 5.0.0. This backup is necessary in case the migration causes issues in the existing database.
  3. 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.
  4. Configure the <NEW_IS_HOME>/repository/conf/datasources/master-­datasources.xml file in Identity Server 5.1.0 by pointing to the same databases used by Identity Server 5.0.0.
  5. Configure the <NEW_IS_HOME>/repository/conf/identity/identity.xml file with the same configurations made in the <OLD_IS_HOME>/repository/conf/identity.xml file.
  6. Configure the <NEW_IS_HOME>/repository/conf/identity/identity-­mgt.properties file with the same configurations made in the <OLD_IS_HOME>/repository/conf/security/identity-mgt.properties file. 

    Note

    Note: The Identity.Listener.Enable property is no longer available in this file in Identity Server 5.1.0. You can enable Identity.Mgt.Listener in the <NEW_IS_HOME>/repository/conf/identity/identity.xml file as indicated below.

    Code Block
    languagexml
    <EventListener type="org.wso2.carbon.user.core.listener.UserOperationEventListener" name="org.wso2.carbon.identity.mgt.IdentityMgtEventListener" orderId="50" enable="true"/>
  7. Configure the <NEW_IS_HOME>/repository/conf/identity/provisioning-config.xml file with the same configurations made in the <OLD_IS_HOME>/repository/conf/provisioning-config.xml.

  8. Configure the primary user store in <NEW_IS_HOME>/repository/conf/user-mgt.xml according to <OLD_IS_HOME>/repository/conf/user-mgt.xml file.

    Note

    Note: The MultiAttributeSeparator property found in the user-mgt.xml file is used to define a character to separate multiple attributes. If a claim value has a comma there may be issues that arise. To overcome this, configure the MultiAttributeSeparator property in the relevant UserStoreManager to something other than ",". For example, you can use ",,," or "..." or a similar character sequence. This ensures that it will not appear as part of a claim value. The default is ",".

  9. If you have created tenants in the previous Identity Server copy content in the <OLD_IS_HOME>/repository/tenants directory to <NEW_IS_HOME>/repository/tenants/ directory.
  10. Copy the .jks files found in the <OLD_IS_HOME>/repository/resources/security folder and paste them in <NEW_IS_HOME>/repository/resources/security.
  11. If you have created secondary user stores in the previous Identity Server copy content in the <OLD_IS_HOME>/repository/deployment/server/userstores directory to <NEW_IS_HOME>/repository/deployment/server/userstores/ directory.
  12. Copy the content in the <OLD_IS_HOME>/repository/resources/security/samlsso_federate.html file to <NEW_IS_HOME>/repository/resources/identity/pages/samlsso_federate.html file.
  13. If you have edited <OLD_IS_HOME>/repository/resources/security/sso_redirect.html file, copy the content in the <OLD_IS_HOME>/repository/resources/security/sso_redirect.html file to the <NEW_IS_HOME>/repository/resources/identity/pages/samlsso_response.html file. Then replace

    Code Block
    languagexml
    <input type='hidden' name='SAMLResponse' value='$response'>
    <input type='hidden' name='RelayState' value='$relayState'>

    with

    Code Block
    languagexml
    <!--$params-->
  14. Make the database script updates as indicated below.
    1. Download the migration resources and unzip it to a local directory. This folder is referred to as <IS5.1.0_MIGRATION_TOOL_HOME>.

      Note

      Note: If you are using MySQL 5.7, rename the following files found in the <IS5.1.0_MIGRATION_TOOL_HOME>/dbscripts/identity/migration­5.0.0SP1_to_5.1.0 directory, before proceeding.

      • mysql.sql to mysql_56.sql
      • mysql_57.sql to mysql.sql
    2. Copy the <IS5.1.0_MIGRATION_TOOL_HOME>/dbscripts/migration­5.0.0_to_5.1.0 directory to the <IS5.1.0_HOME>/dbscripts/ directory.

    3. Copy the <IS5.1.0_MIGRATION_TOOL_HOME>/dbscripts/identity/migration­5.0.0SP1_to_5.1.0 directory and <IS5.1.0_MIGRATION_TOOL_HOME>/dbscripts/identity/migration­5.0.0_to_5.0.0SP1 directory to the <IS5.1.0_HOME>/dbscripts/identity/ directory.

    4. Copy the <IS5.1.0_MIGRATION_TOOL_HOME>/dropins/org.wso2.carbon.is.migrate.client­5.1.0.jar file to the <IS5.1.0_HOME>/repository/components/dropins/ directory.

    5. Alternatively, if you are using Oracle, 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.
    6. To migrate the identity database only (without migrating the user management database): 

      • Add the -DmigrateIdentity JVM parameter to the startup command as well.

      • Open the <NEW_IS_HOME>/repository/conf/user-mgt.xml file and set the value of the <isCascadeDeleteEnabled> property to false.

        Code Block
        languagexml
        <Property name="isCascadeDeleteEnabled">false</Property>
  15. Before you start the migration run the following queries on the database pointed in the identity.xml to identify if there is any corrupted data.

    Code Block
    languagexml
    SELECT * FROM IDN_OAUTH2_ACCESS_TOKEN WHERE AUTHZ_USER LIKE '% @%' AND TOKEN_STATE='ACTIVE';
    SELECT * FROM IDN_OAUTH2_ACCESS_TOKEN WHERE AUTHZ_USER NOT LIKE '%@%' AND TOKEN_STATE='ACTIVE';

    If any of the above queries gives a result, you have clean the database. To do this, start the server with command given below. 

    1. Linux/Unix:

      Code Block
      languagexml
      sh wso2server.sh -Dmigrate -Dcomponent=identity -DcleanIdentityData
    2. Windows:

      Code Block
      languagexml
      wso2server.bat -Dmigrate -Dcomponent=identity -DcleanIdentityData
      Info

      You may notice the following exception being thrown in the console when Identity Server 5.1.0 is started at this point:

      org.wso2.carbon.idp.mgt.IdentityProviderManagementException: Error occurred while retrieving Identity Provider information for tenant : carbon.super and Identity Provider name : LOCAL

      This is due to the fact that the IDP_METADATA table does not exist in the database. This is not a cause for alarm and is to be expected since we are yet to complete the migration process.

  16. Start the Identity Server 5.1.0 using the appropriate command. 

    Info

    The following command does a complete migration and is the recommended approach. However, if you want to perform migration for individual components, migration in batch mode, or uninterrupted migration, see the note below.

    1. Linux/Unix:

      Code Block
      languagexml
      sh wso2server.sh -Dmigrate -Dcomponent=identity
    2. Windows:

      Code Block
      languagexml
      wso2server.bat -Dmigrate -Dcomponent=identity
    Note
    titleNote: Migrate individual components

    Optional: To migrate certain components only, use the relevant commands in the table below.

    Warning

    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.

    Expand
    titleClick here to view the commands
    Background Color
    colorwhite
    Component/PurposeLinux/UnixWindows
    Identity Database with User Management Database Data

    To migrate the identity database component along with the user management database data, run the following command:

    Code Block
    sh wso2server.sh -Dmigrate -Dcomponent=identity -DmigrateIdentity
    Note

    Note: This command does not migrate the user management database. It migrates the user management database data along with the identity database and the identity database data.

    To migrate the identity database component along with the user management database data, run the following command:

    Code Block
    .\wso2server.bat -Dmigrate -Dcomponent=identity -DmigrateIdentity
    Note

    Note: This command does not migrate the user management database. It migrates the user management database data along with the identity database and the identity database data.

    Identity Database



    To migrate only the identity database component, run the following commands in this order:

    1. Runs the migration script for the identity database:

      Code Block
      languagebash
      sh wso2server.sh -Dmigrate -Dcomponent
      =identity -DmigrateIdentityDB
    2. Migrates the identity database data:

      Code Block
      languagebash
      sh wso2server.sh -Dmigrate -Dcomponent
      =identity -DmigrateIdentityData
    3. Completes the identity database migration:

      Code Block
      languagebash
      sh wso2server.sh -Dmigrate -Dcomponent
      =identity -DmigrateIdentityDBFinalize

    To migrate only the identity database component, run the following commands in this order:

    1. Runs the migration script for the identity database:

      Code Block
      languagebash
      .\wso2server.bat -Dmigrate -Dcomponent
      =identity -DmigrateIdentityDB
    2. Migrates the identity database data:

      Code Block
      languagebash
      .\wso2server.bat -Dmigrate -Dcomponent
      =identity -DmigrateIdentityData
    3. Completes the identity database migration:

      Code Block
      languagebash
      .\wso2server.bat -Dmigrate -Dcomponent
      =identity -DmigrateIdentityDBFinalize

    User Management Database


    The following command runs the migration script for the user management database:

    Code Block
    languagebash
    sh wso2server.sh -Dmigrate -Dcomponent=identity -DmigrateUMDB

    The following command runs the migration script for the user management database:

    Code Block
    languagebash
    .\wso2server.bat -Dmigrate -Dcomponent=identity -DmigrateUMDB

    User Management Database Data

    The following command migrates the user management database data:

    Code Block
    languagebash
    sh wso2server.sh -Dmigrate -Dcomponent=identity -DmigrateUMData



    The following command migrates the user management database data:

    Code Block
    languagebash
    .\wso2server.bat -Dmigrate -Dcomponent=identity -DmigrateUMData
    Registry Data

    The following command migrates the registry data (including SAML configurations):

    Code Block
    languagebash
    sh wso2server.sh -Dmigrate -Dcomponent=identity -DmigrateRegistry



    The following command migrates the registry data (including SAML configurations):

    Code Block
    languagebash
    .\wso2server.bat -Dmigrate -Dcomponent=identity -DmigrateRegistry



    All Components (continue on error)

    The following command allows you to run the full component migration to the end while logging any exceptions occurred. This is for uninterrupted migration and is particularly useful to complete migration in a partially migrated database.

    Code Block
    languagebash
    sh wso2server.sh -Dmigrate -Dcomponent
    =identity -DcontinueOnError

    The following command allows you to run the full component migration to the end while logging any exceptions occurred. This is for uninterrupted migration and is particularly useful to complete migration in a partially migrated database.

    Code Block
    languagebash
    .\wso2server.bat -Dmigrate -Dcomponent
    =identity -DcontinueOnError
    Prevent migrating in batch mode

    By default, the queries are executed in batch mode. To prevent executing in batches, use the following command.

    Code Block
    languagebash
    sh wso2server.sh -Dmigrate -Dcomponent
    =identity -DnoBatchUpdate

    By default, the queries are executed in batch mode. To prevent executing in batches, use the following command.

    Code Block
    languagebash
    sh wso2server.sh -Dmigrate -Dcomponent
    =identity -DnoBatchUpdate
  17. After you have successfully migrated, run the following command on the MySQL console to drop the following index (if it exists).

    Code Block
    languagesql
    drop index SESSION_ID on IDN_AUTH_SESSION_STORE

...