This documentation is for WSO2 Identity Server 5.1.0. View documentation for the latest release.
Upgrading from the Previous Release - Identity Server 5.1.0 - WSO2 Documentation
||
Skip to end of metadata
Go to start of metadata

The following sections provide instructions on how you can upgrade (the data and configurations) from WSO2 Identity Server 5.0.0 to WSO2 Identity Server 5.1.0.

Upgrading the database

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.0.0 LDAP user store to IS 5.1.0.

  1. Copy the <IS-5.0-Home>/repository/data folder to <IS-5.1-Home/repository/data folder.
  2. 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. 

In this topic, <OLD_IS_HOME> is the directory that Identity Server 5.0.0 resides in and <NEW_IS_HOME> is the directory that Identity Server 5.1.0 resides in.

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

    <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: 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

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

    with

    <!--$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: 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.

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

    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:

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

      wso2server.bat -Dmigrate -Dcomponent=identity -DcleanIdentityData

      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. 

    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:

      sh wso2server.sh -Dmigrate -Dcomponent=identity
    2. Windows:

      wso2server.bat -Dmigrate -Dcomponent=identity

    Note: 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.

     Click here to view the commands
    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:

    sh wso2server.sh -Dmigrate -Dcomponent=identity -DmigrateIdentity

    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:

    .\wso2server.bat -Dmigrate -Dcomponent=identity -DmigrateIdentity

    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:

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

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

      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:

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

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

      .\wso2server.bat -Dmigrate -Dcomponent
      =identity -DmigrateIdentityDBFinalize

    User Management Database


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

    sh wso2server.sh -Dmigrate -Dcomponent=identity -DmigrateUMDB

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

    .\wso2server.bat -Dmigrate -Dcomponent=identity -DmigrateUMDB

    User Management Database Data

    The following command migrates the user management database data:

    sh wso2server.sh -Dmigrate -Dcomponent=identity -DmigrateUMData



    The following command migrates the user management database data:

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

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

    sh wso2server.sh -Dmigrate -Dcomponent=identity -DmigrateRegistry



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

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

    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.

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

    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.

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

    drop index SESSION_ID on IDN_AUTH_SESSION_STORE

API changes

The following section describes changes made to admin services in IS 5.1.0 which may affect your migration depending on your client's usage of the admin service.

  1. Removed authorization and changed input parameters of the changePasswordByUser operation exposed through the userAdmin service

    Changes to the changePasswordByUser operation

    Make the following change to the client side:

    1. Remove the username and password as authentication headers in the request and send the username, old password and new password inside the SOAP body instead. A sample of the request is shown below.

    <soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsd="http://org.apache.axis2/xsd">
       <soapenv:Header/>
       <soapenv:Body>
          <xsd:changePasswordByUser>
             <!--Optional:-->
             <xsd:userName>admin</xsd:userName>
             <!--Optional:-->
             <xsd:oldPassword>adminpassword</xsd:oldPassword>
             <!--Optional:-->
             <xsd:newPassword>adminnewpassword</xsd:newPassword>
          </xsd:changePasswordByUser>
       </soapenv:Body>
    </soapenv:Envelope>

    How it used to be

    This operation was previously an admin service where the user had to be authenticated before running the operation (i.e, only a user with login permissions could perform a password change). In that case, the user had to use an authentication mechanism (his/her username and current password) to execute the operation and the input parameters were as follows:

    1. old password

    2. new password

    How it is now

    Authentication is no longer required for this operation, which means all users (including those without login permissions) can perform this operation. Therefore, the input parameters are now as follows:

    1. username (username of the user whose password needs to be changed)

    2. old password

    3. new password


Configuration changes in IS 5.1.0

The configuration options listed below are new in WSO2 IS 5.1.0  Follow the given links for more details about configurations.


Tip: Scroll left/right to view the rest of the table.

 Configuration changes: Click here to view the table..
Configuration FileConfiguration Change
axis2.xml file stored in the <PRODUCT_HOME>/repository/conf/axis2/ directory.The following new parameter was added: <parameter name="httpContentNegotiation">true</parameter>. When this is set to 'true' , the server will determine the contentType of responses to requests, by using the 'Accept header' of the request.
identity.xml file stored in the <PRODUCT_HOME>/repository/conf/identity directory.
  1. The <TimeConfig> element was added. This element contains a global session timeout configuration. To configure session timeouts and remember me periods tenant wise, see Configuring Session Timeout.
  2. The <SessionTimeout> parameter under the <OpenID> element and the <SSOService> element was removed. This configuration is no longer a constant across all service providers. With Identity Server 5.1.0, you can define the session timeout and remember me period tenant wise using the management console. For more information on how to do this, see Configuring Session Timeout.
