This documentation is for WSO2 Identity Server version 5.2.0. View this page (if available) in the latest documentation or go to the latest version's home page.

||
Skip to end of metadata
Go to start of metadata

The following instructions guide you through upgrading from WSO2 Identity Server 5.1.0 to WSO2 Identity Server 5.2.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.1.0 LDAP user store to IS 5.2.0.

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

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

In this topic, <OLD_IS_HOME> is the directory that Identity Server 5.1.0 resides in and <NEW_IS_HOME> is the directory that Identity Server 5.2.0 resides in.

  1. Download Identity Server 5.2.0 and unzip it in the <NEW_IS_HOME> directory.
  2. Take a backup of the existing database used by Identity Server 5.1.0. This backup is necessary in case the migration causes issues in the existing database.
  3. Make a copy of the <OLD_IS_HOME>/repository/conf folder. 
  4. 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/event-processor.xml
    • repository/conf/security/Owasp.CsrfGuard.Carbon.properties
    • repository/conf/tomcat/carbon/WEB-INF/web.xml
  5. Replace the <NEW_IS_HOME>/repository/conf folder with the modified copy of the <OLD_IS_HOME>/repository/conf folder.

  6. Open the <NEW_IS_HOME>/repository/conf/identity/identity.xml file and add the <PoolSize> tag under the <SessionDataPersist> tag with the default value as 200, if you have not already done so. If <SessionDataPersist> is commented out, be sure to uncomment it.

  7. Replace the <NEW_IS_HOME>/repository/components/dropins folder with a copy of the <OLD_IS_HOME>/repository/components/dropins folder. 
  8. Copy the .jks files from the <OLD_IS_HOME>/repository/resources/security folder and paste them in <NEW_IS_HOME>/repository/resources/security
  9. If you have created tenants in the previous Identity Server copy content in the  <OLD_IS_HOME>/repository/tenants directory to  <NEW_IS_HOME>/repository/tenants/ directory.
  10. If you have created secondary user stores in the previous Identity Server copy content in the <OLD_IS_HOME>/repository/deployment/server/userstores directory to <NEW_IS_HOME>/repository/deployment/server/userstores/ directory
  11. Download the migration resources and unzip it to a local directory. Run the respective migration script against your database. 

    Note: The db scripts add the following new claims and claim mappings to your database. If you have already mapped the carLicense and/or businessCategory attributes to a claim, follow the steps below to update the SQL with a different attribute value.

    1. Open the relevant db script in an editor.

    2. Change the relevant SQL commands to add a suitable attribute.

       SQL for lastLoginTime Claim

      Change the 'carLicense' attribute value to a different attribute that is not mapped to a claim.

      lastLoginTime claim for super tenant
      lastLoginTime claim for migrating tenants
       SQL for lastPasswordUpdateTime Claim

      Change the 'businessCategory' attribute value to a different attribute that is not mapped to a claim.

      lastPasswordUpdateTime claim for super tenant
      lastPasswordUpdateTime claim for migrating tenants
  12. To avoid a known issue related to OpenID Connect requested claims, update WSO2 IS using the WSO2 Update Manager (WUM). To do this, follow the instructions on the Updating WSO2 Products page and update the WSO2 Identity Server using WUM. 

  13. Start the Identity Server 5.2.0 using the appropriate command.
    1. Linux/Unix:

    2. Windows:

Configuration changes in IS 5.2.0 

The table below lists out all the configuration changes from IS 5.1.0 to IS 5.2.0. You can scroll through the table and change the relevant configurations according to the features you are using. 

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

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:

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:

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.

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

The following properties were replaced:

Old configuration

The properties above were replaced with the following:

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

 
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

The following properties were removed:

 

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

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

 

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

Listeners
Properties
 

The security element was updated:

 

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

 Click to see the code block
 

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

 

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

The <CacheConfig> was replaced:

 Click to see the code block
 
  • 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:

The following elements were removed:

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.

  • 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
application-authentication.xml file stored in the <PRODUCT_HOME>/repository/conf/identity/ directory.
 Click to see the code block
metrics.xml file stored in the <PRODUCT_HOME>/repository/conf/ directory.

The following elements were added:

 Click to see the code block
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
registry.xml file stored in the <PRODUCT_HOME>/repository/conf/ directory.

The following elements were added:

 Click to see the code block
user-mgt.xml file stored in the <PRODUCT_HOME>/repository/conf/ directory.

The following LDAP/AD property was added:

  • No labels