Set up WSO2 Identity Server as a Key Manager¶
Follow the instructions below to configure WSO2 Identity Server (WSO2 IS) as the Key Manager of the WSO2 API Manager (WSO2 API-M) deployment globally.
- Step 1 - Download and install WSO2 IS
- Step 2 - Optionally, configure port offset for WSO2 IS
- Step 3 - Install and configure the databases
- Step 4 - Configure WSO2 IS with WSO2 API-M
- Step 5 - Configure WSO2 API-M with the WSO2 IS
- Step 6 - Optionally, configure High Availability (HA) for the Identity Server
- Step 7 - Start the Identity Server(s)
Step 1 - Download and install WSO2 IS¶
Download and install WSO2 Identity Server version 5.11.0. If you downloaded the archive, extract it. <IS_HOME>
refers to the root folder of the extracted WSO2 Identity Server.
It is assumed that you have already downloaded WSO2 API Manager.
<APIM_HOME>
refers to the root folder of the unzipped WSO2 API-M pack.
Note
If you have a WSO2 subscription, it is recommended to update both APIM and IS to the latest available U2 versions to prevent any compatibility issues between the two products.
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). 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 WSO2 IS and WSO2 API-M.
- WSO2SHARED_DB - This database contains the registry and user management data.
Follow the instructions below to set up and configure the databases for the WSO2 IS as the Key Manager node:
-
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 WSO2 API Manager, you only need to configure the data source configurations in the WSO2 IS node for it to connect with the required databases and act as the Key Manager. -
Share
WSO2_SHARED_DB
with WSO2 IS.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"
-
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"
-
Share
WSO2_SHARED_DB
with WSO2 API-M.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"
-
Share
WSO2AM-DB
with WSO2 API-M.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 WSO2 IS with WSO2 API-M¶
-
Download the WSO2 IS Connector.
-
Extract the distribution and copy the following JAR files, which are in the
<wso2is-extensions-1.2.10>/dropins
directory, to the<IS_HOME>/repository/components/dropins
directory.wso2is.key.manager.core-1.4.2
wso2is.notification.event.handlers-1.4.2
-
Add the
keymanager-operations.war
, which is in the<wso2is-extensions-1.2.10>/webapps
directory, to the<IS_HOME>/repository/deployment/server/webapps
directory. -
Configure the Traffic Manager endpoints.
Add the following configuration in the
<IS_HOME>/repository/conf/deployment.toml
file and configure the Traffic Manager endpoints as follows:[[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/"]
-
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"
-
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 WSO2 Identity Server 5.10.0 documentation, and apply the relevant configurations in the
<IS_HOME>/repository/conf/deployment.toml
file to enable the feature.
Step 5 - Configure WSO2 API-M with the WSO2 IS¶
By default, WSO2 API Manager and WSO2 Identity Server comes with a JDBC User Store as the primary userstore. However, if you wish to use any other type of user store (e.g., LDAP, Active Directory, etc.) in WSO2 IS, that particular user store has to be configured in the API Manager nodes as well. 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"
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.
-
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 WSO2 Identity Server nodes.
Step 7 - Start the Identity Server(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
If you have configured the hostnames for WSO2 API Manager and WSO2 Identity Server, during the 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 the 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 atKM_URL/internal/data/v1/keyTemplates
). Thereafter, WSO2 API Manager decides the URL of the Key Manager based on the URL that is configured in thedeployment.toml
, which islocalhost
.To overcome this issue, you need to create self-signed certificates for WSO2 API-M and WSO2 IS hostnames. Then import the public certificates of WSO2 API-M to the
trust-store.jks
of WSO2 IS and vice versa. This should resolve the SSL handshake failure.Note
In a IS as KM separated environment to invoke RESTful APIs (product APIs), users must generate tokens through API-M Control Plane's token endpoint. The tokens generated using third party key managers, are to manage end-user authentication when accessing APIs.
Important
When WSO2 Identity Server (IS) is configured as the resident key manager, the IS acts as the default key manager component. This key manager component authenticates users when they are using OAuth2 authentication and not basic authentication. Hence for users who exist in a secondary user store within the key manager component, basic authentication will not work. Therefore if basic authentication should be used, the user needs to be added to the Control Plane (CP) component of the APIM server for authentication.
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