Configuring WSO2 Identity Server as a Key Manager¶
Please follow below steps to configure the prepackaged WSO2 Identity Server as the Key Manager of WSO2 API Manager deployment.
Warning
Before you begin check the product compatibility for WSO2 IS as Key Manager.
- Step 1 - Download WSO2 IS as a Key Manager (WSO2 IS-KM)
- Step 2 - Optionally, configure port offset for WSO2 IS
- Step 3 - Install and configure the databases
- Step 4 - Configure the Key Manager (WSO2 IS) with WSO2 API-M
- Step 5 - Configure WSO2 API-M with the Key Manager (WSO2 IS)
- Step 6 - Optionally, configure High Availability (HA) for the Key Manager
- Step 7 - Start the Key Manager(s)
- Step 8 - Configure the other API-M components
Step 1 - Download Prepackaged WSO2 IS as a Key Manager (WSO2 IS-KM)¶
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.9.0 comes with the necessary configurations already installed in order to connect it with WSO2 API Manager, and is therefore different to the default version (vanilla pack) of WSO2 Identity Server 5.9.0. The prepackaged WSO2 Identity Server as a Key Manager 5.9.0 is compatible with WSO2 API Manager 3.0.0 and is available as by WUM .
Download the prepackaged WSO2 Identity Server as a Key Manager from here (Select the version as 3.0.0 and download the Identity Server as a Key Manager from the table) or get the WUM updated distribution and unzip it. <IS_KM_HOME>
will refer to the root folder of the unzipped WSO2 Identity Server as a Key Manager pack. It is assumed that you have already downloaded WSO2 API Manager. <APIM_HOME>
will refer to the root folder of the unzipped WSO2 API-M pack.
Step 2 - Optionally, configure port offset for WSO2 IS¶
Note
This is only required 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.
Open the <IS_KM_HOME>/repository/conf/deployment.toml
file and change the offset to 1 by applying following config. This increments the product's default port by one.
[server]
offset = 1
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 WSO2 IS and WSO2 API-M.
-
WSO2AM_DB - This database stores the identity data and API-related data and it includes OAuth tokens and keys. When serving key-validation requests, the Key Manager accesses the
WSO2AM_DB
, validates whether there are subscriptions made by the particular key. -
WSO2SHARED_DB - This database contains the registry and user management data.
The steps to setup and configure the databases for WSO2 IS as the Key Manager node is given below.
-
Open
<IS_KM_HOME>/repository/conf/deployment.toml
file and comment out the default config database configuration as follows.
2. Install, setup and configure#[database.config] #type = "h2" #url ="jdbc:h2:./repository/database/WSO2SHARED_DB;DB_CLOSE_ON_EXIT=FALSE;MVCC=TRUE" #username = "wso2carbon" #password = "wso2carbon"
WSO2AM_DB
andWSO2_SHARED_DB
databases as illustrated in Changing the Default Databases. This particular guide provides you all the steps on how to install the database, how to setup database users, create tables using relevant scripts, apply the drivers which are compatible with the database type and how to configure the connection details in connection data in<IS_KM_HOME>/repository/conf/deployment.toml
file.Warning
If you have already created and setup databases(
WSO2AM_DB
andWSO2_SHARED_DB
) for WSO2 API Manager, you only need configure the data source configurations in WSO2 IS as Key Manager node. Then it will connect with required databases and acts as the Key Manager.Sample configuration which is required to be applied in
<IS_KM_HOME>/repository/conf/deployment.toml
for MySQL is given below.[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>"
[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"
-
Please make sure to apply the same datasource configuration in above step for
WSO2AM_DB
andWSO2_SHARED_DB
in<APIM_HOME>/repository/conf/deployment.toml
as well.
Step 4 - Configure the WSO2 IS as Key Manager with WSO2 API Manager¶
-
Configure the Key Manager to setup communication with API Gateway Environments.
Info
When users and roles are removed via the Key Manager, the tokens issued for that particular users and roles should be invalidated. But if the corresponding user tokens are cached on the Gateway, these tokens will only get invalidated when the cache is timed out. Therefore, you need to enable communication between the Key Manager and Gateway/Gateways to immediately invalidate the tokens in such scenarios.
For that, open
<IS_KM_HOME>/repository/conf/deployment.toml
file and configure the available Gateway Environments as follows.- Single gateway environment
[[apim.gateway.environment]] name = "<Environment-Name>" type = "<Environment-Type>" description = "<Environment-Description>" service_url = "https://<gateway-server-host>:<gateway-server-port>/services/" username= "<admin-username>" password= "<admin-password>"
[[apim.gateway.environment]] name = "Production and Sandbox" type = "hybrid" description = "This is a hybrid gateway that handles both production and sandbox token traffic." service_url = "https://localhost:9443/services/" username= "${admin.username}" password= "${admin.password}"
- Multiple gateway environments
[[apim.gateway.environment]] name = "<Environment-1-Name>" type = "<Environment-1-Type>" description = "<Environment-1-Description" service_url = "https://<gateway1-server-host>:<gateway1-server-port>/services/" username= "<admin-username>" password= "<admin-password>" [[apim.gateway.environment]] name = "<Environment-2-Name>" type = "<Environment-2-Type>" description = "<Environment-2-Description" service_url = "https://<gateway2-server-host>:<gateway2-server-port>/services/" username= "<admin-username>" password= "<admin-password>"
[[apim.gateway.environment]] name = "Production" type = "production" description = "This is the gateway that handles production token traffic." service_url = "https://localhost:9445/services/" username= "admin" password= "admin" [[apim.gateway.environment]] name = "Sandbox" type = "sandbox" description = "This is the gateway that handles sandbox token traffic." service_url = "https://localhost:9446/services/" username= "admin" password= "admin"
-
Add following configuration to
<IS_KM_HOME>/repository/conf/deployment.toml
file and configure the traffic manager endpoints as follows.Note
Please comment out
receiver_url
andreceiver_auth_url
default configuration elements under[apim.throttling]
before adding the configurations specified in this step.[apim.throttling] enable_data_publishing = false enable_policy_deploy = false enable_blacklist_condition = false enable_decision_connection = false #receiver_url = "tcp://localhost:9611" #receiver_auth_url = "ssl://localhost:9711"
[[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>"]
[[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 with High Availability(HA), the endpoints of both nodes has to be configured as follows.
[[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>"]
[[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"]
Info
- This particular configuration should be applied in Key Manager nodes to establish the connection with traffic manager node/nodes in order to immediately notify the access token revocations to gateways through traffic manager.
- If you are having an All-in-One Deployment, the
traffic_manager_urls
andtraffic_manager_auth_urls
has to be pointed to all in one node's data publishing endpoints(Replace the<traffic-manager-ip>
placeholder with all in one node's IP or a DNS mapping and<binary-data-publishing-port>
,<binary-data-publishing-authentication-port>
with releavant ports with offset). - If you are working with a Distributed Deployment the
traffic_manager_urls
andtraffic_manager_auth_urls
should be pointed to traffic manager node's data publishing endpoints(Replace the<traffic-manager-ip>
placeholder with traffic manager node's IP or a DNS mapping and<binary-data-publishing-port>
,<binary-data-publishing-authentication-port>
with releavant ports with offset).
-
If you want to configure JSON Web Token (JWT) in order to pass the end user attributes to backend, open the
<IS_KM_HOME>/repository/conf/deployment.toml
file in the WSO2 IS as KM node and add relevant config changes given in Passing Enduser Attributes to the Backend Using JWT -
If you wish to encrypt the OAuth2 Keys (access tokens, client secrets and authorization codes) follow the steps given in Encrypting OAuth Keys and apply relevant configurations in
<IS_KM_HOME>/repository/conf/deployment.toml
file to enable the feature.
Step 5 - Configure WSO2 API-M with the WSO2 IS as Key Manager¶
-
Configure the WSO2 API Manager nodes which acts as the API gateways to setup communication with IS as KM node/nodes. For that, open
<APIM_HOME>/repository/conf/deployment.toml
file of API Manager gateway nodes and apply following config pointing to Key Manager URL.[apim.key_manager] service_url = "https://<key-manager-host>:<key-manager-port>/services/"
[apim.key_manager] service_url = "https://km.wso2.com:9444/services/"
Info
- In here, API Gateways are referred to All-in-One Deployment nodes and the Gateway nodes in a Distributed Deployment. Basically, the Gateway nodes should be aware of the Key Manager endpoints, which in this case is WSO2 Identity Server as Key Manager, in order to handover key validation and authorization tasks.
- If you are working with a Single IS as Key Manager node, you need to replace the
<key-manager-host>
inservice_url
config with the actual host of the WSO2 IS as KM or the host of the fronted load balancer. - If you are working with multiple IS as Key Manager in High Availability(HA) mode active-activ node setup, you need to replace the
<key-manager-host>
inservice_url
config with the host of the load balancer which is used to front the all key manager nodes.
-
Import the Key Manager's public certificate to WSO2 API-M's truststore.
Import the public certificate of WSO2 IS as the Key Manager, 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 the WSO2 IS as Key Manager comes with JDBC User Store as the primary userstore. But if you wish to use any other type of user store(LDAP, Active Directory etc) in IS as Key Manager, that particular user store has to be configured in API Manager nodes as well. Please refer Configuring Primary User Store and apply relevant configs to plug a new user store.
Step 6 - Optionally, configure High Availability (HA) for the Key Manager¶
Warning
These steps are ONLY applicable if you need to configure HA for the Key Manager.
-
Make a copy of the active 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 7 - Start the Key Manager(s)¶
Start WSO2 Identity Server for the changes to take effect. For more information, see Running the Product in the WSO2 Identity Server documentation.
-
cd <IS_KM_HOME>>/bin/ sh wso2server.sh
-
cd <IS_KM_HOME>>\bin\ wso2server.bat
Troubleshooting
- You may notice the following error messages when starting up the server. This occurs because some API Manager directories are not available in the Identity Server. These are not critical errors, so they can be ignored. Alternatively, you can create the listed directories in the Identity Server pack.
ERROR {org.wso2.carbon.apimgt.impl.utils.APIUtil} - Custom sequence template location unavailable for custom sequence type in : repository/resources/customsequences/in ERROR {org.wso2.carbon.apimgt.impl.utils.APIUtil} - Custom sequence template location unavailable for custom sequence type out : repository/resources/customsequences/out ERROR {org.wso2.carbon.apimgt.impl.utils.APIUtil} - Custom sequence template location unavailable for custom sequence type fault : repository/resources/customsequences/fault
- If you have configured the hostnames for WSO2 API Manager and WSO2 Identity Server in the server start up, 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 webapp that is in the Key Manager (throttle data at
KM_URL/throttle/data/v1/keyTemplates
). Thereafter, WSO2 API Manager decides the URL of the Key Manager base on the URL that is configured in thedeployment.toml
, which is localhost.To overcome this issue, you need to create self-signed certificates for WSO2 API-M and WSO2 IS host names. Then import the public certs of WSO2 API-M to the
trust-store.jks
of WSO2 IS and vice versa. This should resolve the SSL handshake failure.
Step 8 - 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
- Distributed Deployment