This documentation is for WSO2 Identity Server 5.2.0 . View documentation for the latest release.
Skip to end of metadata
Go to start of metadata

You are viewing an old version of this page. View the current version.

Compare with Current View Page History

« Previous Version 2 Next »

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/datasources/master-­datasources.xml file in Identity Server 5.1.0 by pointing to the same databases used by Identity Server 5.0.0.
  4. 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.
  5. Configure the <NEW_IS_HOME>/repository/conf/identity/identity-­ file with the same configurations made in the <OLD_IS_HOME>/repository/conf/security/ 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"/>
  6. 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 ",".

  7. 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.
  8. 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.
  9. Copy the content in the <OLD_IS_HOME>/repository/resources/security/samlsso_federate.html file to <NEW_IS_HOME>/repository/resources/identity/samlsso_federate.html file.
  10. 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'>


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

    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/­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>
  12. Start the Identity Server 5.1.0 using the appropriate command.
    1. Linux/Unix:

      sh -Dmigrate -Dcomponent=identity
    2. Windows:

      wso2server.bat -Dmigrate -Dcomponent=identity

Configuration changes in Carbon 4.4.x

WSO2 Identity Server 5.1.0 runs on Carbon Kernel 4.4.x. The configuration options listed below are new in Carbon 4.4.x.  Follow the given links for more details about configurations.

Configuration File 
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.
  • 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.
  • 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:
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;


    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 →
    <!-- Broker TCP Port →
    <!-- SSL Port →
  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.

                <!-- Keystore file location-->
                <!-- Keystore type (JKS/PKCS12 etc.)-->
                <!-- Keystore password-->
                <!-- Private Key alias-->
                <!-- Private Key password-->

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