This documentation is for WSO2 Identity Server 5.3.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. 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. 
  5. 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. 

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

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

  9. The ClaimManagementService API is not recommended for use with WSO2 IS 5.3.0. If you are using the ClaimManagementService API and have written any clients using the service, convert the clients to the new and improved ClaimMetadataManagementService API that is packaged with WSO2 IS 5.3.0. 

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

    • Migrate by applying custom configurations to 5.3.0

      Panel

      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 configurations in the config files of your previous version of WSO2 IS, reconfigure the files in the <NEW_IS_HOME>/repository/conf folder with your configurations. 
      2. Proceed to step 11 to run the migration client.
    • Migrate by updating the existing configurations with what's new in 5.3.0

      Panel

      This approach is recommended if:

      • You have done many custom changes in your previous version of WSO2 IS.
      • These configuration changes 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 configs. You may use it as a backup in case there are any issues)
      2. Copy the following files from the <NEW_IS_HOME>/repository/conf/identity folder and paste it into the copy of the <OLD_IS_HOME>/repository/conf/identity folder:

        • captcha-config.properties
        • identity-event.properties
      3. Open the output-event-adapters.xml file found in the <NEW_IS_HOME>/repository/conf folder and configure the relevant email configurations. 

        Expand
        titleClick to view more information
        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">[email protected]</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 similar 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
        languagexml
        titleEmail configuration in axis2.xml file
        <transportSender name="mailto"class="org.apache.axis2.transport.mail.MailTransportSender">    <parameter name="mail.smtp.from">[email protected]</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> 
      4. The table below lists out all the configuration changes from IS 5.2.0 to IS 5.3.0. 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. 

        Info

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

        Panel
        borderColorblack
        bgColorwhite
        borderWidth2
        borderStylesolid
        Changeexcerpt
        Tipexcerpt
        Expand
        titleBehavioral
        changes: Click here to view
        Tip

        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.

        Code Block
        -Dorg.apache.xml.security.ignoreLineBreaks=true
        Expand
        titleConfiguration changes: Click here to view the table..
        Configuration FileRequiredChanges

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

        Mandatory

        Add the following property to the config file.

        Code Block
        <HideMenuItemIds>
        <HideMenuItemId>claim_mgt_menu</HideMenuItemId>
        <HideMenuItemId>identity_mgt_emailtemplate_menu</HideMenuItemId>
        <HideMenuItemId>identity_security_questions_menu</HideMenuItemId>
        </HideMenuItemIds>

        Update the following property value to 5.3.0.

        Code Block
        <Version>5.3.0</Version>

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

        Optional

        If you are using the service provider authorization feature, add the following property to the config file.

        Note

        If you have any other AttributeDesignators configured with the number 2, use the smallest unused number instead of 2 when adding the property below.

        Code Block
        languagexml
        PIP.AttributeDesignators.Designator.2=org.wso2.carbon.identity.application.authz.xacml.pip.AuthenticationContextAttributePIP

        The application-authentication.xml file stored in the <PRODUCT_HOME>/repository/conf/identity/ directory.

        Mandatory

        Add the following property under the <Extensions> tag.

        Code Block
        languagexml
        <AuthorizationHandler>org.wso2.carbon.identity.application.authz.xacml.handler.impl.XACMLBasedAuthorizationHandler</AuthorizationHandler>

        The application-authentication.xml file stored in the <PRODUCT_HOME>/repository/conf/identity/ directory.

        Optional

        If you are using the mobile connect authenticator feature, add the following element under the <AuthenticatorConfigs> tag.

        Code Block
        languagexml
        <AuthenticatorConfig name="MobileConnectAuthenticator" enabled="true">
            <Parameter name="MobileConnectKey">mobileConnectClientId</Parameter>
            <Parameter name="MobileConnectSecret">mobileConnectClientSecret</Parameter>
        </AuthenticatorConfig>

        The Owasp.CsrfGuard.Carbon.properties stored in the <PRODUCT_HOME>/repository/conf/security/ directory.

        Mandatory

        Find the following line.

        Code Block
        languagexml
        titleOld configuration
        org.owasp.csrfguard.unprotected.authiwa=%servletContext%/commonauth/iwa/*

        Update the line as follows.

        Code Block
        languagexml
        titleNew Configuration
        org.owasp.csrfguard.unprotected.oauthiwa=%servletContext%/commonauth/iwa/*

        Add the following property.

        Code Block
        languagexml
        org.owasp.csrfguard.unprotected.mex=%servletContext%/mexut/*

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

        Mandatory

        Add the following element under the <Realm> <Configuration> tag.

        Code Block
        languagexml
        <Property name="initializeNewClaimManager">true</Property>

        The email-admin-config.xml file stored in the <PRODUCT_HOME>/repository/conf/ directory.

        Mandatory

        If you have not made any custom changes to this file in your previous version of WSO2 IS:

          • Copy the <NEW_IS_HOME>/repository/conf/email/email-admin-config.xml file and replace the existing one.

        If you have made custom changes to this file in your previous version:

          1. Locate the templates you have updated that differ from the default config file. You can use a diff tool to compare your <OLD_IS_HOME>/repository/conf/email/email-admin-config.xml file with the default file to identify the custom changes you have made. Note these changes/updates.
          2. Copy the file from <NEW_IS_HOME>/repository/conf/email/email-admin-config.xml to <OLD_IS_HOME>/repository/conf/email/ directory and rename it to email-"admin-config-new.xml".
          3. For each template you have modified, do the following:

            Note

            Note: If you opt to migrate to the new identity management implementation, follow all the steps below. If you wish to continue with the old identity management implementation, skip steps iii and iv.

            1. Locate the relevant template configuration in the old email-admin-config-new.xml file by searching for ‘<configuration type="xxxxx" where “xxxxx” is the type at email-admin-config.xml.

            2. Update the subject, body, and footer in the new config file with the values from the existing configuration.

            3. [OPTIONAL] Update the placeholders so that they are enclosed with double braces (E.g., {user-name} -> {{user-name}} )

            4. [OPTIONAL] Update the user’s attribute related placeholders to follow the {{user.claim.yyyy}} format where yyyy is the attribute name (E.g., {first-name} -> {{user.claim.givenname}})
          1. Delete the <OLD_IS_HOME>/repository/conf/email/email-admin-config.xml file and rename the email-admin-config-new.xml file to "email-admin-config.xml” to finish the update.

        Info

        For more information about this feature, see Email Templates.

        The output-event-adapters.xml file stored in the <PRODUCT_HOME>/repository/conf/ directory.

        Optional

        Add the following properties under the <outputEventAdaptersConfig> tag.

        Code Block
        languagexml
        <adapterConfig type="wso2event">
            <property key="default.thrift.tcp.url">tcp://localhost:7612</property  
            <property key="default.thrift.ssl.url">ssl://localhost:7712</property>
            <property key="default.binary.tcp.url">tcp://localhost:9612</property>
            <property key="default.binary.ssl.url">ssl://localhost:9712</property>
        </adapterConfig>
        The identity.xml file stored in the <PRODUCT_HOME>/repository/conf/identitydirectory.Mandatory

        Add the following event listeners as child elements under the <EventListeners> tag.

        Code Block
        <EventListeners>
        	....
        	....
        	<EventListener 
          	type="org.wso2.carbon.user.core.listener.UserOperationEventListener" 
          	name="org.wso2.carbon.identity.governance.listener.IdentityStoreEventListener"
          	orderId="97" enable="true">
            <Property name="Data.Store">org.wso2.carbon.identity.governance.store.JDBCIdentityDataStore</Property>
        	</EventListener>
                    
        	<EventListener 
          	type="org.wso2.carbon.user.core.listener.UserOperationEventListener" 
          	name="org.wso2.carbon.identity.governance.listener.IdentityMgtEventListener" 
          	orderId="95" 
          	enable="true"/>
        	....
        </EventListeners>

        Add the following properties under the <OAuth> tag.

        Code Block
        <OIDCWebFingerEPUrl>${carbon.protocol}://${carbon.host}:${carbon.management.port}/.well-known/webfinger</OIDCWebFingerEPUrl>
        
        <!-- For tenants below urls will be modified as https://<hostname>:<port>/t/<tenant domain>/<path>-->
        <OAuth2DCREPUrl>${carbon.protocol}://${carbon.host}:${carbon.management.port}/identity/connect/register</OAuth2DCREPUrl>
        <OAuth2JWKSPage>${carbon.protocol}://${carbon.host}:${carbon.management.port}/oauth2/jwks</OAuth2JWKSPage>
        <OIDCDiscoveryEPUrl>${carbon.protocol}://${carbon.host}:${carbon.management.port}/oauth2/oidcdiscovery</OIDCDiscoveryEPUrl>

        Add the following property under the <SSOService> tag.

        Code Block
        <!--<SAMLSSOAssertionBuilder>org.wso2.carbon.identity.sso.saml.builders.assertion.ExtendedDefaultAssertionBuilder</SAMLSSOAssertionBuilder>-->

        Add the following properties at the top level.

        Expand
        titleClick here to view the properties...
        Code Block
        <!--Recovery>
                <Notification>
                    <Password>
                        <Enable>false</Enable>
                    </Password>
                    <Username>
                        <Enable>false</Enable>
                    </Username>
                    <InternallyManage>true</InternallyManage>
                </Notification>
                <Question>
                    <Password>
                        <Enable>false</Enable>
                        <NotifyStart>true</NotifyStart>
                        <Separator>!</Separator>
                        <MinAnswers>2</MinAnswers>
                        <ReCaptcha>
                            <Enable>true</Enable>
                            <MaxFailedAttempts>3</MaxFailedAttempts>
                        </ReCaptcha>
                    </Password>
                </Question>
                <ExpiryTime>3</ExpiryTime>
                <NotifySuccess>true</NotifySuccess>
                <AdminPasswordReset>
                    <Offline>false</Offline>
                    <OTP>false</OTP>
                    <RecoveryLink>false</RecoveryLink>
                </AdminPasswordReset>
            </Recovery>
        
            <EmailVerification>
                <Enable>false</Enable>
                <LockOnCreation>false</LockOnCreation>
                <Notification>
                    <InternallyManage>true</InternallyManage>
                </Notification>
            </EmailVerification>
        
        	<SelfRegistration>
            <Enable>false</Enable>
            <LockOnCreation>false</LockOnCreation>
            <Notification>
                <InternallyManage>true</InternallyManage>
            </Notification>
            <ReCaptcha>false</ReCaptcha>
            </SelfRegistration-->

        Remove the following section:

        Code Block
        <ISAnalytics>
                <DefaultValues>
                    <userName>NOT_AVAILABLE</userName>
                    <userStoreDomain>NOT_AVAILABLE</userStoreDomain>
                    <rolesCommaSeperated>NOT_AVAILABLE</rolesCommaSeperated>
                    <serviceprovider>NOT_AVAILABLE</serviceprovider>
                    <identityProvider>NOT_AVAILABLE</identityProvider>
                </DefaultValues>
            </ISAnalytics>

        Add the following properties to the top level.

        Expand
        titleClick here to view the properties...
        Code Block
        <ResourceAccessControl>
                <Resource context="(.*)/api/identity/user/(.*)" secured="true" http-method="all"/>
                <Resource context="(.*)/api/identity/recovery/(.*)" secured="true" http-method="all"/>
                <Resource context="(.*)/.well-known(.*)" secured="true" http-method="all"/>
                <Resource context="(.*)/identity/register(.*)" secured="true" http-method="all">
                    <Permissions>/permission/admin/manage/identity/applicationmgt/delete</Permissions>
                </Resource>
                <Resource context="(.*)/identity/connect/register(.*)" secured="true" http-method="all">
                    <Permissions>/permission/admin/manage/identity/applicationmgt/create</Permissions>
                </Resource>
                <Resource context="(.*)/oauth2/introspect(.*)" secured="true" http-method="all">
                    <Permissions>/permission/admin/manage/identity/applicationmgt/view</Permissions>
                </Resource>
                <Resource context="(.*)/api/identity/entitlement/(.*)" secured="true" http-method="all">
                    <Permissions>/permission/admin/manage/identity/pep</Permissions>
                </Resource>
            </ResourceAccessControl>
        
            <ClientAppAuthentication>
                <Application name="dashboard" hash="66cd9688a2ae068244ea01e70f0e230f5623b7fa4cdecb65070a09ec06452262"/>
            </ClientAppAuthentication>
        
            <TenantContextsToRewrite>
                <WebApp>
                    <Context>/api/identity/user/v0.9</Context>
                    <Context>/api/identity/recovery/v0.9</Context>
                    <Context>/oauth2</Context>
                    <Context>/api/identity/entitlement</Context>
                </WebApp>
                <Servlet>
                    <Context>/identity/(.*)</Context>
                </Servlet>
            </TenantContextsToRewrite>
        The web.xml file stored in the <PRODUCT_HOME>/repository/conf/tomcat/carbon/WEB_INF directory.Optional

        Add the following properties after the CsrfGuardHttpSessionListener.

        Code Block
        <filter>
              <filter-name>CaptchaFilter</filter-name>
              <filter-class>org.wso2.carbon.identity.captcha.filter.CaptchaFilter</filter-class>
            </filter>
        
            <filter-mapping>
              <filter-name>CaptchaFilter</filter-name>
              <url-pattern>/samlsso</url-pattern>
              <url-pattern>/oauth2</url-pattern>
              <url-pattern>/commonauth</url-pattern>
              <dispatcher>FORWARD</dispatcher>
              <dispatcher>REQUEST</dispatcher>
            </filter-mapping>
        The catalina-server.xml file stored in the <PRODUCT_HOME>/repository/conf/tomcat/ directory.Mandatory

        Add the following valves under the <Host> tag.

        Code Block
        <!-- Authentication and Authorization valve for the rest apis and we can configure context for this in identity.xml  -->
                        <Valve className="org.wso2.carbon.identity.auth.valve.AuthenticationValve"/>
                        <Valve className="org.wso2.carbon.identity.authz.valve.AuthorizationValve"/>
                        <Valve className="org.wso2.carbon.identity.context.rewrite.valve.TenantContextRewriteValve"/>
        The carbonxml file stored in the <PRODUCT_HOME>/repository/conf/ directory.Optional

        Add the following properties after the </Security> tag.

        Code Block
        <HideMenuItemIds>
        <HideMenuItemId>identity_mgt_emailtemplate_menu</HideMenuItemId>
        <HideMenuItemId>identity_security_questions_menu</HideMenuItemId>
        </HideMenuItemIds>
        The log4j.properties file stored in the <PRODUCT_HOME>/repository/conf/ directory.Optional

        Add the following property.

        Code Block
        log4j.logger.org.springframework=WARN
        The data-agent-config.xml filestored in the <NEW_IS_HOME>/repository/conf/data-bridge directory.Mandatory

        Add the following properties under the <Agent> ThriftDataEndpoint and under the <Agent>BinaryDataEndpoint tags.

        Code Block
        <!--<sslEnabledProtocols>TLSv1,TLSv1.1,TLSv1.2</sslEnabledProtocols>-->
        <!--<ciphers>SSL_RSA_WITH_RC4_128_MD5,SSL_RSA_WITH_RC4_128_SHA,TLS_RSA_WITH_AES
        _128_CBC_SHA,TLS_DHE_RSA_WITH_AES_128_CBC_SHA,TLS_DHE_DSS_WITH_AES_128_CBC_SHA,SSL
        _RSA_WITH_3DES_EDE_CBC_SHA,SSL_DHE_RSA_WITH_3DES_EDE_CBC_SHA,SSL_DHE_DSS_WITH_
        3DES_EDE_CBC_SHA</ciphers>-->
        Theclaim-config.xml file stored in the <NEW_IS_HOME>/repository/conf/ directoryMandatory

        Replace the following attribute found under the <Claim> <ClaimURI>http://wso2.org/claims/locality> tag.

        Code Block
        Replace this attribute:
        <AttributeID>localityName</AttributeID>
         
        with this:
        <AttributeID>local</AttributeID>

        Modify the following claims as follows.

        Expand
        titleClick here to see the modified claims...
        Code Block
        <Claim>
          <ClaimURI>http://wso2.org/claims/userid</ClaimURI>
          <DisplayName>User ID</DisplayName>
          <AttributeID>scimId</AttributeID>
          <Description>Unique ID of the user</Description>
          <ReadOnly/>
        </Claim>
        <Claim>
          <ClaimURI>http://wso2.org/claims/externalid</ClaimURI>
          <DisplayName>External User ID</DisplayName>
          <AttributeID>externalId</AttributeID>
          <Description>Unique ID of the user used in external systems</Description>
          <ReadOnly/>
        </Claim>
        <Claim>
          <ClaimURI>http://wso2.org/claims/created</ClaimURI>
          <DisplayName>Created Time</DisplayName>
          <AttributeID>createdDate</AttributeID>
          <Description>Created timestamp of the user</Description>
          <ReadOnly/>
        </Claim>
        <Claim>
          <ClaimURI>http://wso2.org/claims/modified</ClaimURI>
          <DisplayName>Last Modified Time</DisplayName>
          <AttributeID>lastModifiedDate</AttributeID>
          <Description>Last Modified timestamp of the user</Description>
          <ReadOnly/>
        </Claim>
        <Claim>
          <ClaimURI>http://wso2.org/claims/location</ClaimURI>
          <DisplayName>Location</DisplayName>
          <AttributeID>location</AttributeID>
          <Description>Location</Description>
        </Claim>
        <Claim>
          <ClaimURI>http://wso2.org/claims/formattedName</ClaimURI>
          <DisplayName>Name - Formatted Name</DisplayName>
          <AttributeID>formattedName</AttributeID>
          <Description>Formatted Name</Description>
        </Claim>
        <Claim>
          <ClaimURI>http://wso2.org/claims/middleName</ClaimURI>
          <DisplayName>Middle Name</DisplayName>
          <AttributeID>middleName</AttributeID>
          <Description>Middle Name</Description>
        </Claim>
        <Claim>
          <ClaimURI>http://wso2.org/claims/honorificPrefix</ClaimURI>
          <DisplayName>Name - Honoric Prefix</DisplayName>
          <AttributeID>honoricPrefix</AttributeID>
          <Description>Honoric Prefix</Description>
        </Claim>
        <Claim>
          <ClaimURI>http://wso2.org/claims/honorificSuffix</ClaimURI>
          <DisplayName>Name - Honoric Suffix</DisplayName>
          <AttributeID>honoricSuffix</AttributeID>
          <Description>Honoric Suffix</Description>
        </Claim>
        <Claim>
          <ClaimURI>http://wso2.org/claims/userType</ClaimURI>
          <DisplayName>User Type</DisplayName>
          <AttributeID>userType</AttributeID>
          <Description>User Type</Description>
        </Claim>
        <Claim>
          <ClaimURI>http://wso2.org/claims/preferredLanguage</ClaimURI>
          <DisplayName>Preferred Language</DisplayName>
          <AttributeID>preferredLanguage</AttributeID>
          <Description>Preferred Language</Description>
        </Claim>
        <Claim>
          <ClaimURI>http://wso2.org/claims/local</ClaimURI>
          <DisplayName>Local</DisplayName>
          <AttributeID>local</AttributeID>
          <Description>Local</Description>
        </Claim>
        <Claim>
          <ClaimURI>http://wso2.org/claims/timeZone</ClaimURI>
          <DisplayName>Time Zone</DisplayName>
          <AttributeID>timeZone</AttributeID>
          <Description>Time Zone</Description>
        </Claim>
        <Claim>
          <ClaimURI>http://wso2.org/claims/emails.work</ClaimURI>
          <DisplayName>Emails - Work Email</DisplayName>
          <AttributeID>workEmail</AttributeID>
          <Description>Work Email</Description>
        </Claim>
        <Claim>
          <ClaimURI>http://wso2.org/claims/emails.home</ClaimURI>
          <DisplayName>Emails - Home Email</DisplayName>
          <AttributeID>homeEmail</AttributeID>
          <Description>Home Email</Description>
        </Claim>
        <Claim>
          <ClaimURI>http://wso2.org/claims/emails.other</ClaimURI>
          <DisplayName>Emails - Other Email</DisplayName>
          <AttributeID>otherEmail</AttributeID>
          <Description>Other Email</Description>
        </Claim>
        <Claim>
          <ClaimURI>http://wso2.org/claims/phoneNumbers</ClaimURI>
          <DisplayName>Phone Numbers</DisplayName>
          <AttributeID>phoneNumbers</AttributeID>
          <Description>Phone Numbers</Description>
          <RegEx>^([a-zA-Z0-9_\.\-])+\@(([a-zA-Z0-9\-])+\.)+([a-zA-Z0-9]{2,4})+$</RegEx>
        </Claim>
        <Claim>
          <ClaimURI>http://wso2.org/claims/phoneNumbers.home</ClaimURI>
          <DisplayName>Phone Numbers - Home Phone Number</DisplayName>
          <AttributeID>homePhone</AttributeID>
          <Description>Home Phone</Description>
        </Claim>
        <Claim>
          <ClaimURI>http://wso2.org/claims/phoneNumbers.work</ClaimURI>
          <DisplayName>Phone Numbers - Work Phone Number</DisplayName>
          <AttributeID>workPhone</AttributeID>
          <Description>Work Phone</Description>
        </Claim>
        <Claim>
          <ClaimURI>http://wso2.org/claims/phoneNumbers.fax</ClaimURI>
          <DisplayName>Phone Numbers - Fax Number</DisplayName>
          <AttributeID>fax</AttributeID>
          <Description>Fax Number</Description>
        </Claim>
        <Claim>
          <ClaimURI>http://wso2.org/claims/phoneNumbers.pager</ClaimURI>
          <DisplayName>Phone Numbers - Pager Number</DisplayName>
          <AttributeID>pager</AttributeID>
          <Description>Pager Number</Description>
        </Claim>
        <Claim>
          <ClaimURI>http://wso2.org/claims/phoneNumbers.other</ClaimURI>
          <DisplayName>Phone Numbers - Other</DisplayName>
          <AttributeID>otherPhoneNumber</AttributeID>
          <Description>Other Phone Number</Description>
        </Claim>
        <Claim>
          <ClaimURI>http://wso2.org/claims/gtalk</ClaimURI>
          <DisplayName>IM - Gtalk</DisplayName>
          <AttributeID>imGtalk</AttributeID>
          <Description>IM - Gtalk</Description>
        </Claim>
        <Claim>
          <ClaimURI>http://wso2.org/claims/skype</ClaimURI>
          <DisplayName>IM - Skype</DisplayName>
          <AttributeID>imSkype</AttributeID>
          <Description>IM - Skype</Description>
        </Claim>
        <Claim>
          <ClaimURI>http://wso2.org/claims/photos</ClaimURI>
          <DisplayName>Photo</DisplayName>
          <AttributeID>photos</AttributeID>
          <Description>Photo</Description>
        </Claim>
        <Claim>
          <ClaimURI>http://wso2.org/claims/photourl</ClaimURI>
          <DisplayName>Photo URIL</DisplayName>
          <AttributeID>photoUrl</AttributeID>
          <Description>Photo URL</Description>
        </Claim>
        <Claim>
          <ClaimURI>http://wso2.org/claims/thumbnail</ClaimURI>
          <DisplayName>Photo - Thumbnail</DisplayName>
          <AttributeID>thumbnail</AttributeID>
          <Description>Photo - Thumbnail</Description>
        </Claim>
        <Claim>
          <ClaimURI>http://wso2.org/claims/addresses</ClaimURI>
          <DisplayName>Address</DisplayName>
          <AttributeID>addresses</AttributeID>
          <Description>Address</Description>
        </Claim>
        <Claim>
          <ClaimURI>http://wso2.org/claims/addresses.formatted</ClaimURI>
          <DisplayName>Address - Formatted</DisplayName>
          <AttributeID>formattedAddress</AttributeID>
          <Description>Address - Formatted</Description>
        </Claim>
        <Claim>
          <ClaimURI>http://wso2.org/claims/streetaddress</ClaimURI>
          <DisplayName>Address - Street</DisplayName>
          <AttributeID>streetAddress</AttributeID>
          <Description>Address - Street</Description>
          <DisplayOrder>5</DisplayOrder>
        </Claim>
        <Claim>
          <ClaimURI>http://wso2.org/claims/addresses.locality</ClaimURI>
          <DisplayName>Address - Locality</DisplayName>
          <AttributeID>localityAddress</AttributeID>
          <Description>Address - Locality</Description>
        </Claim>
        <Claim>
          <ClaimURI>http://wso2.org/claims/groups</ClaimURI>
          <DisplayName>Groups</DisplayName>
          <AttributeID>groups</AttributeID>
          <Description>Groups</Description>
        </Claim>
        <Claim>
          <ClaimURI>http://wso2.org/claims/identity/verifyEmail</ClaimURI>
          <DisplayName>Verify Email</DisplayName>
          <AttributeID>manager</AttributeID>
          <Description>Temporary claim to invoke email verified feature</Description>
        </Claim>
        <Claim>
          <ClaimURI>http://wso2.org/claims/identity/askPassword</ClaimURI>
          <DisplayName>Ask Password</DisplayName>
          <AttributeID>postOfficeBox</AttributeID>
          <Description>Temporary claim to invoke email ask Password feature</Description>
        </Claim>
        <Claim>
          <ClaimURI>http://wso2.org/claims/identity/adminForcedPasswordReset</ClaimURI>
          <DisplayName>Force Password Reset</DisplayName>
          <AttributeID>departmentNumber</AttributeID>
          <Description>Temporary claim to invoke email force password feature</Description>
        </Claim>
        <Claim>
          <ClaimURI>http://wso2.org/claims/entitlements</ClaimURI>
          <DisplayName>Entitlements</DisplayName>
          <AttributeID>entitlements</AttributeID>
          <Description>Entitlements</Description>
        </Claim>
        <Claim>
          <ClaimURI>urn:scim:schemas:core:1.0:roles</ClaimURI>
          <DisplayName>Roles</DisplayName>
          <AttributeID>roles</AttributeID>
          <Description>Roles</Description>
          <DisplayOrder>5</DisplayOrder>
          <SupportedByDefault />
          <MappedLocalClaim>http://wso2.org/claims/role</MappedLocalClaim>
        </Claim>
        <Claim>
          <ClaimURI>http://wso2.org/claims/x509Certificates</ClaimURI>
          <DisplayName>X509Certificates</DisplayName>
          <AttributeID>x509Certificates</AttributeID>
          <Description>X509Certificates</Description>
        </Claim>
        <Claim>
          <ClaimURI>http://wso2.org/claims/identity/failedPasswordRecoveryAttempts</ClaimURI>
          <DisplayName>Failed Password Recovery Attempts</DisplayName>
          <AttributeID>postalCode</AttributeID>
          <Description>Number of consecutive failed attempts done for password recovery</Description>
        </Claim>
        <Claim>
          <ClaimURI>http://wso2.org/claims/identity/emailVerified</ClaimURI>
          <DisplayName>Email Verified</DisplayName>
          <!-- Proper attribute Id in your user store must be configured for this -->
          <AttributeID>postalAddress</AttributeID>
          <Description>Email Verified</Description>
        </Claim>
        <Claim>
          <ClaimURI>http://wso2.org/claims/identity/failedLoginLockoutCount</ClaimURI>
          <DisplayName>Failed Lockout Count</DisplayName>
          <!-- Proper attribute Id in your user store must be configured for this -->
          <AttributeID>employeeNumber</AttributeID>
          <Description>Failed Lockout Count</Description>
        </Claim>

        Remove the following claim.

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

        Add the following claim.

        Code Block
        <ClaimURI>http://wso2.org/claims/identity/lastLogonTime</ClaimURI>
        <DisplayName>Last Logon</DisplayName>
        <!-- Proper attribute Id in your user store must be configured for this -->
        <AttributeID>carLicense</AttributeID>
        <Description>Last Logon Time</Description>
        </Claim>

        Replace the following attribute from under the <Claim> <ClaimURI> http://wso2.org/claims/challengeQuestion1 </ClaimURI> tag.


        Code Block
        Replace this attribute:
        <AttributeID>localityName</AttributeID>
         
        with this:
        <AttributeID>firstChallenge</AttributeID>

        Replace the following attribute from under the the <Claim> <ClaimURI> http://wso2.org/claims/challengeQuestion2 </ClaimURI>


        Code Block
        Replace this attribute:
        <AttributeID>localityName</AttributeID>
         
        with this:
        <AttributeID>secondChallenge</AttributeID>

        Modify this claim as follows:

        Code Block
        <Claim>
          <ClaimURI>http://wso2.org/claims/active</ClaimURI>
          <DisplayName>Active</DisplayName>
          <AttributeID>active</AttributeID>
          <Description>Status of the account</Description>
        </Claim>
      5. Proceed to step 11 to run the migration client.

        Note

        Note: Note that if you followed this approach for migration, the migration client will map all claims to a local claim in the wso2 claims dialect. This is done by matching the attribute IDs. If there is a claim with no matching attribute ID, the migration client will create a new local claim to create the association.

        For example:

        If the following two claims were mapped in WSO2 IS 5.2.0, the migration client may not identify this because the attribute IDs are different.

        Code Block
        <Dialect dialectURI="http://wso2.org/claims">
            <ClaimURI>http://wso2.org/claims/streetaddress</ClaimURI>
            <DisplayName>Address</DisplayName>
            <AttributeID>streetAddress</AttributeID>
        
        <Dialect dialectURI="http://wso2.org/oidc/claim">
             <ClaimURI>street_address</ClaimURI>
             <DisplayName>Street Address</DisplayName>
             <AttributeID>street</AttributeID>

        As a result, the migration client will create a new local claim like "http://wso2.org/claims/migration__street__73622 " and map the OIDC claim to the new local claim.

      Anchor
      step11
      step11

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

...