Set up MWARE IAM as a Key Manager

Follow the instructions below to configure MWARE IAM (MWARE IAM) as the Key Manager of the MWARE ESB deployment globally.

Step 1 - Download and install MWARE IAM

Download and install MWARE IAM 6.0.0 or 6.1.0. If you downloaded the archive, extract it. <IS_HOME> refers to the root folder of the extracted MWARE IAM.

It is assumed that you have already downloaded MWARE ESB. <APIM_HOME> refers to the root folder of the unzipped MWARE ESB pack.

Step 2 - Optionally, configure port offset for MWARE IAM

Note

This is only required if you are running both MWARE ESB and MWARE IAM on the same Virtual Machine (VM). For more information, see Changing the Default Ports with Offset.

Open the <IS_HOME>/repository/conf/deployment.toml file and change the offset to 1 by applying the following configuration as follows:

[server]
offset = 1

This increments the product's default port by one.

Step 3 - Install and configure the databases

You can create the required databases for the API-M deployment on a separate server and point to the databases from the respective nodes.

The following diagram depicts how the databases are shared between MWARE IAM and MWARE ESB.

IS-AS-KM-DBS

  • WSO2SHARED_DB - This database contains the registry and user management data.

Follow the instructions below to set up and configure the databases for the MWARE IAM as the Key Manager node:

  1. Install, setup, and configure WSO2_SHARED_DB databases as illustrated in Changing the Default Databases.

    This particular guide provides you all the steps on how to install the database, set up database users, create tables using relevant scripts, apply the drivers that are compatible with the database type, and configure the connection details in the connection data in the <IS_HOME>/repository/conf/deployment.toml file.

    This step is needed if a shared user store has to be used among the servers.

    Warning

    If you have already created and set up the database (WSO2_SHARED_DB) for MWARE ESB, you only need to configure the data source configurations in the MWARE IAM node for it to connect with the required databases and act as the Key Manager.

  2. Share WSO2_SHARED_DBwith MWARE IAM.

    You need to define the following configuration in the <IS_HOME>/repository/conf/deployment.toml file. Sample configurations for MySQL have been provided.

    
 [database.shared_db]
 type = "mysql"
 url = "jdbc:mysql://<database-host>:3306/<WSO2_SHARED_DB>"
 username = "<db_username>"
 password = "<db_password>"
    
 [database.shared_db]
 type = "mysql"
 url = "jdbc:mysql://localhost:3306/shared_db"
 username = "umadmin"
 password = "umadmin"

  3. If multi-tenancy is used, you need to share the WSO2AM_DB with the Identity Server.

    You need to define the following configuration in the <IS_HOME>/repository/conf/deployment.toml file. Sample configurations for MySQL have been provided.

    Note

    If you are using Identity Server in an HA setup and not using multi-tenancy, create an identity database and share the [database.identity_db] db between the two IS nodes.

     [database.identity_db]
 type = "mysql"
 url = "jdbc:mysql://<database-host>:3306/<WSO2AM_DB>?useSSL=false"
 username = "wso2carbon"
 password = "wso2carbon"
     [database.identity_db]
 type = "mysql"
 url = "jdbc:mysql://localhost:3306/apim_db?useSSL=false"
 username = "wso2carbon"
 password = "wso2carbon"

  4. Share WSO2_SHARED_DB with MWARE ESB.

    Define the same datasource configurations that were mentioned in step 3.2 for WSO2_SHARED_DB in the <APIM_HOME>/repository/conf/deployment.toml file.

    [database.shared_db]
type = "mysql"
url = "jdbc:mysql://<database-host>:3306/<WSO2_SHARED_DB>"
username = "<db_username>"
password = "<db_password>"
    [database.shared_db]
type = "mysql"
url = "jdbc:mysql://localhost:3306/shared_db"
username = "umadmin"
password = "umadmin"

  5. Share WSO2AM-DB with MWARE ESB.

    Define the datasource configurations for WSO2AM-DB in the <APIM_HOME>/repository/conf/deployment.toml file. 

    
[database.apim_db]
type = "mysql"
url = "jdbc:mysql://<database-host>:3306/<WSO2AM_DB>"
username = "<db_username>"
password = "<db_password>"
    
[database.apim_db]
type = "mysql"
url = "jdbc:mysql://localhost:3306/apim_db"
username = "amadmin"
password = "amadmin"