tenant-axis2.xml stored in the <PRODUCT_HOME>/repository/conf/tomcat/ directory.The default value for the "httpContentNegotiation" parameter is set to 'true': <parameter name="httpContentNegotiation">true</parameter>.
catalina-server.xml file stored in the <PRODUCT_HOME>/repository/conf/tomcat/ directory.
  1. Keystore parameters was added under the <Connector> element as shown below. This setting allows you to use separate keystore and security certificates to certify SSL connections. Note that the location and password of the default "wso2carbon.jks" keystore is given for these parameters by default.

    keystoreFile=location of the keystore file
    keystorePass=password for the keystore 
  2. The ciphers parameter under the <Connector> element was removed. Depending on the java version you are using, you can define ciphers using the Configuring Transport Level Security page as a guide.
  3. The clientAuth parameter setting under the <Connector> element was changed from clientAuth="false" to clientAuth="want". Setting this parameter to false makes the two-way SSL authentication optional and uses it in instances when it is possible i.e., if you need to disable the certification authentication in certain occasions (e.g., mobile applications). This is recommended since setting it to 'false' will simply disable certificate authentication completely and not use it even when it is possible.
  4. The <Host> element was removed. It was added to fix XSS and CSRF vulnarabilities in WSO2-CARBON-PATCH-4.2.0-1256. For information on how to fix these vulnerabilities in IS 5.1.0, see the following pages:
    1. Mitigating Cross Site Request Forgery (CSRF) Attacks 
    2. Mitigating Carriage Return Line Feed (CRLF)
    3. Mitigating Cross Site Scripting (XSS) Attacks
master-datasources.xml file stored in the <PRODUCT_HOME>/repository/conf/datasources/ directory.Default auto-commit setting for a data source is set to false: <defaultAutoCommit>false</defaultAutoCommit>.
carbon.xml file stored in the <PRODUCT_HOME>/repository/conf/ directory. 
  1. New parameters to define proxy context path as shown below;

    <MgtProxyContextPath></MgtProxyContextPath>
    <ProxyContextPath></ProxyContextPath>

    Proxy context path is a useful parameter to add a proxy path when a Carbon server is fronted by reverse proxy. In addition to the proxy host and proxy port this parameter allows you add a path component to external URLs. See Adding a Custom Proxy Path for details.

  2. The following port configurations was removed:

    <!-- Embedded Qpid broker ports →
    <EmbeddedQpid>
    <!-- Broker TCP Port →
    <BrokerPort>5672</BrokerPort>
    <!-- SSL Port →
    <BrokerSSLPort>8672</BrokerSSLPort>
    </EmbeddedQpid>
  3. In Carbon 4.2.0, the following registry keystore configuration was required for configuring the keystore keys that certify encrypting/decrypting meta data to the registry. From Carbon 4.3.0 onwards the primary keystore configuration shown below will be used for this purpose as well. Therefore, it is not necessary to use a separate registry keystore configuration for encrypting/decrypting meta data to the registry. Read more about keystore configurations in Carbon 4.3.0.

    <RegistryKeyStore>
                <!-- Keystore file location-->
                <Location>${carbon.home}/repository/resources/security/wso2carbon.jks</Location>
                <!-- Keystore type (JKS/PKCS12 etc.)-->
                <Type>JKS</Type>
                <!-- Keystore password-->
                <Password>wso2carbon</Password>
                <!-- Private Key alias-->
                <KeyAlias>wso2carbon</KeyAlias>
                <!-- Private Key password-->
                <KeyPassword>wso2carbon</KeyPassword>
    </RegistryKeyStore>

user-mgt.xml file stored in the<PRODUCT_HOME>/repository/conf/ directory.

The following property was added under the <Configuration> tag. If you are connecting the database from a previous version of IS, set this property to false. 

<Property name="isCascadeDeleteEnabled">true</Property>

The following properties under the <UserStoreManager> tag were changed as follows:

  • The <BackLinksEnabled> property was added. If this property is set to 'true', it enables an object that has a reference to another object to inherit the attributes of the referenced object.
  • The following property was added. It provides flexibility to customize the error message.

    <Property name="UsernameJavaRegExViolationErrorMsg">Username pattern policy violated</Property>
                <Property name="PasswordJavaRegEx">^[\S]{5,30}$</Property>

     

  • The <IsBulkImportSupported> property was added. It specifies whether to enable or disable bulk user import.

  • The following properties were added. They provide flexibility to customize the connection pooling parameters.

    <Property name="ConnectionPoolingEnabled">false</Property>
                <Property name="LDAPConnectionTimeout">5000</Property>
                <Property name="ReadTimeout"/>
                <Property name="RetryAttempts"/>
registry.xml file stored in the <PRODUCT_HOME>/repository/conf/ directory.The default value was changed to 'false' for the following setting: <versionResourcesOnChange>false</versionResourcesOnChange>.
authenticators.xml file stored in the <PRODUCT_HOME>/repository/conf/security directory.

The following parameter was added under the <Authenticator> element to specify the AssertionConsumerServiceURL. This is an optional parameter and is used by the requesting party to build the request. For more information, see Authenticators Configuration.

<Parameter name="AssertionConsumerServiceURL">https://localhost:9443/acs</Parameter>

  • No labels