

Configuring WSO2 Identity Server as a Key Manager¶

Please follow the steps below to configure a prepackaged WSO2 Identity Server as Key Manager for your WSO2 API Manager deployment.

Info

What is referred to as the prepackaged WSO2 Identity Server as a Key Manager?

The prepackaged WSO2 Identity Server as a Key Manager 5.10.0 is pre-configured to connect with WSO2 API Manager out of the box. Therefore, it is different from the vanilla form of a WSO2 Identity Server 5.10.0 distribution. The prepackaged WSO2 Identity Server as a Key Manager 5.10.0 is compatible with WSO2 API Manager 3.1.0 and supports in-place updates via WUM.

Warning

Before you begin check the product compatibility for WSO2 IS as Key Manager.

Step 1 - Download the prepackaged WSO2 IS as a Key Manager (WSO2 IS-KM)¶

Download the prepackaged WSO2 IS-KM from here or get the wum updated distribution and unzip it. <IS_KM_HOME> will refer to the root folder of the unzipped WSO2 IS-KM pack.
If you have not downloaded WSO2 API Manager, you can download it from here. <APIM_HOME> will refer to the root folder of the unzipped WSO2 API-M pack.

Step 2 - Optionally, configure a port offset for WSO2 IS¶

Note

This step is only required to be followed if you are running both WSO2 API Manager and WSO2 Identity Server on the same Virtual Machine (VM). Please refer Changing the Default Ports with Offset for more information.

This feature is available only as a WUM update and is effective from 20^th April 2020 (2020-04-20).

Open the <IS_KM_HOME>/repository/conf/deployment.toml file.
Change the offset by 1 as shown in the following configuration. This increments the server's default port by one.

[server]
offset = 1

Step 3 - Install and configure the databases¶

Step 3.1 Overview¶

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 WSO2 IS-KM and WSO2 API-M.

WSO2AM_DB - This database stores the identity-related data, API related data as well as OAuth tokens and keys. When serving key-validation requests, the key manager accesses the WSO2AM_DB and validates whether there are subscriptions made by the particular key.
WSO2SHARED_DB - This database contains the registry and user management data.

Step 3.2 Setup and configure the databases for WSO2 IS-KM¶

Follow the steps below to set up and configure the databases for WSO2 IS-KM node.

Open <IS_KM_HOME>/repository/conf/deployment.toml file. Comment out the default database configuration as follows.

#[database.config]
#type = "h2"
#url ="jdbc:h2:./repository/database/WSO2SHARED_DB;DB_CLOSE_ON_EXIT=FALSE;MVCC=TRUE"
#username = "wso2carbon"
#password = "wso2carbon"

Install, setup and configure WSO2AM_DB and WSO2_SHARED_DB databases as explained in Changing the Default Databases. This guide includes instructions on how to install the database, how to set up database users, create tables using relevant scripts, apply the drivers which are compatible with the database type, and how to set up the connection details in the <IS_KM_HOME>/repository/conf/deployment.toml file.

Warning

If you have already created and set up databases(WSO2AM_DB and WSO2_SHARED_DB) for WSO2 API Manager, you will only need to configure the data source configurations in the WSO2 IS-KM node. This will allow the key manager node to connect to the required databases.

Find below a sample configuration of the connection details in the <IS_KM_HOME>/repository/conf/deployment.toml.
Format
```
 [database.apim_db]
 type = "mysql"
 url = "jdbc:mysql://<database-host>:3306/<WSO2AM_DB>"
 username = "<db_username>"
 password = "<db_password>"

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

 [database.shared_db]
 type = "mysql"
 url = "jdbc:mysql://localhost:3306/shared_db"
 username = "regadmin"
 password = "regadmin"
```
Apply the data source configuration (WSO2AM_DB and WSO2_SHARED_DB) done above, to the <APIM_HOME>/repository/conf/deployment.toml of the API-M node as well.

Step 4 - Optionally, configure cache invalidation for WSO2 IS-KM¶

Note

This configuration is required only if it is needed to immediately invalidate the cache within the WSO2 IS-KM nodes via the Traffic manager.

Open the <IS_KM_HOME>/repository/conf/deployment.toml file and add following configuration.

       [apim.cache_invalidation]
       enabled = true
       domain = "keymanager-domain"

Step 5 - Configure the WSO2 IS-KM to connect to WSO2 API-M¶

