Secure your WSO2 Microintegrator

Dhanushka Dhanushka Follow Jun 13, 2022 · 10 mins read
Secure your WSO2 Microintegrator
Share this

WSO2 Microintegrator is an integration solution that is widely used in enterprise integration. You can use MI(For short let’s use Microintegrator as MI) to implement mediation policies, message transformation, security, and many more. In this article, we are going to focus on how you can securely place MI on your deployment.

First thing first:

WSO2 MI comes with a default Keystore that is used in many cryptography-related features including SSL, mutual SSL, password encryption, and so on. Since this is a public one, you should make sure that you have generated a new Keystore and truststore for the MI.

If you are looking for steps on how you do it, then refer to the following document:

Avoid having the default H2 database and use a proper one

By default WSO2 MI ships with H2 embedded database to store data for the following purposes:

  • Cluster coordination
  • RDBMS user store
  • Transaction counter

It is not good practice to use the H2 database in the deployment environment as it is stored in the deployment environment where people who have access to the deployment able to acess this file. WSO2 MI provides the following list of databases that you can easily configure with MI:

  • MySQL
  • Oracle
  • Postgre
  • IBM DB

These databases are enterprise databases that provide much more security than the simple H2 database. Therefore, make sure to configure any of the databases given here rather than using the default H2 database to have a good security level.

Use the secure vault to store sensitive data

WSO2 MI use synapse-based XML document to specify and store mediation policies. In some cases, you might need to access secure services/endpoints with particular inputs such as passwords. Storing these inside the mediation flow might not good solution in case of attacker get access to the MI instance as these mediation sequences are stored in a file.

MI provides a secure vault to store this sensitive information in an encrypted manner. Instead of keeping data as plain text, you can save data encrypted where MI is able to decrypt it whenever it is needed.

You can configure the text you need to encrypt under the [secrets] section on the /conf/deployment.toml folder(Define this at the bottom of the file). Check the following example values that you are defined in the deployment.toml file:


You can notice that value is given as a plain text value and surrounded with square brackets. We will use the Keystore file to encrypt this content and replace this value. For that, you can use ./ -Dconfigure command. It will ask you the Keystore password where by default it would be wso2carbon(Make sure to create a new one when you are using this in a production environment). If you check the deployment.toml file again, you may notice that the value with the square bracket gets changed into an encrypted value. This is the encrypted value and you can use the key whenever you need to use this particular secret.

If you are using MI in a microservices environment, you have to generate these encrypted entities first and then copy them inside the image.

Now you can use this key inside the MI sequences. Check the following example property mediator that retrieves an encrypted entity and logs it:

<property expression="wso2:vault-lookup('hello')" name="helloProperty" scope="default" type="STRING"/>
<log level="custom">
 <property expression="$ctx:helloProperty" name="secure valut log"/>

The wso2:vault-lookup() function lets you retrieve decrypted values you have specified in the deployment.toml in an encrypted format. Now, you can use this property anywhere in the mediation flow. As early mentioned this is an elegant way of storing passwords that you need to access third-party services.

Using Harshicorp secure vault

If you have dynamic content that you need to change, then you can consider using Harshicorp secure vault with the MI. Harshicorp vault is a secure vault provided by Harshicorp, especially for microservices environments. In the Harshicorop vault, you can define the secrets you need and Vault API lets services access these secrets.

You can configure MI to access the Harshicorp vault by Secure Vault driver into the */lib* directory and by adding the following TOML configuration into the /conf/deployment.toml file:

name = "hashicorp"
address = ""
roleId = "ROLE_ID"
secretId = "SECRET_ID"
cachableDuration = 15000
engineVersion = 2
namespace = "NAMESPACE"
trustStoreFile = "${carbon.home}/repository/resources/security/client-truststore.jks"
keyStoreFile = "${carbon.home}/repository/resources/security/wso2carbon.jks"
keyStorePassword = "KEY_STORE_PASSWORD"

Now you can access secret values with harshicorp:vault-lookup(‘path-name’, ‘field-name’) expression which is the same as the MI secure vault.

For more instruction on how to do it, refer to the following documentation:

Use Hashicorp Secrets - WSO2 API Manager Documentation 4.1.0

Other than the local secure vault and Harshicorp secure vault, you can use Docker secrets and Kubernetes secrets as well. The implementation of those two methods is pretty much similar. Check the following documentation to learn more about these two methods:

Use Docker Secrets in Synapse Configurations - WSO2 API Manager Documentation 4.1.0

Use Kubernetes Secrets in Synapse Configurations - WSO2 API Manager Documentation 4.1.0

