

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 APIM 3.2.0 to 4.0.0 when WSO2 Identity Server (WSO2 IS) is the Key Manager in the pre-migrated setup.

Note

You can follow the below information in the situation where you are currently using a WSO2 IS 5.10.0 vanilla distribution that has WSO2 API Management related Key Manager features installed on top of it.
WSO2 API-M 4.0.0 supports WSO2 IS 5.11.0 as its resident key manager.

Step 1 - Upgrade IS as Key Manager 5.10.0 to IS 5.11.0
Step 2 - Upgrade API Manager 3.2.0 to 4.0.0

Step 1 - Upgrade IS as Key Manager 5.10.0 to IS 5.11.0¶

Step A - Setup IS 5.11.0 as a Key Manager
Step B - Migrate IS from 5.10.0 to 5.11.0

Step A - Setup IS 5.11.0 as a Key Manager¶

Download and install WSO2 IS 5.11.0 distribution from here. If you have downloaded the archive, extract it. <IS_HOME> refers to the root folder of the extracted WSO2 IS.

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

[event_listener.properties]
notification_endpoint = "https://localhost:9443/internal/data/v1/notify"
username = "${admin.username}"
password = "${admin.password}"
'header.X-WSO2-KEY-MANAGER' = "WSO2IS"

[[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/"]

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.2.10.jar
- wso2is.notification.event.handlers_1.2.10.jar
Add keymanager-operations.war from the extracted distribution to the <IS_HOME>/repository/deployment/server/webapps directory.

Step B - Migrate IS from 5.10.0 to 5.11.0¶

Follow Step 2 and 3 under Step 2 - Upgrade API Manager to 4.0.0 to backup and upgrade the WSO2 API-M WSO2AM_DB from 3.2.0 to 4.0.0. This will be used as the identity_db in IS 5.11.0.
Follow the guidelines in WSO2 IS 5.11.0 migration guide to migrate your current IS as KM 5.10.0 distribution to IS 5.11.0.
Important

When following the instructions in Migrating the configurations section 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 old WSO2AM_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.
```
#[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"
```
  Instead, add the following to the <IS_HOME>/repository/conf/deployment.toml in IS 5.11.0
```
[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.
Important

Follow Step 10 Part (d) of IS 5.11 migration guide only if you have enabled Symmetric Key Encryption in the previous IS as KM setup. If not, that step can be skipped.
Important

Before executing the IS migration client according to Step 11 of IS 5.11 migration guide, keep in mind to remove the following entries from migration-config.yaml in the migration-resources directory.
```
- version: "5.10.0"
    migratorConfigs:
    -
        name: "MigrationValidator"
        order: 2
    -
        name: "SchemaMigrator"
        order: 5
        parameters:
        location: "step2"
        schema: "identity"
    -
        name: "TenantPortalMigrator"
        order: 11
```
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 2 - Upgrade API Manager 3.2.0 to 4.0.0¶

Follow the steps mentioned in Upgrading API-M from 3.2.0 to 4.0.0 to upgrade your API-M environment from 3.2.0 to 4.0.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.0.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.
When following guidelines under Step 2 - Upgrade API Manager to 4.0.0, make sure you SKIP the following steps.
- Step 3 to upgrade the WSO2AM_DB from 3.2.0 to 4.0.0. You have already done this in Step 1 of Step A - Setup IS 5.11.0 as a Key Manager.
- Step 5 to upgrade identity component in API-M from 5.10.0 to 5.11.0. You have already done this in Step 2 of Step A - Setup IS 5.11.0 as a Key Manager.
After configuring WSO2 IS 5.11.0 as the Resident Key Manager and before starting the API-M 4.0.0 server for the first time in Step 5 under Step 2 - Upgrade API Manager to 4.0.0, make sure you have already started WSO2 IS 5.11.0.

Info

If you want to use the latest user store, please update both the <IS_HOME>/repository/conf/deployment.toml and <API-M_HOME>/repository/conf/deployment.toml as follows after the migration.

[user_store]
type = "database_unique_id"

Top