Step 4 - Configure MWARE IAM with MWARE ESB

  1. Download the MWARE IAM Connector.

  2. Extract the distribution and copy the following JAR files, which are in the <wso2is-extensions-1.6.8>/dropins directory, to the <IS_HOME>/repository/components/dropins directory.

    • wso2is.key.manager.core-1.6.8.jar
    • wso2is.notification.event.handlers-1.6.8.jar

  3. Add the keymanager-operations.war, which is in the <wso2is-extensions-1.6.8>/webapps directory, to the <IS_HOME>/repository/deployment/server/webapps directory.

  4. Configure the Traffic Manager endpoints.

    Add the following configuration in the <IS_HOME>/repository/conf/deployment.toml file.

    [[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 = "DELETE"
permissions = "/permission/admin/manage/identity/applicationmgt/delete"
scopes = "internal_application_mgt_delete"

[[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 = "POST"
permissions = "/permission/admin/manage/identity/applicationmgt/update"
scopes = "internal_application_mgt_update"

[tenant_context.rewrite]
custom_webapps = ["/keymanager-operations/"]

  5. Configure the event listener endpoint to publish controller events to the Control Plane.

    
[event_listener.properties]
notification_endpoint = "https://<control-plane-host>:<control-plane-https-port>/internal/data/v1/notify"
username = "${admin.username}"
password = "${admin.password}"
'header.X-WSO2-KEY-MANAGER' = "WSO2-IS"
    
[event_listener.properties]
notification_endpoint = "https://<cp.wso2.com>:9443/internal/data/v1/notify"
username = "${admin.username}"
password = "${admin.password}"
'header.X-WSO2-KEY-MANAGER' = "WSO2-IS"

  6. Add the following configuration in the <IS_HOME>/repository/conf/deployment.toml file to change the default encryption type and remove the keystore.primary configuration. 

    [keystore]
userstore_password_encryption = "InternalKeyStore"

[system.parameter]
"org.wso2.CipherTransformation" = "RSA/ECB/OAEPwithSHA1andMGF1Padding"

[encryption]
internal_crypto_provider = "org.wso2.carbon.crypto.provider.KeyStoreBasedInternalCryptoProvider"

  7. If you wish to encrypt the OAuth2 Keys (access tokens, client secrets, and authorization codes), follow the steps given in Encrypting OAuth Keys, which is in the MWARE IAM 5.10.0 documentation, and apply the relevant configurations in the <IS_HOME>/repository/conf/deployment.toml file to enable the feature.

  8. If you are using the existing keystore and truststore (with self signed certificate) shipped by default with the product distributions, replace the keystore in <IS_HOME>/repository/resources/security/wso2carbon.jks and trustore in <IS_HOME>/repository/resources/security/client-truststore.jks with the `<APIM_HOME>/repository/resources/security/wso2carbon.jks and <APIM_HOME>/repository/resources/security/client-truststore.jks respectively. Make sure to follow this step before starting either of the servers for the first time. (Please note that in a production environment, it is not recommended to use the default keystores. Instead, it is recommended to create new keystores with new keys and certificates.)

Step 5 - Configure MWARE ESB with the MWARE IAM

  1. By default, MWARE ESB and MWARE IAM come with a JDBC User Store as the primary userstore. If you wish to use any other type of user store (e.g., LDAP, Active Directory, etc.) in MWARE IAM, it has to be configured in the ESB nodes. For more information, see Configuring the Primary User Store and apply the relevant configs to plug in a new user store.

    Add below configuration in <APIM_HOME>/repository/conf/deployment.toml

       [apim.key_manager]
   service_url = "https://localhost:9444/services/"
   type = "WSO2-IS"

  2. The token exchange grant type is enabled by default in MWARE ESB 4.1.0 onwards. But the corresponding grant type is currently not supported by the MWARE IAM. You need to modify the [oauth.grant_type.token_exchange] config in the <APIM_HOME>/repository/conf/deployment.toml file as follows. 

    [oauth.grant_type.token_exchange]
enable = false
allow_refresh_tokens = true
iat_validity_period = "1h"

Step 6 - Optionally, configure High Availability (HA) for the Identity Server

Warning

These steps are ONLY applicable if you need to configure HA for the Key Manager.

  1. Make a copy of the active instance configured above and use this copy as the second Key Manager active instance.

  2. Configure a Load Balancer to front the two MWARE IAM nodes.

Step 7 - Start the Identity Server(s)

Start MWARE IAM for the changes to take effect. For more information, see Running the Product in the MWARE IAM documentation.

  • Linux/Mac OS 

    cd <IS_KM_HOME>>/bin/
sh wso2server.sh

  • Windows 

    cd <IS_KM_HOME>>\bin\    
wso2server.bat

    Troubleshooting

    If you have configured the hostnames for MWARE ESB and MWARE IAM, during the server startup, you will see the following warning in the MWARE ESB backend logs.

    WARN {org.wso2.carbon.apimgt.gateway.throttling.util.BlockingConditionRetriever} -  Failed retrieving Blocking Conditions from remote endpoint: sun.security.validator.ValidatorException: PKIX path building failed: sun.security.provider.certpath.SunCertPathBuilderException: unable to find valid certification path to requested target. Retrying after 15 seconds... {org.wso2.carbon.apimgt.gateway.throttling.util.BlockingConditionRetriever}

    The reason for this is that the default certificates that come with the ESB servers are created for localhost. Therefore, when MWARE ESB boots up, it makes an HTTP call to a webapp that is in the Key Manager (throttle data at KM_URL/internal/data/v1/keyTemplates). Thereafter, MWARE ESB decides the URL of the Key Manager based on the URL that is configured in the deployment.toml, which is localhost.

    To overcome this issue, you need to create self-signed certificates for MWARE ESB and MWARE IAM hostnames. Then import the public certificates of MWARE ESB to the trust-store.jks of MWARE IAM and vice versa. This should resolve the SSL handshake failure.

Follow the instructions below to configure the other MWARE ESB components, namely the Publisher, Developer Portal, Traffic Manager, and Gateway:

Top