Hide observable data with log masking

Logging is an important requirement when you are building a server-side application. Logging is the most basic observability principle that you can implement to track errors and find the root cause. While it makes simplify your process, it may cause a security impact if you log sensitive information. If you need to log sensitive information such as credit card numbers and passwords, you need to care about how you are going to keep it secure.

MI may place where transactions with sensitive data are present. If you logging enabled and sensitive data may be logged with message payload or header. WSO2 MI let you mask this sensitive information while it logging in to the given destination. WSO2 MI uses log4j as the logging library and you can specify what are the logs that need to print and where they should print.

You can enable log masking for WSO2 MI by adding an additional ‘m’ to the CARBON_CONSOLE layout appender in the /conf/ file. Following is what looks like when you enable log masking for log4.

appender.CARBON_CONSOLE.layout.pattern = [%d] %5p {%c{1}} - %mm%ex%n

Now, you can define masking patterns in RegEx format in the deployment.toml file. This will search RegEx patterns on the logline and replace those with ***** values.

"CREDIT_CARD_VISA" = "4[0-9]{6,}$"

Masking Sensitive Information in Logs - WSO2 API Manager Documentation 4.1.0

Secure your proxy services in MI

One of the main purposes of MI is to expose its mediation endpoints to the client endpoint. When you need to expose MI services outside, you need to have a proper security mechanism to authorize your services. Web Service Security(WS Security) helps you to achieve this by applying different authentication and authorization policies to the MI endpoints.

With MI, you can authenticate and authorize client before access its endpoint. MI prvide multiple different ways including Username Token, Non-repudiation, Integrity, Confidentiality and so on. For an example, you can configure your proxy services with Username Token, where you can autheticate request with username and password against MI user store. In MI, you can create user and roles with MI CLI tool. Then you can map those roles with WS security policies created by using a registry resoure project.

Do you wan’t more details on how to configure WS security for MI, then follow the instruction in here.

Secure your REST APIs in MI

Now you know how to secure proxy service with WSO2 MI. How about APIs? Now web services are fading away and APIs take the lead of web space. WSO2 MI gives you to define your API and do some mediations same as the proxy services do.

APIs WSO2 MI does not directly provide you a way to secure REST API and you need to use WSO2 API Manager(APIM) Gateway to expose your services. If you already have a proxy service that you need to expose, then you can easily configure WSO2 APIM to access MI APIs. Here MI automatically publish artifacts to the APIM service catalog such that you can manage MI APIs with the APIM.

On the other hand, you can do API first integration by starting creating API specs. First you need to create mock API with APIM that include how the API looks like. Then you can import API specs into the Integration Studio and implement the mediation logics in there. Following is the detailed steps to how to do it.

Now you know how to expose WSO2 MI API through the WSO2 APIM. WSO2 APIM let you to apply various different policies of exposing APIs that include securing APIs as well. You can enable trasport level security with SSL verification and authentication with OAuth2 protocol.

Other than those security features, you can use other features such as API lifecycle management, throttling, monotization as well.

If you don’t need to use APIM to secure your MI APIs, you can use MI handlers and some JAVA code to secure MI APIs. MI API handlers is a JAVA hook that get trigger before the request hit the API mediation flow and before send the response.

WSO2 MI API handlers

It provide two methods handleRequest() and handleResponse() to handle request and the response. Both of these methods return a boolean value that say whether the request or response should be proceed as usual or restricted. Now you know the trick. You can implement authorization on the handleRequest() method and limit the access to the API. The API that need to have this authorization machanism can be specified in the MI Synapse API definition. You can get more details on how to configure it with the following documentation.

Apply Security to a REST API — WSO2 API Manager Documentation 4.1.0

Get a WSO2 MI subscription and always up to date

Finally, non of the software is one hundred present secure where vulnerabilities get discovered when the time goes on. Therefore, the software product that you are using, should always get updated to withstand cyber attacks. MI security scans are performed frequently and check if there are any vulnerabilities. If there are any vulnerabilities, WSO2 sends security updates to subscription customers. For more security, get a subscription and keep on updating the deployment.

In this article we have focus on the basic security practices that you should follow to secure your Microintegrator from vulunerabilities. Keep it mind that there are lot more of best practices that you need to follow inorder to secure you whole deployment. Always keep on mind to secure links with SSL or mutual SSL, update vulunerable dependencies, handle attacks such as DDoS and XSS to make sure your deployment is secure.

Join Newsletter
Get the latest news right in your inbox. We never spam!
Written by Dhanushka Follow
Hi, I am Dhanushka, the author of TechCraftZone