This documentation is for WSO2 Identity Server 5.2.0. View documentation for the latest release.
Upgrading From an Older Version of WSO2 IS - Identity Server 5.2.0 - WSO2 Documentation
||
Skip to end of metadata
Go to start of metadata

Note that these instructions have been tested for migration from WSO2 IS 5.0.0 to 5.4.0 only with the ORACLE database.

The following sections provide instructions that enable you to upgrade from older versions of WSO2 Identity Server (from version 5.0.0 onwards) to the latest version of WSO2 Identity Server. In this topic, <OLD_IS_HOME> is the directory that the older version of WSO2 Identity Server resides in, and <NEW_IS_HOME> is the directory that the latest version of WSO2 Identity Server 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 WSO2 Update Manager (WUM).

  • If you are upgrading to use this version in your production environment, use the WSO2 Update Manager to get the latest updates available for WSO2 IS. 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 WSO2 IS LDAP user store to the new version of WSO2 IS. 

  1. Copy the <OLD_IS_HOME>/repository/data folder to <NEW_IS_HOME>/repository/data folder.
  2. Restart the server to save the changes.

Migrating the configurations

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

  • Migrating by updating the custom configurations

    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.  

    Steps:

    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 the Migrating the data section to run the migration client.
  • Migrating by updating the new configurations in 5.2.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.  

    Steps:

    1. Make a copy of the <OLD_IS_HOME>/repository/conf folder. (Do not change the original configurations. 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/carbon.properties

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

    3. The sections below list out all the configuration changes from IS 5.0.0 to IS 5.2.0. You can scroll through each table and change the relevant configurations according to the features you are using.

      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 want to change the configurations for the existing tenants, configure it through the management console user interface.

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

       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>

       API changes: Click here to view the steps..

      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

      Recommended: See the WSO2 IS 5.1.0 migration guide for more information.

      Note that the following files located in the <IS_HOME>/repository/conf/ folder in 5.0.0 have been moved to the <IS_HOME>/repository/conf/identity/ folder in 5.1.0 onwards:

      • provisioning-config.xml

      • identity.xml
      • /security/identity-mgt.properties

       Behavioral changes: Click here to view

      Due to a fix done in this release, the effective default value of the system property org.apache.xml.security.ignoreLineBreaks has been changed from “true” to “false”. Due to this change, you will observe line breaks in SAML responses.

      However, if the SAML response consuming client applications have used a standard library such as OpenSAML and use canonicalization when processing the response, this should not cause any problems. Therefore, our recommendation is to use a standard library to process SAML responses on consuming applications.

      If you have any concerns about this behavioral change or if the SAML response consuming client applications does not use canonicalization when processing the response and the client cannot be updated to do so, add the following jvm parameter to the server startup script located in the <IS_HOME>/bin/ folder to revert back to the previous behavior.

      -Dorg.apache.xml.security.ignoreLineBreaks=true
       Configuration changes: Click here to view the table..
      Configuration FileChanges
      oidc-scope-config.xml file stored in the <PRODUCT_HOME>/repository/conf/identity/ directory.The following configuration file was added to enable grouping claims that are bound to a scope value in OpenID Connect (OIDC). When requesting for an OIDC token, you can specify a scope value that is bound to a set of claims in the oidc-scope-config.xml file. When sending that OIDC token to the userinfo endpoint, only the claims that are common to both the oidc-scope-config and the service provider claim configuration, will be returned.
      identity-mgt.properties file stored in the <PRODUCT_HOME>/repository/conf/identity/ directory.

      The following parameters were added:

      # Whether to use hash of username when storing codes. 
      # Enable this if Registry is used to store the codes and if username may contain non alphanumeric characters.
      
      UserInfoRecovery.UseHashedUserNames=false
      UserInfoRecovery.UsernameHashAlg=SHA-1

      If you have enabled the using email address as the username option, the confirmation codes are retained after they are used, due to the special character '@' contained in the email address. To resolve this, you can set the UserInfoRecovery.UseHashedUserNames parameter to true so that the registry resources will be saved by hash of username instead of the email address username which contains the '@' sign.


      The following properties were added to support notification sending for account enabling and disabling:

      Notification.Sending.Enable.Account.Disable=false
      Notification.Sending.Enable.Account.Enable=false

      For more information, see User Account Locking and Account Disabling.


      The following property was added to check if the account has been locked, at the point of authentication.

      Authentication.Policy.Check.Account.Disable=false

      EndpointConfig.properties file stored in the <PRODUCT_HOME>/repository/conf/identity/ directory.

      The following properties were replaced:

      Old configuration
      identity.server.host=localhost
      identity.server.port=9443
      identity.server.serviceURL=/services/

      The properties above were replaced with the following:

      New configuration
      #identity.server.serviceURL=https://localhost:9443/services/ 

      entitlement.properties file stored in the <PRODUCT_HOME>/repository/conf/identity/ directory.

      When policy sets are used with entitlements, the default policy set cache size is 100. This may cause frequent cache eviction if there are more than 100 policies in the set. To avoid this, configure the following property. It will cause the cache size to increase depending on the policy set size for better performance.
       

      PDP.References.MaxPolicyEntries=3000

      identity.xml file stored in the <PRODUCT_HOME>/repository/conf/identity/ directory.

      Session data persistence is enabled by default from IS 5.2.0 onwards.

       Click to see the code block
      <SessionDataPersist>
          <Enable>true</Enable>
          <Temporary>true</Temporary>
          <PoolSize>0</PoolSize>
          <SessionDataCleanUp>
              <Enable>true</Enable>
              <CleanUpTimeout>20160</CleanUpTimeout>
              <CleanUpPeriod>1140</CleanUpPeriod>
          </SessionDataCleanUp>
          <OperationDataCleanUp>
              <Enable>true</Enable>
              <CleanUpPeriod>720</CleanUpPeriod>
          </OperationDataCleanUp>
      </SessionDataPersist>

      The following properties were removed:

      <!--SessionContextCache>
       	<Enable>true</Enable> 
       	<Capacity>100000</Capacity> 
      </SessionContextCache-->

      The following property was added to the <SSOService> and <PassiveSTS> elements:

      <SLOHostNameVerificationEnabled>true</SLOHostNameVerificationEnabled>

      For more information on configuring hostname verification, see the info note at the bottom of the Configuring WS-Federation page.


      Listeners and properties related to analytics in WSO2 Identity Server were added. For more information, see Prerequisites to Publish Statistics.

      Listeners
      <EventListener type="org.wso2.carbon.identity.core.handler.AbstractIdentityMessageHandler" name="org.wso2.carbon.identity.data.publisher.application.authentication.impl.DASLoginDataPublisherImpl" orderId="10" enable="false" />
      <EventListener type="org.wso2.carbon.identity.core.handler.AbstractIdentityMessageHandler" name="org.wso2.carbon.identity.data.publisher.application.authentication.impl.DASSessionDataPublisherImpl" orderId="11" enable="false" />
      <EventListener type="org.wso2.carbon.identity.core.handler.AbstractIdentityMessageHandler" name="org.wso2.carbon.identity.data.publisher.application.authentication.AuthnDataPublisherProxy" orderId="11" enable="true" />
      Properties
      <ISAnalytics>
              <DefaultValues>
                  <userName>NOT_AVAILABLE</userName>
                  <userStoreDomain>NOT_AVAILABLE</userStoreDomain>
                  <rolesCommaSeperated>NOT_AVAILABLE</rolesCommaSeperated>
                  <serviceprovider>NOT_AVAILABLE</serviceprovider>
                  <identityProvider>NOT_AVAILABLE</identityProvider>
              </DefaultValues>
          </ISAnalytics>

      The security element was updated:

      <!-- Security configurations-->
      <Security>
          <!-- The directory under which all other KeyStore files will be stored-->
          <KeyStoresDir>${carbon.home}/conf/keystores</KeyStoresDir>
          <KeyManagerType>SunX509</KeyManagerType> 
          <TrustManagerType>SunX509</TrustManagerType> 
      </Security>

      The following elements were added under the <OAuth> element:

       Click to see the code block
      <OIDCCheckSessionEPUrl>${carbon.protocol}://${carbon.host}:${carbon.management.port}/oidc/checksession</OIDCCheckSessionEPUrl>
      <OIDCLogoutEPUrl>${carbon.protocol}://${carbon.host}:${carbon.management.port}/oidc/logout</OIDCLogoutEPUrl>
      <OIDCConsentPage>${carbon.protocol}://${carbon.host}:${carbon.management.port}/authenticationendpoint/oauth2_consent.do</OIDCConsentPage>
      <OIDCLogoutConsentPage>${carbon.protocol}://${carbon.host}:${carbon.management.port}/authenticationendpoint/oauth2_logout_consent.do</OIDCLogoutConsentPage>
      <OIDCLogoutPage>${carbon.protocol}://${carbon.host}:${carbon.management.port}/authenticationendpoint/oauth2_logout.do</OIDCLogoutPage>
      
      <EnableOAuthCache>false</EnableOAuthCache>

      Caching Recommendation

      It is recommended to keep the OAuth2 local cache and the distributed cache disabled as it may cause out-of-memory issues.
      However, if you want to enable the OAuth2 local cache, you have to enable the distributed cache as well.

      To enable the OAuth2 local cache and distributed cache, set the <EnableOAuthCache> property and isDistributed to true.

      <EnableOAuthCache>true</EnableOAuthCache>
      <Cache name="OAuthCache" enable="true" timeout="1" capacity="5000" isDistributed="true"/>

      The following elements were removed from the <OAuth><OpenIDConnect> element:

      <IDTokenSubjectClaim>http://wso2.org/claims/givenname</IDTokenSubjectClaim>
      <UserInfoEndpointClaimDialect>http://wso2.org/claims</UserInfoEndpointClaimDialect>

      The following code was updated. To add audiences to the JWT token, use the code block below. For more information, see JWT Token Generation.

       Click here to expand...
      <OpenIDConnect>
          <IDTokenBuilder>org.wso2.carbon.identity.openidconnect.DefaultIDTokenBuilder</IDTokenBuilder>
          <!-- Comment out to add Audience values to the JWT token (id_token)-->
          <!--Audiences>
              <Audience>${carbon.protocol}://${carbon.host}:${carbon.management.port}/oauth2/token</Audience>
          </Audiences-->
          <!--Default value for IDTokenIssuerID, is OAuth2TokenEPUrl.If that doesn't satisfy uncomment the following config and explicitly configure the value-->
          <IDTokenIssuerID>${carbon.protocol}://${carbon.host}:${carbon.management.port}/oauth2/token</IDTokenIssuerID>
      
        ...
        
      </OpenIDConnect>

      The <CacheConfig> was replaced:

       Click to see the code block
      <CacheConfig>
          <CacheManager name="IdentityApplicationManagementCacheManager">
              <Cache name="AppAuthFrameworkSessionContextCache" enable="false" timeout="1" capacity="5000" isDistributed="false" />
              <Cache name="AuthenticationContextCache" enable="false" timeout="1" capacity="5000" isDistributed="false" />
              <Cache name="AuthenticationRequestCache" enable="false" timeout="1" capacity="5000" isDistributed="false" />
              <Cache name="AuthenticationResultCache" enable="false" timeout="1" capacity="5000" isDistributed="false" />
              <Cache name="AppInfoCache" enable="true" timeout="1" capacity="5000" isDistributed="false" />
              <Cache name="AuthorizationGrantCache" enable="false" timeout="1" capacity="5000" isDistributed="false" />
              <Cache name="OAuthCache" enable="false" timeout="1" capacity="5000" isDistributed="false" />
              <Cache name="OAuthSessionDataCache" enable="false" timeout="1" capacity="5000" isDistributed="false" />
              <Cache name="SAMLSSOParticipantCache" enable="false" timeout="1" capacity="5000" isDistributed="false" />
              <Cache name="SAMLSSOSessionIndexCache" enable="false" timeout="1" capacity="5000" isDistributed="false" />
              <Cache name="SAMLSSOSessionDataCache" enable="false" timeout="1" capacity="5000" isDistributed="false" />
              <Cache name="ServiceProviderCache" enable="true" timeout="1" capacity="5000" isDistributed="false" />
              <Cache name="ProvisioningConnectorCache" enable="true" timeout="1" capacity="5000" isDistributed="false" />
              <Cache name="ProvisioningEntityCache" enable="false" timeout="1" capacity="5000" isDistributed="false" />
              <Cache name="ServiceProviderProvisioningConnectorCache" enable="true" timeout="1" capacity="5000" isDistributed="false" />
              <Cache name="IdPCacheByAuthProperty" enable="true" timeout="1" capacity="5000" isDistributed="false" />
              <Cache name="IdPCacheByHRI" enable="true" timeout="1" capacity="5000" isDistributed="false" />
              <Cache name="IdPCacheByName" enable="true" timeout="1" capacity="5000" isDistributed="false" />
          </CacheManager>
      </CacheConfig>

      • context.xml file stored in the <PRODUCT_HOME>/repository/conf/tomcat/carbon/META-INF/ directory.
         
      • context.xml file stored in the <PRODUCT_HOME>/repository/conf/tomcat/ directory.
         
      • web.xml file stored in the <PRODUCT_HOME>/repository/conf/tomcat/carbon/WEB-INF/ directory.
       The entire file was replaced.
      carbon.xml file stored in the <PRODUCT_HOME>/repository/conf/ directory.

      The following elements were added under the <Security> tag:

      <STSCallBackHandlerName>org.wso2.carbon.identity.provider.AttributeCallbackHandler</STSCallBackHandlerName>
      
      <XSSPreventionConfig>
          <Enabled>true</Enabled>
          <Rule>allow</Rule>
          <Patterns>
              <!--Pattern></Pattern-->
          </Patterns>
      </XSSPreventionConfig>

      The following elements were removed:

      <!--Configurations to avoid Cross Site Request Forgery vulnerabilities-->
      <CSRFPreventionConfig>
          <!--CSRFPreventionFilter configurations that adopts Synchronizer Token Pattern-->
          <CSRFPreventionFilter>
          <!-- Set below to true to enable the CSRFPreventionFilter-->
          <Enabled>false</Enabled>
          <!--Url Pattern to skip application of CSRF protection-->
          <SkipUrlPattern > (.*)(/images|/css | /js|/docs)(.*) </SkipUrlPattern> 
          </CSRFPreventionFilter> 
      </CSRFPreventionConfig>
      
      <!-- Configuration to enable or disable CR and LF sanitization filter-->
      <CRLFPreventionConfig>
          <!--Set below to true to enable the CRLFPreventionFilter-->
          <Enabled>true</Enabled> 
      </CRLFPreventionConfig
      claim-config.xml file stored in the <PRODUCT_HOME>/repository/conf/ directory.

      The following claims were added. For more information on configuring these, see Configuring Users or User Account Locking and Account Disabling depending on the claim you want to configure.

      <Claim>
          <ClaimURI>http://wso2.org/claims/identity/lastLoginTime</ClaimURI>
          <DisplayName>Last Login</DisplayName>
          <!-- Proper attribute Id in your user store must be configured for this -->
          <AttributeID>carLicense</AttributeID>
          <Description>Last Login Time</Description>
      </Claim>
      <Claim>
          <ClaimURI>http://wso2.org/claims/identity/lastPasswordUpdateTime</ClaimURI>
          <DisplayName>Last Password Update</DisplayName>
          <!-- Proper attribute Id in your user store must be configured for this -->
          <AttributeID>businessCategory</AttributeID>
          <Description>Last Password Update Time</Description>
      </Claim>
      <Claim>
          <ClaimURI>http://wso2.org/claims/identity/accountDisabled</ClaimURI>
          <DisplayName>Account Disabled</DisplayName>
          <!-- Proper attribute Id in your user store must be configured for this -->
          <AttributeID>ref</AttributeID>
          <Description>Account Disabled</Description>
      </Claim>
      • data-agent-config.xml file stored in the  <PRODUCT_HOME>/repository/conf/data-bridge/ directory.
      • event-processor.xml file stored in the  <PRODUCT_HOME>/repository/conf/ directory.


      The file was newly added.
      metrics-datasources.xml file stored in the  <PRODUCT_HOME>/repository/conf/datasources/ directory.

      Set the <defaultAutocommit> property to true.

       Click to see the code block
       <datasource>
                  <name>WSO2_METRICS_DB</name>
                  <description>The default datasource used for WSO2 Carbon Metrics</description>
                  <jndiConfig>
                      <name>jdbc/WSO2MetricsDB</name>
                  </jndiConfig>
                  <definition type="RDBMS">
                      <configuration>        <url>jdbc:h2:repository/database/WSO2METRICS_DB;DB_CLOSE_ON_EXIT=FALSE;AUTO_SERVER=TRUE</url>
                          <username>wso2carbon</username>
                          <password>wso2carbon</password>
                          <driverClassName>org.h2.Driver</driverClassName>
                          <maxActive>50</maxActive>
                          <maxWait>60000</maxWait>
                          <testOnBorrow>true</testOnBorrow>
                          <validationQuery>SELECT 1</validationQuery>
                          <validationInterval>30000</validationInterval>
                          <defaultAutoCommit>true</defaultAutoCommit>
                      </configuration>
                  </definition>
              </datasource>
      application-authentication.xml file stored in the <PRODUCT_HOME>/repository/conf/identity/ directory.
       Click to see the code block
      <AuthenticatorConfig name="EmailOTP" enabled="true">
          <Parameter name="GmailClientId">gmailClientIdValue</Parameter>
          <Parameter name="GmailClientSecret">gmailClientSecretValue</Parameter>
          <Parameter name="SendgridAPIKey">sendgridAPIKeyValue</Parameter>
          <Parameter name="GmailRefreshToken">gmailRefreshTokenValue</Parameter>
          <Parameter name="GmailEmailEndpoint">https://www.googleapis.com/gmail/v1/users/[userId]/messages/send</Parameter>
          <Parameter name="SendgridEmailEndpoint">https://api.sendgrid.com/api/mail.send.json</Parameter>
          <Parameter name="accessTokenRequiredAPIs">Gmail</Parameter>
          <Parameter name="apiKeyHeaderRequiredAPIs">Sendgrid</Parameter>
          <Parameter name="SendgridFormData">sendgridFormDataValue</Parameter>
          <Parameter name="SendgridURLParams">sendgridURLParamsValue</Parameter>
          <Parameter name="GmailAuthTokenType">Bearer</Parameter>
          <Parameter name="GmailTokenEndpoint">https://www.googleapis.com/oauth2/v3/token</Parameter>
          <Parameter name="SendgridAuthTokenType">Bearer</Parameter>
      </AuthenticatorConfig>
      
      <AuthenticatorConfig name="x509CertificateAuthenticator" enabled="true">
          <Parameter name="AuthenticationEndpoint">https://localhost:8443/x509-certificate-servlet</Parameter>
      </AuthenticatorConfig>
      
      <AuthenticatorConfig name="totp" enabled="true">
          <Parameter name="encodingMethod">Base32</Parameter>
          <Parameter name="timeStepSize">30</Parameter>
          <Parameter name="windowSize">3</Parameter>
          <Parameter name="enableTOTP">false</Parameter>
      </AuthenticatorConfig>
      metrics.xml file stored in the <PRODUCT_HOME>/repository/conf/ directory.

      The following elements were added:

       Click to see the code block
      <Metrics xmlns="http://wso2.org/projects/carbon/metrics.xml">
          <Reporting>
              <Console>
                  <Enabled>false</Enabled>
                  <!-- Polling Period in seconds.
                      This is the period for polling metrics from the metric registry and
                      printing in the console -->
                  <PollingPeriod>60</PollingPeriod>
              </Console>
      
              <DAS>
                  <Enabled>false</Enabled>
                  <!-- Source of Metrics, which will be used to
                      identify each metric sent in the streams -->
                  <!-- Commented to use the hostname
                      <Source>Carbon</Source>
                  -->
                  <!-- Polling Period in seconds.
                      This is the period for polling metrics from the metric registry and
                      sending events via the Data Publisher -->
                  <PollingPeriod>60</PollingPeriod>
                  <!-- The type used with Data Publisher -->
                  <Type>thrift</Type>
                  <!-- Data Receiver URL used by the Data Publisher -->
                  <ReceiverURL>tcp://localhost:7611</ReceiverURL>
                  <!-- Authentication URL for the Data Publisher -->
                  <!-- <AuthURL>ssl://localhost:7711</AuthURL> -->
                  <Username>admin</Username>
                  <Password>admin</Password>
                  <!-- Path for Data Agent Configuration -->
                  <DataAgentConfigPath>repository/conf/data-bridge/data-agent-config.xml</DataAgentConfigPath>
              </DAS>
      output-event-adapters.xml file stored in the <PRODUCT_HOME>/repository/conf/ directory.

      The following adapter configurations were added:

       Click to see the code block
      <adapterConfig type="http">
          <!-- Thread Pool Related Properties -->
          <property key="minThread">8</property>
          <property key="maxThread">100</property>
          <property key="keepAliveTimeInMillis">20000</property>
          <property key="jobQueueSize">10000</property>
          <!-- HTTP Client Pool Related Properties -->
          <property key="defaultMaxConnectionsPerHost">50</property>
          <property key="maxTotalConnections">1000</property>
      </adapterConfig>
      
      <adapterConfig type="jms">
          <!-- Thread Pool Related Properties -->
          <property key="minThread">8</property>
          <property key="maxThread">100</property>
          <property key="keepAliveTimeInMillis">20000</property>
          <property key="jobQueueSize">10000</property>
      </adapterConfig>
      
      <adapterConfig type="mqtt">
          <!-- Thread Pool Related Properties -->
          <property key="minThread">8</property>
          <property key="maxThread">100</property>
          <property key="keepAliveTimeInMillis">20000</property>
          <property key="jobQueueSize">10000</property>
          <property key="connectionKeepAliveInterval">60</property>
      </adapterConfig>
      
      <adapterConfig type="kafka">
          <!-- Thread Pool Related Properties -->
          <property key="minThread">8</property>
          <property key="maxThread">100</property>
          <property key="keepAliveTimeInMillis">20000</property>
          <property key="jobQueueSize">10000</property>
      </adapterConfig>
      
      <adapterConfig type="email">
          <!-- Comment mail.smtp.user and mail.smtp.password properties to support connecting SMTP servers which use trust
              based authentication rather username/password authentication -->
          <property key="mail.smtp.from">abcd@gmail.com</property>
          <property key="mail.smtp.user">abcd</property>
          <property key="mail.smtp.password">xxxx</property>
          <property key="mail.smtp.host">smtp.gmail.com</property>
          <property key="mail.smtp.port">587</property>
          <property key="mail.smtp.starttls.enable">true</property>
          <property key="mail.smtp.auth">true</property>
          <!-- Thread Pool Related Properties -->
          <property key="minThread">8</property>
          <property key="maxThread">100</property>
          <property key="keepAliveTimeInMillis">20000</property>
          <property key="jobQueueSize">10000</property>
      </adapterConfig>
      
      <adapterConfig type="ui">
          <property key="eventQueueSize">30</property>
          <!-- Thread Pool Related Properties -->
          <property key="minThread">8</property>
          <property key="maxThread">100</property>
          <property key="keepAliveTimeInMillis">20000</property>
          <property key="jobQueueSize">10000</property>
      </adapterConfig>
      
      <adapterConfig type="websocket-local">
          <!-- Thread Pool Related Properties -->
          <property key="minThread">8</property>
          <property key="maxThread">100</property>
          <property key="keepAliveTimeInMillis">20000</property>
          <property key="jobQueueSize">10000</property>
      </adapterConfig>
      
      <adapterConfig type="websocket">
          <!-- Thread Pool Related Properties -->
          <property key="minThread">8</property>
          <property key="maxThread">100</property>
          <property key="keepAliveTimeInMillis">20000</property>
          <property key="jobQueueSize">10000</property>
      </adapterConfig>
      
      <adapterConfig type="soap">
          <!-- Thread Pool Related Properties -->
          <property key="minThread">8</property>
          <property key="maxThread">100</property>
          <property key="keepAliveTimeInMillis">20000</property>
          <property key="jobQueueSize">10000</property>
          <!-- Axis2 Client Connection Related Properties -->
          <property key="axis2ClientConnectionTimeout">10000</property>
          <property key="reuseHTTPClient">true</property>
          <property key="autoReleaseConnection">true</property>
          <property key="maxConnectionsPerHost">50</property>
      </adapterConfig>
      registry.xml file stored in the <PRODUCT_HOME>/repository/conf/ directory.

      The following elements were added:

       Click to see the code block
      <indexingConfiguration>
          <startIndexing>false</startIndexing>
          <startingDelayInSeconds>35</startingDelayInSeconds>
          <indexingFrequencyInSeconds>5</indexingFrequencyInSeconds>
          <!--number of resources submit for given indexing thread -->
          <batchSize>40</batchSize>
          <!--number of worker threads for indexing -->
          <indexerPoolSize>40</indexerPoolSize>
          <!-- location storing the time the indexing took place-->
          <lastAccessTimeLocation>/_system/local/repository/components/org.wso2.carbon.registry/indexing/lastaccesstime</lastAccessTimeLocation>
          <!-- the indexers that implement the indexer interface for a relevant media type/(s) -->
          <indexers>
              <indexer class="org.wso2.carbon.registry.indexing.indexer.MSExcelIndexer" mediaTypeRegEx="application/vnd.ms-excel" />
              <indexer class="org.wso2.carbon.registry.indexing.indexer.MSPowerpointIndexer" mediaTypeRegEx="application/vnd.ms-powerpoint" />
              <indexer class="org.wso2.carbon.registry.indexing.indexer.MSWordIndexer" mediaTypeRegEx="application/msword" />
              <indexer class="org.wso2.carbon.registry.indexing.indexer.PDFIndexer" mediaTypeRegEx="application/pdf" />
              <indexer class="org.wso2.carbon.registry.indexing.indexer.XMLIndexer" mediaTypeRegEx="application/xml" />
              <indexer class="org.wso2.carbon.registry.indexing.indexer.XMLIndexer" mediaTypeRegEx="application/(.)+\+xml" />
              <indexer class="org.wso2.carbon.registry.indexing.indexer.PlainTextIndexer" mediaTypeRegEx="application/swagger\+json" />
              <indexer class="org.wso2.carbon.registry.indexing.indexer.PlainTextIndexer" mediaTypeRegEx="application/(.)+\+json" />
              <indexer class="org.wso2.carbon.registry.indexing.indexer.PlainTextIndexer" mediaTypeRegEx="text/(.)+" />
              <indexer class="org.wso2.carbon.registry.indexing.indexer.PlainTextIndexer" mediaTypeRegEx="application/x-javascript" />
          </indexers>
          <exclusions>
              <exclusion pathRegEx="/_system/config/repository/dashboards/gadgets/swfobject1-5/.*[.]html" />
              <exclusion pathRegEx="/_system/local/repository/components/org[.]wso2[.]carbon[.]registry/mount/.*" />
          </exclusions>
      </indexingConfiguration>
      user-mgt.xml file stored in the <PRODUCT_HOME>/repository/conf/ directory.

      The following LDAP/AD property was added:

      <Property name="AnonymousBind">false</Property>

      Recommended: See the WSO2 IS 5.2.0 migration guide for more information.

      Note that the following new configuration files have been added from 5.2.0 onwards.

      • repository/conf/event-processor.xml
      • repository/conf/security/Owasp.CsrfGuard.Carbon.properties
      • repository/conf/tomcat/carbon/WEB-INF/web.xml
      • repository/conf/identity/oidc-scope-config.xml
    4. Replace the <NEW_IS_HOME>/repository/conf folder with the modified copy of the <OLD_IS_HOME>/repository/conf folder.

    5. Proceed to the Migrating the data section to run the migration client.

Migrating the custom components

Any custom OSGI bundles which were added manually should be recompiled with new dependency versions that are relevant to the new WSO2 IS version. All custom OSGI components reside in the <OLD_IS_HOME>/repository/components/dropins directory.

  1. Get the source codes of the custom OSGI components located in the dropins directory.
  2. Change the dependency versions in the relevant POM files according to the WSO2 IS version that you are upgrading to, and compile them. The compatible dependency versions for each release of WSO2 IS is given below.

  3. If you come across any compile time errors, refer to the WSO2 IS code base and make the necessary changes related to that particular component version.

  4. Add the compiled JAR files to the <NEW_IS_HOME>/repository/components/dropins directory.
  5. If there were any custom OSGI components in <OLD_IS_HOME>/repository/components/lib directory, add newly compiled versions of those components to the <NEW_IS_HOME>/repository/components/lib directory.

Migrating the data

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.

Download the latest version of WSO2 Identity Server and unzip it in the <NEW_IS_HOME> directory.

  1. Take a backup of the existing database used by the <OLD_IS>. This backup is necessary in case the migration causes issues in the existing database.
    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 <IS_MIGRATION_TOOL_HOME>.

    2. Copy the org.wso2.carbon.is.migration-5.x.x.jar and the snakeyaml-1.16.0.wso2v1.jar found in the <IS_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. Set the following property values accordingly in the migration-config.yaml file found in the <NEW_IS_HOME>/migration-resources folder. Specify the current WSO2 Identity Server version as the currentVersion value and specify the new version of WSO2 Identity Server that you want to migrate to, as the  migrateVersion.

      migrationEnable: "true"
      
      currentVersion: "5.x.x"
      
      migrateVersion: "5.x.x"
  2. 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. 
  3. 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. 

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

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

    Note: If your current version is 5.0.0, run the following queries on the database that is referenced in the identity.xml file in order 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';
  7. Start WSO2 Identity Server with the following command to perform the data migration for all components. 

    1. Linux/Unix:

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

      wso2server.bat -Dmigrate -Dcomponent=identity
  8. Once the migration is successful, stop the server and remove the following files and folders from the <NEW_IS_HOME>/repository/components/dropins directory.

    1.  org.wso2.carbon.is.migration-5.x.x.jar

    2. snakeyaml-1.16.0.wso2v1.jar 

    3. migration-resources directory

  • No labels