Geek Culture
Published in

Geek Culture

Integrating WSO2 APIM, API Microgateway with WSO2 Identity Server

In a typical setup we have the WSO2 API Manager and WSO2 Identity Server Integrated as a Key Manager, as an add-on WSO2 has introduced API Microgateway which can be integrated and used as Gateway along with WSO2 API Manager. Where the management of the APIs will be handled by the WSO2 API Manager.

In this article we are going to see how we can integrate all together and use it in a distributed setup.


  • Prerequisite
  • Setup Architecture
  • Setting up the Environment for Development

( Setup OpenJDK, Setup Microgateway Toolkit, Setup API Controller, Setup MySQL, Setup Microgateway Runtime ( Optional ), Setup the WSO2 Distributions, Setup Docker )

  • Configuring the Database for WSO2 Setup
  • Configuring the WSO2 APIM to Integrate with WSO2 IS
  • Verifying the Setup between WSO2 APIM and IS
  • Setting up the WSO2 API Microgateway
  • Import the APIs to Govern from WSO2 API Manager
  • Conclusion


  1. WSO2 APIM 3.2.0
  2. WSO2 IS 5.11.0
  3. OpenJDK 11
  4. Microgateway Toolkit 3.2.0
  5. Microgateway 3.2.0 Runtime
  6. MySQL 5.7.33
  7. API Controller — apictl 3.2.1

Setup Architecture

Setting Up the Environment for Development

Setup OpenJDK

You can download the pack and extract it to location and then set the environment variables as below:

Setup Microgateway Toolkit

Download and extract it to a location and setup the environment variables as below:

Setup API Controller

Download and extract it to a location and setup the environment variables as below:

Setup MySQL

For this demonstration I’m using the MySQL below version and based on your need you can go with a version and install it using the standard MySQL installation process.

Setup Microgateway Runtime

This setup is needed if we are going to deploy into the Virtual Machine only. As here I’m going to demonstrate how we can do the deployment with Docker, this setup is not needed. For more information on this can be found at the of the Microgateway Runtime Distribution.

Setup the WSO2 Distributions

Download and extract the WSO2 APIM and WSO2 IS distributions and extract it to a location.

Setup Docker

Configuring the Database for WSO2 Setup

Mainly the apim_db, shared_db and identity_db are involved in the distributed setup and other dbs will be used as default h2 database.

Below sample scripts can be used to create the database setup.

Configuring the WSO2 APIM to Integrate with WSO2 IS

WSO2 IS Configuration Updates

As in my local setup I’m going to run both the WSO2 APIM and IS in the same machine, and due to that setting the port offset for the WSO2 IS.

Setup the Host name

Create a mapping in the /etc/hosts to map the host names with local IP

Update the Databases to point to the MySQL Instance, here if we are not using Multi Tenancy the apim_db need not to be shared here.

Download the WSO2 IS Connector for WSO2 APIM from here.

Add the below Traffic Manager Configurations to <IS_HOME>/repository/conf/deployment.toml

Configure the event listeners.

WSO2 APIM Configuration Updates

Update the Host name.

Update the Database Configuration, here we need to specify.

Configure the IS as Keymanager in deployment.toml.

As we updated the mysql database, we needed to add the mysql connector to the <APIM_HOME>/repository/components/lib.

Verifying the Setup between WSO2 APIM and IS

Start the WSO2 IS

Start the WSO2 API Manager

Go to https://wso2apimserver:9443/admin/settings/key-managers and check whether the Type is : WSO2-IS.

Create a User in WSO2 IS and see whether you can view that user in the WSO2 API Manager Console.

Make sure the below Topics are Listened Successfully by the WSO2 API Manager.

Setting up the WSO2 API Microgateway

Before starting make sure you have done the Microgateway Toolkit Setup, if not refer to the section “Setup Microgateway Toolkit”.

  1. Update the <TOOLKIT_HOME>/resources/conf/micro-gw.conf file, this is to change the default configuration, where for our use case we need to point the keymanager to use through the WSO2 API Manager and also other configuration we can edit here and specify in the deployment-config.toml, so that those configurations will be added to the image.

