1 Sep, 2022 | 3 min read

Secure Your WSO2 Micro Integrator Deployment

  • Dhanushka Madushan
  • Software Engineer - WSO2

Photo by Kieran Somerville on Unsplash

First published on DZone.

This article is about how to secure WSO2 Micro Integrator on microservices integration deployment. It describes how to use keystores, secure vaults, and more. WSO2 Micro Integrator is an integration solution widely used in enterprise integration. You can use it to implement mediation policies, message transformation, security, and more. In this article, let’s focus on how you can securely place WSO2 Micro Integrator on your deployment.

First Things First

WSO2 Micro Integrator comes with a default keystore that is used in many cryptography-related features including SSL, mutual SSL, and password encryption. Since this is the default key shipped with the product, anyone can use it, which is a security risk. Therefore, ensure you have generated a new keystore and truststore. See this document for more information.

Avoid Having the Default H2 Database

By default, the solution ships with a H2 embedded database to store data for the following purposes:

  • Cluster coordination
  • RDBMS user store
  • Transaction counter

It is not a good practice to use the H2 database in a deployment environment, as this allows individuals with access to your files. WSO2 Micro Integrator provides the following list of databases that you can easily configure:

  • MySQL
  • Oracle
  • PostgreSQL
  • IBM DB

These are enterprise databases that are more secure than a simple H2 database.

Use the Secure Vault to Store Sensitive Data

The solution uses synapse-based XML documents to specify and store mediation policies. In some cases, you might need to access secure services/endpoints with inputs such as passwords. Storing these inside the mediation flow is risky as hackers can access them if they breach the security protocols and access the mediation sequences. Fortunately, WSO2 Micro Integrator provides a secure vault to store this sensitive information. Instead of keeping data in a plain text format, you can save and encrypt the data, allowing WSO2 Micro Integrator to decrypt it whenever needed.

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


You will notice the value is given as a plain text and is surrounded by square brackets. Let’s use the keystore file to encrypt this content and replace this value. To do this, use the "./ciphertool.sh -Dconfigure" command. It will ask you for the keystore password, which is "wso2carbon" by default. It is recommended to make a new password when using this in a production environment. If you recheck the deployment.toml file, you will see the value with the square bracket has now changed into an encrypted value. You can use the key when you need to use this secret.

If you are using WSO2 Micro Integrator in a microservices environment, you must generate these encrypted entities first, and then copy them inside the image. 

Now, you can use this key inside the WSO2 Micro Integrator 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 vault 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 mentioned earlier, this is an elegant way of storing passwords you may need to access third-party services. For more information, click here.

Using HashiCorp Secure Vault

If you have dynamic content that you must change, consider using the HashiCorp Vault with WSO2 Micro Integrator. The HashiCorp Vault is highly secure, especially for microservices environments. In this vault, you can define the secrets you need, and the Vault API lets services access these secrets securely.

You can configure WSO2 Micro Integrator to access the HashiCorp Vault by using Secure Vault driver into the <MI_HOME>/lib directory and by adding the following TOML configuration into the <MI_HOME>/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"

Afterwards, you can access secret values with the  hashicorp:vault-lookup('path-name', 'field name')  expression, which is the same as the secure vault in WSO2 Micro Integrator. Find out more here.

Aside from the local secure vault and HashiCorp’s vault, you can use Docker Secrets and Kubernetes Secrets too. 

Hide Observable Data with Log Masking

Logging is an important requirement when building a server-side application. This is the most basic observability principle that you can implement to track errors and find their root cause. While it simplifies your process, it may affect your security if you log sensitive information like credit card details and passwords. If you must do so, they need to be secure.

WSO2 Micro Integrator may record transactions with sensitive data. If you enable logging, sensitive data may be logged with a message payload or header. Luckily, WSO2 Micro Integrator lets you mask this sensitive information while it logs into the given destination. the solution uses log4j as the logging library. You can specify what logs need to be printed and where.

Enable log masking for WSO2 Micro Integrator by adding an additional  m  to the  CARBON_CONSOLE  log appender (or any appender you wish to enable log masking) in the <MI_HOME>/conf/log4j2.properties file. This is what it 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 the 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 information visit Masking Sensitive Information in Logs.

Secure Your Proxy Services in WSO2 Micro Integrator

One of the main purposes of the solution is to expose its mediation endpoints to the client’s endpoint. When you must expose WSO2 Micro Integrator services externally, you need a proper security mechanism to authorize your services. Web Service Security (WS Security) helps you achieve this by applying different authentication and authorization policies to WSO2 Micro Integrator endpoints.

With WSO2 Micro Integrator, you can authenticate and authorize the client before accessing its endpoint. It provides multiple ways to do this 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 a username and password against the user store in WSO2 Micro Integrator. You can create users and roles with its Command Line Interface (CLI) tool. Then, you can map those roles with WS Security policies by using a registry resource project. Follow the instructions here to configure WS Security for WSO2 Micro Integrator.

Secure Your Rest APIs in WSO2 Micro Integrator

Now you know how to secure proxy services with WSO2 Micro Integrator. But what about APIs? As APIs become increasingly more important, the solution lets you define your API and conduct mediations similar to proxy services.

For APIs, WSO2 Micro Integrator does not directly let you secure REST APIs, so you must use WSO2 API Manager’s Gateway to expose your services. If you have a proxy service that must be exposed, you can easily configure WSO2 API Manager to access the APIs in WSO2 Micro Integrator. Here, it automatically publishes artifacts to WSO2’s API Manager service catalog. so you can manage the APIs in the solution with WSO2 API Manager.

On the other hand, you can conduct an API first integration by creating API specifications. First, create a mock API with WSO2 API Manager without the endpoint. Then, import the API specs into WSO2 Integration Studio through the Service Catalog and implement the mediation logic there. Here are the steps to do so.

Congratulations, now you know how to expose the APIs in WSO2 Micro Integrator via WSO2 API Manager, which lets you apply various policies to expose and secure APIs such as enabling transport-level security with SSL verification and authentication with OAuth2 protocols. In addition, you can use API lifecycle management, throttling, and monetization.

If you don’t need to use WSO2 API Manager to secure your APIs, you can use WSO2 Micro Integrator handlers and Java coding to secure the APIs. These are Java hooks that gets triggered before the request hits the API mediation flow and before sending the response. This is shown in the Figure below.

Figure 1: WSO2 Micro Integrator API Handlers

WSO2 Micro Integrator has two methods,  handleRequest()  and  handleResponse() , to handle requests and responses. Both methods return a boolean value that says whether the request or response should proceed as usual or is restricted. You can implement authorization on the  handleRequest()  method and limit access to the API. The API that must have this authorization mechanism can be specified in the Micro Integrator Synapse API definition. Find out how to configure it here.

Subscribe to WSO2 Micro Integrator and Stay up-to-Date

Whenever you use software, it should be secure against vulnerabilities. For customers who subscribe to WSO2 Micro Integrator, they benefit as the solution conducts frequent and comprehensive scans, and sends security updates to its subscribers. Click here to get a subscription today.