Secure Your WSO2 Micro Integrator Deployment

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

First Things First

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

Refer to this document for setup steps.

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 access 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 uses synapse-based XML documents 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 be a good solution in the case an attacker gets 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 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 by square brackets. We will use the keystore file to encrypt this content and replace this value. For that, you can use the “./ -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 media flow. As mentioned earlier, this is an elegant way of storing passwords that you need to access third-party services. Access the official documentation here.

Using HashiCorp Secure Vault

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

You can configure MI to access HashiCorp 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 the hashicorp:vault-lookup('path-name', 'field name') expression, which is the same as the MI secure vault. For more instructions on how to do it, refer to the documentation.

Other than the local secure vault and HashiCorp 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:

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 are logging enabled, sensitive data may be logged with message payload or header. WSO2 MI lets you mask this sensitive information while it logging in to the given destination. WSO2 MI uses log4j as the logging library. 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,}$"

For more, visit Masking Sensitive Information in Logs documentation.

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 the client before accessing its endpoint. MI provides multiple ways including username token, non-repudiation, integrity, and confidentiality. For example, you can configure your proxy services with a username token, where you can authenticate requests with username and password against the MI user store. In MI, you can create users and roles with the MI CLI tool. Then you can map those roles with WS security policies created by using a registry resource project.

If you are looking for more details on how to configure WS security for MI, then follow the instructions 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 in web space. WSO2 MI gives you to define your API and do some mediations the 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 publishes 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 by creating API specs. First, you need to create a mock API with APIM that include what the API looks like. Then you can import API specs into the Integration Studio and implement the mediation logic there. Access the detailed steps to how to do it.

Now you know how to expose WSO2 MI API through the WSO2 APIM. WSO2 APIM lets you apply various policies for exposing APIs that include securing APIs as well. You can enable transport-level security with SSL verification and authentication with the OAuth2 protocol. In addition to those security features, you can use other features such as API lifecycle management, throttling, and monetization.

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 gets triggered before the request hits the API mediation flow and before sending the response.

WSO2 MI API handlers

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

Get a WSO2 MI Subscription and Always up to Date

Finally, none of the software is one hundred percent secure where vulnerabilities get discovered as time goes on. Therefore, the software product that you are using should always get updated to withstand cyberattacks. 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 focused on the basic security practices that you should follow to secure your Micro Integrator from vulnerabilities. Keep in mind that there are more best practices that you need to follow in order to secure your whole deployment. Always keep in mind to secure links with SSL or mutual SSL, update vulnerable dependencies, and handle attacks such as DDoS and XSS to make sure your deployment is secure.


Leave a Comment