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

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

Compare with Current View Page History

« Previous Version 14 Next »

The following instructions guide you through upgrading from WSO2 Identity Server 5.2.0 to WSO2 Identity Server 5.3.0. 

Migrating the embedded LDAP user store

It is not generally recommended to use the embedded LDAP user store that is shipped with WSO2 Identity Server in production setups. However, if migration of the embedded LDAP is required, follow the instructions below to migrate the existing IS 5.2.0 LDAP user store to IS 5.3.0.

  1. Copy the <IS-5.2-Home>/repository/data folder to <IS-5.3-Home/repository/data folder.
  2. Restart the server to save the changes. 

To upgrade the version of WSO2 Identity Server, the user store database should be upgraded. Note that there are no registry schema changes between versions. 

In this topic, <OLD_IS_HOME> is the directory that Identity Server 5.2.0 resides in and <NEW_IS_HOME> is the directory that Identity Server 5.3.0 resides in. Follow the steps below as needed to complete the migration process. .

  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. You can do database migration using the 5.2.0 to 5.3.0 database migration scripts and running the respective migration script on your database. 
  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 folder and paste it in the copy of the <OLD_IS_HOME>/repository/conf directory in the relevant sub folder:
    • repository/conf/identity/CaptchaConfig.properties
    • repository/conf/security/identity/identity-event.properties
  6. Replace the <NEW_IS_HOME>/repository/components/dropins folder with a copy of the <OLD_IS_HOME>/repository/components/dropins folder. 
  7. Copy the .jks files from the <OLD_IS_HOME>/repository/resources/security folder and paste them in <NEW_IS_HOME>/repository/resources/security
  8. If you have created tenants in the previous WSO2 Identity Server version, copy the content in the <OLD_IS_HOME>/repository/tenants directory to the <NEW_IS_HOME>/repository/tenants/ directory.
  9. 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.

  10. 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: Scroll left/right to view the entire table below.

    Mandatory configuration changes: Click here to view the table..

     Configuration Changes: Click here to view the table...
    Configuration FileChanges

    [OPTIONAL]

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

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

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

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

    [MANDATORY]

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

    Add the following property under the <Extensions> tag.

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

    [OPTIONAL]

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

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

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

    [MANDATORY]

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

    Find the following line.

    Old configuration
    org.owasp.csrfguard.unprotected.authiwa=%servletContext%/commonauth/iwa/*

    Update the line as follows.

    New Configuration
    org.owasp.csrfguard.unprotected.oauthiwa=%servletContext%/commonauth/iwa/*

    Add the following property.

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

    [MANDATORY]

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

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

    <Property name="initializeNewClaimManager">true</Property>

    [MANDATORY]

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

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

    For more information about this feature, see Email Templates.

    [OPTIONAL]

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

    Add the following property to the config file.

    <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>
    [MANDATORY] identity.xml file stored in the <PRODUCT_HOME>/repository/conf/identity directory.

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

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

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

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

    Add the following properties at the top level.

    <!--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:

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

    <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>
    [OPTIONAL] web.xml file stored in the <PRODUCT_HOME>/repository/conf/security /tomcat/WEB_INF directory.

    Add the following properties after the CsrfGuardHttpSessionListener.

    <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>
    [OPTIONAL]   catalina-server.xml file stored in the <PRODUCT_HOME>/repository/conf/security /tomcat/ directory.

    Add the following valves under the <Host> tag.

    <!-- 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"/>
    [OPTIONAL]  
    carbon.
    xml file stored in the <PRODUCT_HOME>/repository/conf/ directory.

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

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

    Add the following property.

    log4j.logger.org.springframework=WARN
    [OPTIONAL] 
    captcha-config.properties file stored in the <NEW_IS_HOME>/repository/conf/identity directory.
    This file is newly added in IS 5.3.0. Copy the file from the <NEW_IS_HOME>/repository/conf/identity directory and paste it in the copy of the <OLD_IS_HOME>/repository/conf/identity folder.
    identity-event.properties file stored in the <NEW_IS_HOME>/repository/conf/identity directory.This file is newly added in IS 5.3.0. Copy the file from the <NEW_IS_HOME>/repository/conf/identity directory and paste it in the copy of the <OLD_IS_HOME>/repository/conf/identity folder.

     

     

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

  12. Start the Identity Server 5.3.0 with the following command to perform the data migration. 

      1. Linux/Unix:

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

        wso2server.bat -Dmigrate -Dcomponent=identity 
  13. Once the migration is successful, stop the server and start using the appropriate command.
    1. Linux/Unix:

      sh wso2server.sh
    2. Windows:

      wso2server.bat
  • No labels