This documentation is for WSO2 Identity Server 5.4.0 . View documentation for the latest release.

Versions Compared

Key

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

...

  1. Download Identity Server 5.3.0 and unzip it in the <NEW_IS_HOME> directory.
  2. Take a backup of the existing database used by Identity Server 5.2.0. This backup is necessary in case the migration causes issues in the existing database.
  3. 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.3.0_MIGRATION_TOOL_HOME>.

      2. Copy the db script files in the <IS5.3.0_MIGRATION_TOOL_HOME>/dbscripts/identity/ directory to the <NEW_IS_HOME>/dbscripts/identity/migration-5.2.0_to_5.3.0/ directory.

      3. Copy the org.wso2.carbon.is.migrate.client-5.3.0.jar file in the  <IS5.3.0_MIGRATION_TOOL_HOME>/dropins directory to the <NEW_IS_HOME>/repository/components/dropins directory. 
      4. Alternatively, if you are using Oracle database, 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.
  4. Make a copy of the <OLD_IS_HOME>/repository/conf folder. (Do not change the original configs. You may use it as a backup in case there are any issues)

  5. Copy the following files from the <NEW_IS_HOME>/repository/conf/identity folder and paste it in the copy of the <OLD_IS_HOME>/repository/conf/identity folder:
    • captcha-config.properties
    • identity-event.properties
  6. 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. 
  7. 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. 
  8. Open the output-event-adapters.xml file found in the <NEW_IS_HOME>/repository/conf folder and configure the relevant email configurations. 

    Code Block
    languagexml
    <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>
    Tip

    Tip: This email configuration is similiar to the email configuration shown in the code block below, which is found in the <IS_HOME>/repository/conf/axis2/axis2.xml file. This configuration is used for email-enabled features. You can configure the same values in the output-event-adapters.xml file for email-enabled features using REST APIs in IS 5.3.0.

    Code Block
    titleEmail configuration in axis2.xml file
    <transportSender name="mailto"class="org.apache.axis2.transport.mail.MailTransportSender">
        <parameter name="mail.smtp.from">sampleemail@gmail.com</parameter>
        <parameter name="mail.smtp.user">sampleemail</parameter>
        <parameter name="mail.smtp.password">password</parameter>
        <parameter name="mail.smtp.host">smtp.gmail.com</parameter>
        <parameter name="mail.smtp.port">587</parameter>
        <parameter name="mail.smtp.starttls.enable">true</parameter>
        <parameter name="mail.smtp.auth">true</parameter>
    </transportSender> 
  9. Copy the .jks files from the <OLD_IS_HOME>/repository/resources/security folder and paste them in <NEW_IS_HOME>/repository/resources/security folder. 

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

  12. If you have done custom changes to the config files in your previous version of WSO2 IS, see the table below. 

    The table below lists out all the configuration changes from IS 5.2.0 to IS 5.3.0. You can scroll through the table and change the relevant configurations according to the features you are using. Any step which is not explicitly mentioned as “optional” is mandatory for the migration. 

    Tip

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

    Info
    titleMandatory configuration changes: Click here to view the table..
    Expand
    Configuration FileChanges

    [MANDATORY]

    identity-event.properties file stored in the <IS_HOME>/repository/conf/identity folder.

    Add the following property shown at line number 2.

    Code Block
    linenumberstrue
    module.name.5=account.disable.handler
    account.disable.handler.enable=false
    account.disable.handler.subscription.1=PRE_AUTHENTICATION
    identity.xml file stored in the <IS_HOME>/repository/conf/identity folder.

    Add the following property found under the <SessionDataCleanUp> tag.

    Code Block
    <DeleteChunkSize>50000</DeleteChunkSize>

    Remove the following property found under the <OperationDataCleanUp> tag.

    Code Block
     <CleanUpPeriod>720</CleanUpPeriod>

    Change the default value of the following property from 300 to 0.

    Warning

    You can skip this step if you have already configured the <TimestampSkew> property with your own value.

    Code Block
    <TimestampSkew>0</TimestampSkew>

    Add the following JWT bearer grant type.

    Code Block
    linenumberstrue
    <SupportedGrantType>
    <GrantTypeName>urn:ietf:params:oauth:grant-type:jwt-bearer</GrantTypeName>
    <GrantTypeHandlerImplClass>org.wso2.carbon.identity.oauth2.grant.jwt.JWTBearerGrantHandler</GrantTypeHandlerImplClass>
    <GrantTypeValidatorImplClass>org.wso2.carbon.identity.oauth2.grant.jwt.JWTGrantValidator</GrantTypeValidatorImplClass>
    </SupportedGrantType>

    Update the <EmailVerification> code block with the following code.
    The properties shown below at line numbers 3,8,9 & 10 were added in 5.4.0.

    Code Block
    linenumberstrue
    <EmailVerification>
        <Enable>false</Enable>
        <ExpiryTime>1440</ExpiryTime>
        <LockOnCreation>true</LockOnCreation>
        <Notification>
            <InternallyManage>true</InternallyManage>
        </Notification>
        <AskPassword>
            <ExpiryTime>1440</ExpiryTime>
        </AskPassword>
    </EmailVerification>

    Update the following property found under the <SelfRegistration> tag to true.

    Code Block
    <LockOnCreation>true</LockOnCreation>

    Add the following properties under the <SelfRegistration> tag.

    Code Block
    linenumberstrue
    <VerificationCode>
      <ExpiryTime>1440</ExpiryTime>
    </VerificationCode>
    authenticators.xml file stored in the <IS_HOME>/repository/conf/identity folder.

    Update the parameter name of the <JITUserProvisioning> parameter to the following.

    Code Block
    <Parameter name="JITUserProvisioningEnabled">true</Parameter>
    web.xml file stored in the <IS_HOME>/repository/conf/tomcat folder.

    Add the following property under the <session-config> tag.

    Code Block
    <tracking-mode>COOKIE</tracking-mode>
    user-mgt.xml file stored in the <IS_HOME>/repository/conf folder.

    Update the default value of the following properties as follows.

    Warning

    You can skip this step if you have already configured these properties with your own RegEx.

    Code Block
    <Property name="UsernameJavaRegEx">[a-zA-Z0-9._\-|//]{3,30}$</Property>
    Code Block
    <Property name="RolenameJavaRegEx">[a-zA-Z0-9._\-|//]{3,30}$</Property>
    claim-config.xml file stored in the <IS_HOME>/repository/conf folder.

    Add the following claim.

    Code Block
    linenumberstrue
    <Claim>
    	<ClaimURI>http://wso2.org/claims/identity/phoneVerified</ClaimURI>
    	<DisplayName>Phone Verified</DisplayName>
    	<!-- Proper attribute Id in your user store must be configured for this -->
    	<AttributeID>imSkype</AttributeID>
    	<Description>Phone Verified</Description>
    </Claim>

    Change the following claim mappings.

    1. Remove the property at line number 7 and add in the property at line number 8.

      Code Block
      linenumberstrue
      <Claim>	
      	<ClaimURI>http://schemas.xmlsoap.org/ws/2005/05/identity/claims/homephone</ClaimURI>
      	<DisplayName>Home Phone</DisplayName>
      	<AttributeID>homePhone</AttributeID>
      	<Description>Home Phone</Description>
      	<SupportedByDefault />
      	<MappedLocalClaim>http://wso2.org/claims/country</MappedLocalClaim>
      	<MappedLocalClaim>http://wso2.org/claims/phoneNumbers.home</MappedLocalClaim>
      </Claim>
    2. Remove the property at line number 7 and add in the property at line number 8.

      Code Block
      linenumberstrue
      <Claim>
      	<ClaimURI>http://schemas.xmlsoap.org/ws/2005/05/identity/claims/privatepersonalidentifier</ClaimURI>
      	<AttributeID>privatePersonalIdentifier</AttributeID>
      	<Description>PPID</Description>
      	<Required />
      	<SupportedByDefault />
      	<MappedLocalClaim>http://wso2.org/claims/country</MappedLocalClaim>
      	<MappedLocalClaim>http://wso2.org/claims/im</MappedLocalClaim>
      </Claim>
    3. Remove the property at line number 8 and add in the property at line number 9.

      Code Block
      linenumberstrue
      <Claim>
      	<ClaimURI>timezone</ClaimURI>
      	<DisplayName>Time Zone</DisplayName>
      	<AttributeID>timeZone</AttributeID>
      	<Description>Time Zone</Description>
      	<DisplayOrder>9</DisplayOrder>
      	<SupportedByDefault />
      	<MappedLocalClaim>http://wso2.org/claims/country</MappedLocalClaim>
      	<MappedLocalClaim>http://wso2.org/claims/timeZone</MappedLocalClaim>
      </Claim>
    4. Remove the property at line number 8 and add in the property at line number 9.

      Code Block
      linenumberstrue
      <Claim>
          <ClaimURI>postcode</ClaimURI>
          <DisplayName>Postalcode</DisplayName>
          <AttributeID>postalCode</AttributeID>
          <Description>Postalcode</Description>
          <DisplayOrder>4</DisplayOrder>
          <SupportedByDefault />
          <MappedLocalClaim>http://wso2.org/claims/country</MappedLocalClaim>
          <MappedLocalClaim>http://wso2.org/claims/postalcode</MappedLocalClaim>
      </Claim>
    5. Remove the property at line number 8 and add in the property at line number 9.

      Code Block
      linenumberstrue
      <Claim>
          <ClaimURI>language</ClaimURI>
          <DisplayName>Language</DisplayName>
          <AttributeID>prefferedLanguage</AttributeID>
          <Description>Language</Description>
          <DisplayOrder>7</DisplayOrder>
          <SupportedByDefault />
          <MappedLocalClaim>http://wso2.org/claims/country</MappedLocalClaim>
          <MappedLocalClaim>http://wso2.org/claims/preferredLanguage</MappedLocalClaim>
      </Claim>
    6. Remove the property at line number 6 and add in the property at line number 7.

      Code Block
      linenumberstrue
      <Claim>
          <ClaimURI>http://axschema.org/pref/timezone</ClaimURI>
          <DisplayName>Time Zone</DisplayName>
          <AttributeID>timeZone</AttributeID>
          <Description>Time Zone</Description>
          <MappedLocalClaim>http://wso2.org/claims/country</MappedLocalClaim>
          <MappedLocalClaim>http://wso2.org/claims/timeZone</MappedLocalClaim>
      </Claim>
    7. Remove the property at line number 6 and add in the property at line number 7.

      Code Block
      linenumberstrue
      <Claim>
          <ClaimURI>http://axschema.org/contact/postalCode/home</ClaimURI>
          <DisplayName>Postalcode</DisplayName>
          <AttributeID>postalCode</AttributeID>
          <Description>Postalcode</Description>
          <SupportedByDefault />
          <MappedLocalClaim>http://wso2.org/claims/country</MappedLocalClaim>
          <MappedLocalClaim>http://wso2.org/claims/postalcode</MappedLocalClaim>
      </Claim>



  13. Replace the <NEW_IS_HOME>/repository/conf folder with the modified copy of the <OLD_IS_HOME>/repository/conf folder.

  14. Start the Identity Server 5.3.0 with the following command to perform the data migration for all components. 

    Info

    See the notes below to perform migration for individual components or for active tenants only. 

    1. Linux/Unix:

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

      Code Block
      languagebash
      wso2server.bat -Dmigrate -Dcomponent=identity 
      Note
      titleMigrate 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
      ComponentLinux/UnixWindows
      Identity Database Schema
      Code Block
      languagebash
      sh wso2server.sh -Dmigrate -Dcomponent
      =identity -DmigrateIdentityDB
      Code Block
      languagebash
      wso2server.bat -Dmigrate -Dcomponent
      =identity -DmigrateIdentityDB
      Claim Data
      Code Block
      languagebash
      sh wso2server.sh -Dmigrate -Dcomponent
      =identity -DmigrateClaimData
      Code Block
      languagebash
      wso2server.bat -Dmigrate -Dcomponent=
      identity -DmigrateClaimData
      Email Template Data
      Code Block
      languagebash
      sh wso2server.sh -Dmigrate -Dcomponent
      =identity -DmigrateEmailTemplateData
      Code Block
      languagebash
      wso2server.bat -Dmigrate -Dcomponent
      =identity -DmigrateEmailTemplateData
      Permission Data
      Code Block
      languagebash
      sh wso2server.sh -Dmigrate -Dcomponent
      =identity -DmigratePermissionData
      Code Block
      languagebash
      wso2server.bat -Dmigrate -Dcomponent
      =identity -DmigratePermissionData
      Challenge Question Data
      Code Block
      languagebash
      sh wso2server.sh -Dmigrate -Dcomponent
      =identity -DmigrateChallengeQuestionData
      Code Block
      languagebash
      wso2server.bat -Dmigrate -Dcomponent
      =identity -DmigrateChallengeQuestionData
      Resident IdP MetaData
      Code Block
      languagebash
      sh wso2server.sh -Dmigrate -Dcomponent
      =identity -DmigrateResidentIdpMetaData
      Code Block
      languagebash
      wso2server.bat -Dmigrate -Dcomponent
      =identity -DmigrateResidentIdpMetaData
      OIDC Scope Data
      Code Block
      languagebash
      sh wso2server.sh -Dmigrate -Dcomponent
      =identity -DmigrateOIDCScopeData
      Code Block
      languagebash
      wso2server.bat -Dmigrate -Dcomponent
      =identity -DmigrateOIDCScopeData
      Note
      titleMigrate active tenants only

      Optional:If you have any disabled/inactive tenants in your previous version of WSO2 IS that you do not want to bring forward to the next version, do a complete migration for all components with active tenants only.

      Expand
      titleClick here to view the command

      Start the server against the migration client jar located in the <IS_HOME>/repository/components/dropins directory using the -DmigrateActiveTenantsOnly flag, as shown below.

      Code Block
      sh wso2server.sh -Dmigrate -Dcomponent=identity -DmigrateActiveTenantsOnly
  15. Once the migration is successful, stop the server and start using the appropriate command.
    1. Linux/Unix:

      Code Block
      languagexml
      sh wso2server.sh
    2. Windows:

      Code Block
      languagexml
      wso2server.bat