Step 5.1 Configure the key manager (WSO2 IS-KM) to connect to the traffic manager¶

The following configuration should be applied to the key manager node(s). It allows the key manager to establish a connection with the traffic manager node(s) to immediately notify any access token revocations to the gateways via the traffic manager.

You need to change the default token expiry time based on your requirements. For more information on how to do this, see Changing the Default Token Expiration Time.

Follow the steps below to configure the traffic manager endpoints.

Open the <IS_KM_HOME>/repository/conf/deployment.toml file.

Configure the traffic manager endpoints as follows.

Note

If your deployment is an All-in-One Deployment, the traffic_manager_urls and traffic_manager_auth_urls needs to point to the all in one node's data publishing endpoints (all in one node's IP or a DNS mapping). To do this, follow the steps below.
- Replace the <traffic-manager-ip> placeholder value with the all in one node's IP or a DNS mapping.
- Replace the <binary-data-publishing-port> and <binary-data-publishing-authentication-port> with the respective port (reflecting any port offsets).
If your deployment is a Distributed Deployment the traffic_manager_urls and traffic_manager_auth_urls should point to the traffic manager node's data publishing endpoints. To do this, follow the steps below.
- Replace the <traffic-manager-ip> placeholder value with the traffic manager node's IP or a DNS mapping.
- Replace the <binary-data-publishing-port>and <binary-data-publishing-authentication-port> placeholder value with the respective port (reflecting any port offsets).

Format

[apim.throttling]
enable_data_publishing = false
enable_policy_deploy = false
enable_blacklist_condition = false
enable_decision_connection = false
throttle_decision_endpoints = ["tcp://<traffic-manager-ip>:5672"]

[[apim.throttling.url_group]]
traffic_manager_urls=["tcp://<traffic-manager-ip>:<binary-data-publishing-port>"]
traffic_manager_auth_urls=["ssl://<traffic-manager-ip>:<binary-data-publishing-authentication-port>"]

Example

[apim.throttling]
enable_data_publishing = false
enable_policy_deploy = false
enable_blacklist_condition = false
enable_decision_connection = false
throttle_decision_endpoints = ["tcp://tm.wso2.com:5672"]

[[apim.throttling.url_group]]
traffic_manager_urls=["tcp://tm.wso2.com:9611"]
traffic_manager_auth_urls=["ssl://tm.wso2.com:9711"]

If the traffic Manager deployment is a High Availability(HA) deployment, the endpoints of both nodes have to be configured as follows.

Format

[apim.throttling]
enable_data_publishing = false
enable_policy_deploy = false
enable_blacklist_condition = false
enable_decision_connection = false
throttle_decision_endpoints = ["tcp://<traffic-manager-1-ip>:5672","tcp://<traffic-manager-2-ip>:5672"]

[[apim.throttling.url_group]]
traffic_manager_urls=["tcp://<traffic-manager-1-ip>:<binary-data-publishing-port>"]
traffic_manager_auth_urls=["ssl://<traffic-manager-1-ip>:<binary-data-publishing-authentication-port>"]

[[apim.throttling.url_group]]
traffic_manager_urls=["tcp://<traffic-manager-2-ip>:<binary-data-publishing-port>"]
traffic_manager_auth_urls=["ssl://<traffic-manager-2-ip>:<binary-data-publishing-authentication-port>"]

Example

[apim.throttling]
enable_data_publishing = false
enable_policy_deploy = false
enable_blacklist_condition = false
enable_decision_connection = false
throttle_decision_endpoints = ["tcp://tm1.wso2.com:5672","tcp://tm2.wso2.com:5672"]

[[apim.throttling.url_group]]
traffic_manager_urls=["tcp://tm1.wso2.com:9611"]
traffic_manager_auth_urls=["ssl://tm1.wso2.com:9711"]

[[apim.throttling.url_group]]
traffic_manager_urls=["tcp://tm2.wso2.com:9611"]
traffic_manager_auth_urls=["ssl://tm2.wso2.com:9711"]

Step-5.2 Remove the existing mutual TLS authenticator configuration¶

Follow the steps below to remove the mutual_tls_authenticator configuration provided in the deployment.toml file in IS-KM.

Open the <IS_KM_HOME>/repository/conf/deployment.toml file in the WSO2 IS as KM node.
Remove or comment out the complete event listener configuration as follows.

