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 4 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.1.0 LDAP user store to IS 5.2.0.

  1. Copy the <IS-5.1-Home>/repository/data folder to <IS-5.2-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.1.0 resides in and <NEW_IS_HOME> is the directory that Identity Server 5.2.0 resides in.

  1. Download Identity Server 5.2.0 and unzip it in the <NEW_IS_HOME> directory.
  2. Take a backup of the existing database used by Identity Server 5.1.0. This backup is necessary in case the migration causes issues in the existing database.
  3. Replace the <NEW_IS_HOME>/repository/conf folder with the <OLD_IS_HOME>/repository/conf folder.

  4. Open the <NEW_IS_HOME>/repository/conf/identity/identity.xml file and add the <PoolSize> tag under the <SessionDataPersist> tag with the default value as 200, if you have not already done so. 

  5. 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.
  6. 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
  7. You can do database migration by using the db scripts and running the respective migration script on your database. 

    Database migration is only required if you are planning to use any of the following use cases:

    • To use the PKCE feature
    • To use the workflow feature with DB2 database
    • To use manager/worker service URLs which are more than 45 characters long for BPS profiles used in workflows.
  8. Start the Identity Server 5.2.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