This is the sample configuration used for the setup in the “micro-gw.conf” file.

2. Prepare the API Definition File. Here I’m using two APIs one is secured with Client Credentials Grant Type and with a specific scope and the other is non-secure API.

3. Execute the below command to Initialize and create the project. At this point before executing we can pass two files

API Definition File — Which we created earlier

Deployment Config File — This one we need to update as below.

As we are using the Docker build, update the below section, so that we are copying our custom configuration.

sl-ajanthan@slajanthan-Latitude-3580:~/integration$ micro-gw init testapimgw -a api-definition/api-definition-sample.yaml -d deployment-config/deployment-config.yaml

4. Export the WSO2 API Manager Public Certificate

keytool -export -alias wso2carbon -file wso2carbon.crt -keystore <API-M_HOME>/repository/resources/security/wso2carbon.jks

5. Import the certificate to wso2am-micro-gw-toolkit-linux-3.2.0/lib/platform/bre/security/ballerinaTruststore.p12

keytool -import -trustcacerts -alias wso2apimlocal -file wso2carbon.crt -keystore <TOOLKIT_HOME>/lib/platform/bre/security/ballerinaTruststore.p12

6. Export the public certificate of the WSO2 API and import it to the below trust store.

keytool -export -alias wso2carbon -file wso2carbon-alias.crt -keystore <API-M_HOME>/repository/resources/security/wso2carbon.jks

keytool -import -trustcacerts -alias gateway_certificate_alias -file wso2carbon-alias.crt -keystore <TOOLKIT_HOME>/lib/platform/bre/security/ballerinaTruststore.p12

7. Execute the build command to build the Image.

sl-ajanthan@slajanthan-Latitude-3580:~/integration$ micro-gw build testapimgw — docker — docker-image testapigw:v1 — docker-base-image wso2/wso2micro-gw:3.2.0

8. Start the Containers.

docker run -d -p 10400:9095 -p 10401:9090 testapigw:v1

If we need to load the configuration from external file, without building the image again, can use the below command:

docker run -p 10400:9095 -p 10401:9090 -v <host_path_to_micro-gw.conf_dir>:/home/ballerina/conf testapigw:v1

9. Verify the Microgateway

Also by invoking the non-secure endpoint we can check whether the request is processed through the Micro gateway.

But when you try with the secured Endpoint:

10. To invoke the secured endpoints we need to Import the API definitions to WSO2 APIM and need to manage it from there. To ease this process the API Controller was introduced by WSO2.

Import the APIs to Govern from WSO2 API Manager

  1. Hope already done the “Setup API Controller”
  2. Once (1) is done execute the below command to set the environmental variables.

3. Check whether you can login to the system.

4. Initialize the project to create for Import.

5. Go to the newly created project “testapiimport” and update the <HOME>/testapiimport/Meta-information/api.yaml

6. Import the API

apictl import-api -f testapiimport -e development -k

7. Create Application and Subscribe API

8. Generate the Bearer Token.

9. Invoke the Secured Endpoint with Bearer Token.

10. Check the logs of Microgateway whether the API calls passed through.


This article explained about a basic setup that we can do along with WSO2 APIM, WSO2 IS and WSO2 Micro Integrator. Using this understanding we can expand the Architecture to cater High availability and also on the API definition we can add other OAuth2.0 Grant Types using the openAPI specification for further use.



Get the Medium app

A button that says 'Download on the App Store', and if clicked it will lead you to the iOS App store
A button that says 'Get it on, Google Play', and if clicked it will lead you to the Google Play store
Ajanthan Eliyathamby 🇱🇰

Ajanthan Eliyathamby 🇱🇰

Associate Architect — Enterprise Integration | WSO2 Certified Solution Architect |