# [[event_listener]]
# id = "mutual_tls_authenticator"
# type = "org.wso2.carbon.identity.core.handler.AbstractIdentityHandler"
# name = "org.wso2.carbon.identity.oauth2.token.handler.clientauth.mutualtls.MutualTLSClientAuthenticator"
# order = "158"
# enable = false

Step-5.3 Configure WSO2 IS to prevent authentication failures when retrieving resources¶

Follow the steps below to enable resource access control in IS-KM.

Open the <IS_KM_HOME>/repository/conf/deployment.toml file in the WSO2 IS as KM node.
Add the following configuration to the file.

[resource_access_control]
default_access_allow= true

Step-5.4 Configure WSO2 IS to pass end-user attributes to the backend (JWT)¶

Follow the steps below to configure JSON Web Token (JWT) to pass the end-user attributes to the backend.

Open the <IS_KM_HOME>/repository/conf/deployment.toml file in the WSO2 IS as KM node.
Follow the document Passing Enduser Attributes to the Backend Using JWT.

Step 5.5 Encrypting OAuth2 Keys (access tokens, client secrets, and authorization codes)¶

Follow the steps below to encrypt OAuth2 Keys (access tokens, client secrets, and authorization codes).

Open the <IS_KM_HOME>/repository/conf/deployment.toml file in the WSO2 IS as KM node.
Follow the steps given in Encrypting OAuth Keys.

Step 6 - Configure the WSO2 API-M Gateway to connect to WSO2 IS-KM¶

Note

In this document, the term API Gateways refers to All-in-One Deployment nodes or the Gateway nodes in a Distributed Deployment.

The WSO2 API-M Gateway nodes should be aware of the key manager (IS as KM) endpoints, to handover key validation and authorization tasks.

Follow the steps below to configure the API gateway(s) (WSO2 API Manager nodes) to connect to the IS as KM(s).

Open the <APIM_HOME>/repository/conf/deployment.toml file of API Manager gateway nodes.
Apply the following configuration by pointing to the key manager URL.
Format
```
[apim.key_manager]
service_url = "https://<key-manager-host>:<key-manager-port>/services/"
```
Note
- If you have a Single IS as Key Manager deployment, you need to replace the <key-manager-host> found in the service_url config, with the actual host of the WSO2 IS as KM node or the host of the load balancer fronting the WSO2 IS as KM node.
- If you have multiple IS as Key Managers in High Availability(HA) mode, in an active-active node setup, you need to replace the <key-manager-host> in service_url config with the host of the load balancer which is used to front all of the key manager nodes.
Import the public certificate of WSO2 IS-KM, which is used to sign the tokens, to the WSO2 API-M truststore (client-truststore.jks) under the "gateway_certificate_alias" alias. For more information, see Import the public certificate into the client trust store.
By default, both API Manager and WSO2 IS-KM is configured to have the JDBC User Store as the primary user store. But if you wish to use any other type of user store (LDAP, Active Directory, etc.) in IS-KM, that user store has to be configured in the API Manager nodes as well. Refer to Configuring Primary User Store to configure a new user store.

Step 7 - Optionally, configure High Availability (HA) for the Key Manager¶

Warning

Follow the steps below ONLY if you need to configure HA for the Key Manager.

Make a copy of the active WSO2 IS-KM instance configured above and use this copy as the second key manager active instance.
Configure a load balancer to front the two key manager nodes.

Step 8 - Start the Key Manager(s)¶

Use the command below to start the WSO2 IS as KM. For more information, see Running the Product in the WSO2 Identity Server 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 WSO2 API Manager and WSO2 Identity Server at server startup, you will see the following warning in the WSO2 API Manager 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 WSO2 Servers are created for localhost. Therefore, when WSO2 API Manager boots up, it makes an HTTP call to a web app that is in the key manager (throttle data at KM_URL/throttle/data/v1/keyTemplates ). Thereafter, WSO2 API Manager derives the URL of the key manager that is configured in the deployment.toml, which is localhost.

To overcome this issue, follow the steps below.
1. Create self-signed certificates for WSO2 API-M and WSO2 IS hostnames.
2. Import the public certs of WSO2 API-M to the trust-store.jks of WSO2 IS and vice versa.

Step 9 - Configure the other API-M components¶

Follow the instructions below to configure the other WSO2 API-M components, namely the Publisher, Developer Portal, Traffic Manager, and Gateway:

All-in-One Deployment
- Configuring a Single Node
- Configuring an Active-Active Deployment
Distributed Deployment

Top