Upgrading WSO2 IS as Key Manager to 5.11.0¶
The following information describes how to upgrade your WSO2 API Manager (WSO2 API-M) environment from API-M 3.2.0 to 4.1.0 when WSO2 Identity Server (WSO2 IS) is the Key Manager in the pre-migrated setup.
Step A - Upgrade IS as Key Manager 5.10.0 to IS 5.11.0¶
Follow step 1 to step 3 below to upgrade your IS as Key Manager 5.10.0 to IS 5.11.0
Step 1 - Migrate the IS as KM configurations¶
-
Download WSO2 IS 5.11.0 distribution from here and extract it.
<IS_HOME>
refers to the root folder of the extracted WSO2 IS 5.11.0. -
Add following configurations in the
<IS_HOME>/repository/conf/deployment.toml
file.deployment.toml
[[event_listener]] id = "token_revocation" type = "org.wso2.carbon.identity.core.handler.AbstractIdentityHandler" name = "org.wso2.is.notification.ApimOauthEventInterceptor" order = 1 [[resource.access_control]] context = "(.)/keymanager-operations/user-info/claims(.)" secure = true http_method = "GET" permissions = "/permission/admin/manage/identity/usermgt/list" scopes = "internal_user_mgt_list" [[resource.access_control]] context = "(.*)/keymanager-operations/user-info/claims/generate" secure = true http_method = "POST" permissions = "/permission/admin/manage/identity/usermgt/list" scopes = "internal_user_mgt_list" [[resource.access_control]] context = "(.*)/keymanager-operations/dcr/register" secure = true http_method = "POST" permissions = "/permission/admin/manage/identity/applicationmgt/create" scopes = "internal_application_mgt_create" [[resource.access_control]] context = "(.*)/keymanager-operations/dcr/register(.*)" secure = true http_method = "GET" permissions = "/permission/admin/manage/identity/applicationmgt/view" scopes = "internal_application_mgt_view" [[resource.access_control]] context = "(.*)/keymanager-operations/dcr/register(.*)" secure = true http_method = "PUT" permissions = "/permission/admin/manage/identity/applicationmgt/update" scopes = "internal_application_mgt_update" [[resource.access_control]] context = "(.*)/keymanager-operations/dcr/register(.*)" secure = true http_method = "DELETE" permissions = "/permission/admin/manage/identity/applicationmgt/delete" scopes = "internal_application_mgt_delete" [tenant_context.rewrite] custom_webapps = ["/keymanager-operations/"]
-
Configure the event listener endpoint to publish controller events to the Traffic Manager.
[event_listener.properties] notification_endpoint = "https://<tm.wso2.com>:9443/internal/data/v1/notify" username = "${admin.username}" password = "${admin.password}" 'header.X-WSO2-KEY-MANAGER' = "WSO2-IS"
-
IS 5.11.0 uses Symmetric encryption as default and API-M 4.1.0 uses Asymmetric algorithm as default. So when using IS 5.11.0 as KM, if you had used Asymmetric encryption in the previous API-M version, please add below configurations to
deployment.toml
.[keystore] userstore_password_encryption = "InternalKeyStore" [system.parameter] "org.wso2.CipherTransformation"="RSA/ECB/OAEPwithSHA1andMGF1Padding" [encryption] internal_crypto_provider = "org.wso2.carbon.crypto.provider.KeyStoreBasedInternalCryptoProvider"
-
Migrate IS KM 5.10.0 configurations as per the instructions in Migrating the configurations.
Important
When following the instructions of IS 5.11.0 migration guide, make sure to follow the below guidelines as well.
-
Configure the
identity_db
datasource in<IS_HOME>/repository/conf/deployment.toml
of IS 5.11.0 by pointing to the oldWSO2AM_DB
.[database.identity_db] type = "mysql" url = "jdbc:mysql://localhost:3306/am_db" username = "wso2carbon" password = "wso2carbon"
-
If you have used a JDBCUserStoreManager as the userstore in previous IS as KM setup, comment/remove the following from
<IS_HOME>/repository/conf/deployment.toml
in IS 5.11.0.
Instead, add the following to the#[user_store] #type = "read_write_ldap_unique_id" #connection_url = "ldap://localhost:${Ports.EmbeddedLDAP.LDAPServerPort}" #connection_name = "uid=admin,ou=system" #connection_password = "admin" #base_dn = "dc=wso2,dc=org"
<IS_HOME>/repository/conf/deployment.toml
in IS 5.11.0
If the user store type in the previous version is set to[user_store] type = "database_unique_id"
database
instead of defaultdatabase_unique_id
, update<IS_HOME>/repository/conf/deployment.toml
file as follows[user_store] type = "database"
-
If you have used separate DBs for user management and registry in the previous IS as KM version, you need to configure WSO2REG_DB and WSO2USER_DB databases separately in
<IS_HOME>/repository/conf/deployment.toml
of IS 5.11.0 to avoid any issues.[database.shared_db] type = "mysql" url = "jdbc:mysql://localhost:3306/reg_db" username = "wso2carbon" password = "wso2carbon" [database.user] type = "mysql" url = "jdbc:mysql://localhost:3306/um_db" username = "wso2carbon" password = "wso2carbon"
-
If you have used a separate user management database as the primary userstore in previous IS as KM setup, add the following to the
<IS_HOME>/repository/conf/deployment.toml
in IS 5.11.0.[realm_manager] data_source = "WSO2USER_DB"
- You DO NOT NEED to copy the API-M Key Manager specific configurations from
<OLD_IS_KM_HOME>/repository/conf/api-manager.xml
of previous IS as KM version to IS 5.11.0.
-
Step 2 - Migrate the IS as KM Resources¶
-
Download the WSO2 IS Connector.
-
Extract the distribution and copy the following JAR files to the
<IS_HOME>/repository/components/dropins
directory.wso2is.key.manager.core-1.4.2.jar
wso2is.notification.event.handlers_1.4.2.jar
-
Add
keymanager-operations.war
from the extracted distribution to the<IS_HOME>/repository/deployment/server/webapps
directory. -
Follow the steps 1 to 8 in WSO2 IS 5.11.0 migration guide except for step 6 to prepare your current IS as KM 5.10.0 for migration to IS 5.11.0.
Step 3 - Migrate the IS as KM Components¶
-
Make sure you backed up all the databases in API-M 3.2.0
-
Download the identity component migration resources and unzip it in a local directory.
Navigate to the latest release tag and download the
wso2is-migration-x.x.x.zip
under Assets.Let's refer to this directory that you downloaded and extracted as
<IS_MIGRATION_TOOL_HOME>
. -
Copy the
migration-resources
folder from the extracted folder to the<IS_HOME>
directory. -
Open the
migration-config.yaml
file in the migration-resources directory and make sure that thecurrentVersion
element is set to 5.10.0, as shown below.migrationEnable: "true" currentVersion: "5.10.0" migrateVersion: "5.11.0"
-
Remove the following 2 steps from migration-config.yaml which is included under version: "5.10.0"
- version: "5.10.0" migratorConfigs: - name: "MigrationValidator" order: 2 - name: "SchemaMigrator" order: 5 parameters: location: "step2" schema: "identity" - name: "TenantPortalMigrator" order: 11
-
Remove the following 2 steps from migration-config.yaml which is included under version: "5.11.0"
- name: "EncryptionAdminFlowMigrator" order: 1 parameters: currentEncryptionAlgorithm: "RSA/ECB/OAEPwithSHA1andMGF1Padding" migratedEncryptionAlgorithm: "AES/GCM/NoPadding" schema: "identity" - name: "EncryptionUserFlowMigrator" order: 2 parameters: currentEncryptionAlgorithm: "RSA/ECB/OAEPwithSHA1andMGF1Padding" migratedEncryptionAlgorithm: "AES/GCM/NoPadding" schema: "identity"
-
Copy the
org.wso2.carbon.is.migration-x.x.x.jar
from the<IS_MIGRATION_TOOL_HOME>/dropins
directory to the<IS_HOME>/repository/components/dropins
directory.Important
In WSO2 Identity Server 5.11.0, groups include user store roles and roles include internal roles. Therefore, from IS 5.11.0 onwards, we cannot have the same admin role in both primary and internal user domains. If the same admin role exists in both UM domains of your older version, we should add the PRIMARY/admin to the internal domain with a different admin role name during the group role separation. To do that, you have to follow the below steps.
- Add the following configuration to
<IS_HOME>/repository/conf/deployment.toml
file. Rename the admin role with a new role name. This can be any value you prefer.
[super_admin] admin_role = "<NEW-ADMIN-ROLE-NAME>" create_admin_account = false
- Open the
migration-config.yaml
file in the migration-resources directory and add the admin role name of the current version to the parametercurrentAdminRoleName
under theGroupsAndRolesMigrator
. For example, "admin" which is the default admin role name.
name: "GroupsAndRolesMigrator" order: 4 parameters: currentAdminRoleName: "<CURRENT-ADMIN-ROLE_NAME>"
- Add the following configuration to
-
Modify
create_admin_account
to false in<IS_HOME>/repository/conf/deployment.toml
if it is not changed already.[super_admin] create_admin_account = false
-
Start WSO2 IS 5.11.0 as follows to carry out the complete Identity component migration.
sh wso2server.sh -Dmigrate -Dcomponent=identity
wso2server.bat -Dmigrate -Dcomponent=identity
Warning
Depending on the number of records in the identity tables, this identity component migration will take a considerable amount of time to finish. Do NOT stop the server during the migration process and please wait until the migration process finish completely and server get started.
-
After you have successfully completed the migration, stop the server and remove the following files and folders.
-
Remove the
org.wso2.carbon.is.migration-x.x.x.jar
file, which is in the<IS_HOME>/repository/components/dropins
directory. -
Remove the migration-resources directory, which is in the
<IS_HOME>
directory. -
If you ran WSO2 IS as a Windows Service when doing the IS migration , then you need to remove the following parameters in the command line arguments section (CMD_LINE_ARGS) of the
wso2server.bat
file.-Dmigrate -Dcomponent=identity
-
Step B - Upgrade API Manager 3.2.0 to 4.1.0¶
Follow the steps mentioned in Upgrading API-M from 3.2.0 to 4.1.0 to upgrade your API-M environment from 3.2.0 to 4.1.0.
Important
-
When following guidelines under Step 1 - Migrate the API Manager configurations, make sure to add the following to the
<API-M_HOME>/repository/conf/deployment.toml
. This is to configure your IS 5.11.0 as the Resident Key Manager of your API-M 4.1.0 deployment.[apim.key_manager] service_url = "https://<IS_5.11.0_HOST_NAME>:<PORT>/services/" type = "WSO2-IS"
- Do NOT copy anyother Key Manager specific configurations coming from previous API-M version to the latest pointing to the IS instance.
-
SKIP guidelines under Step 3 - Migrate the Identity Components
- You have already done this in Step 3 of Step A - Upgrade IS as Key Manager 5.10.0 to IS 5.11.0.
-
After configuring WSO2 IS 5.11.0 as the Resident Key Manager and before starting the API-M 4.1.0 server for the first time in Step 6 under Step 6 - Restart the WSO2 API-M 4.1.0 Server, make sure you have already started WSO2 IS 5.11.0.