WSO2 Micro Integrator and the Chamber of Secrets

The more the technology evolves every day, the more our lives are relying on it and the more vulnerable our lives have become to outsiders. We live in an era where everything around us getting systemized, computerized, and nearly fully automated. Hence, it is becoming more and more vital to secure every aspect of our data before they fall into someone’s hand. No matter how secured the underline implementation of your application is, it is equally important that you protect the data integrity of your system while configuring or integrating it with various heterogeneous systems. Among all of these, secret protection is an increasingly important legal tool for businesses to preserve such sensitive information.

When WSO2 Micro Integrator being used as an open-source middleware to enable the integration of heterogeneous systems and applications across the enterprise, it is highly likely to have sensitive information used in the configuration files related to your integration logic and across different environments. Because of this reason, WSO2 Micro Integrator has been significantly improved to manage your sensitive information by letting you store your secrets securely in your integration solution.

We will have a series to cover how to securely store your sensitive information used in integration logics (e.g., passwords, API keys, tokens, etc.). It will be done in a practical way where you get your “hands dirty” by trying things out — we will use the latest WSO2 Micro Integrator 1.2.0 (WSO2 Enterprise Integrator 7.1.0) and WSO2 Integration Studio 7.1.0 for demonstration purposes throughout this series. (WSO2 Micro Integrator and WSO2 MI will be used interchangeably here).

So, before we fly right into the real stuff, let’s first buckle up with some theory behind the ride.

A bit about WSO2 Secure Vault Implementation…

WSO2 Micro Integrator comes with a built-in secret repository as a part of its secure vault implementation. This can be used to store encrypted secrets that are mapped to aliases. This alias allows you to have a plaintext reference to an encrypted password stored in the WSO2 secure vault, with the alias being used wherever the password is needed. For instance, some integration scenarios require database credentials to connect to a database. In that case, you could use an alias as IntegrationDB.password in place of the plaintext password and then let your configuration file resolve the actual password at runtime with the help of the WSO2 vault implementation.

Four Pillars of the WSO2 Secure Vault Implementation.

• Secret Repository — This stores aliases vs. their actual secrets in encrypted format (encrypted via a key in Keystore). By default, the WSO2 MI-1.2.0 implements the file-based secret repository, which comes as the cipher-text.properties file located in the /conf/security folder. Then, the environment secret repository that directly reads from the environment, and the file secret repository to read the secrets from a file resource.
• Secret Manager — This initializes the Secret Repository and the Keystore configured inside the secret-conf.properties file located at the /conf/security folder (the values are configurable).
• Secret Callback — This provides the actual password for a given alias. There is a SecretManagerSecretCallbackHandler, which is combined with the Secret Manager to resolve the secret.
• Secret Resolver — Any configuration builder that uses secret information within its own configuration file needs to initialize the Secret Resolver when building its own configuration. The Secret Resolver keeps a list of secured elements that need to be defined in the configuration file with secret aliases. Secret Resolver initializes the Secret Callback handler class, which is defined in the configuration file.

What’s New in Secrets?

Revamped Secure Vault Experience

When the WSO2 Micro Integrator is used to create integrated solutions with sensitive information, there will be two places where you might end up having your secrets defined;

• Server configuration file which is known as the deployment.toml, where you define all the server related configurations.
• Synapse configuration files in which you define your mediation logic.

In MI-1.1.0, there were two ways of managing secrets concerning the above two file types. The sensitive data defined in the deployment.toml was encrypted using the Cipher-tool and then stored in the cipher-text.properties file located at /conf/security folder. Similarly, securevault. sh(.bat) was supposed to be executed to encrypt the sensitive information in Synapse configurations and store them in the secure-vault.properties file located in /registry/config/repository/components/secure-vault folder.

However, having two different experiences for secret management could be somewhat tiresome and can be a bit overhead. Therefore, the latest WSO2 MI-1.2.0 uses only the Cipher-tool to manage sensitive information in both Server and Synapse configurations, leaving you only a minimal set of configurations to be done to secure your sensitive data.

Static Secrets vs Dynamic Secrets

With Micro Integrator 1.2.0, a new concept called Static secrets and Dynamic secrets have been introduced to offer users all the flexibility to define the secrets across multiple environments in a secure manner.

• Static secrets — In the context of Micro Integrator, these are sensitive data that are specified directly in configurations as plain-text value as below.

Here, your actual passwords are secret_1 and secret_2 and you define them after the respective alias; admin_password and db_password in the following format under the secrets header in deployment.toml.

[secrets] 
admin_password = "[secret_1]" 
db_password = "[secret_2]"

However, defining secrets as static secrets has its own limitations. Suppose you’re planning to use the WSO2 MI Docker image across different environments (Dev, UAT, Prod, etc.) and you have environment-specific secrets to be used in the configuration files. For instance, different admin passwords per environment. With only static secrets, you are required to update the secrets array in deployment.toml file and build a separate Docker image for each environment. Frustrating, right? So, this is why WSO2 MI introduces Dynamic Secrets into the play.

• Dynamic secrets — The sensitive data are not directly defined in the configurations. Rather, they are specified as Environment variables or System properties in the deployment.toml file. With Dynamic secret support, you will have the flexibility to dynamically update the secrets in each environment without replacing artifacts and configuration files. Here, you can encrypt the secrets using the Micro Integrator CLI and store them in the environment suitably. Then, you can refer to them in the deployment.toml file as follows.

[secrets] 
# as environment variable 
server_secret = "$env{dynamic_secret_1}"
# as system property
server_secret = "$sys{dynamic_secret_2}"

Additionally, WSO2 MI-1.2.0 now supports Docker secrets and Kubernetes secrets for your containerized deployments. But, unlike the environment variable and system property based dynamic secrets, Docker and Kubernetes secrets are not supported in server configurations. That means you cannot use the $secret{alias} function for these two types. The support is only given to Synapse configurations via the wso2:vault-lookup function as explained in the next section.

Enhanced Vault-lookup function

From WSO2 MI 1.2.0 onwards, the vault-lookup function has been enhanced to support Dynamic secrets in both VM and Container environments.

wso2:vault-lookup() function

In the enhanced function, the three parameters are,

• alias — Name of the secret
• type — FILE, DOCKER, ENV
• isEncrypted — true if the secret is first encrypted using Cipher-tool or false if otherwise

I’ve explained Docker secrets in my next blog and will be discussing File and Kubernetes secrets in future blogs. 😎 You can also refer to here for more details.

How to enable the WSO2 Secure Vault in WSO2 MI?

Step 1: Create a new Keystore (Optional)

WSO2 Secure Vault uses a Keystore to encrypt/decrypt your sensitive information defined across various configuration files. Therefore, WSO2 MI is shipped with a default Keystore (wso2carbon.jks), which is stored in the /repository/resources/security/ folder. However, if you intend to change this default Keystore, have a look here.

Step 2: Update carbon.xml with new Keystore values (Required if and only if step 1 is performed)

To perform secret encryption, the Cipher-tool refers to these Keystore details configured at “KeyStore” and “InternalKeyStore” sections in the carbon.xml. Therefore, if you’ve created a new Keystore as in the above step, then you need to update the relevant sections in the carbon.xml file with Keystore file location, Keystore type, Keystore password, Private Key alias, Private key password, before running the Cipher-tool.

Attention please!!! The recommended approach for this in WSO2 MI 1.2.0 would be defining the new Keystore details under the [keystore.primary] section in the deployment.toml and then start the server. During the server startup, the carbon.xml file will be updated with these new Keystore information. Then, the Cipher-tool will refer to these updated values in the carbon.xml during its execution.

Step 3: Define your secrets in the deployment.toml file under the [secrets] section.

[secrets] 
truststore_password = "[wso2carbon]" 

Step 4: Run the Cipher-tool

Navigate to <MI_HOME>/bin folder and execute the following command to run the Cipher-tool.

• On Linux — ./ciphertool.sh -Dconfigure
• On Windows — ./ciphertool.bat -Dconfigure. (Make sure you have Ant installed before executing this command)

Running the Cipher-tool will first encrypt any static secrets defined in the [secrets] section, and then enable all the secrets (static as well as dynamic) in the environment. If you check the deployment.toml, you can see that the plain text truststore_password has been replaced by an encrypted value similar to what you can see below.

[secrets]
truststore_password = "uftyeBgmUpEEhQCLPJQCNE0cKCJ8+vhLNieDwWseZ0+xBfAH/urrXW0//2XbN0//WFZ+sACgnHlpSNYj9pnuYCSJNpzrxCaO64Jrb0DALeFZghxL1NwHQf5YWWVV6kghUJxoQBG536TiR8IxBJF8SvTxgiyTT0kaeWtj5bnUVKYGkiVuP5R7vlaYXq6tDfZHyvrUHJ2SlrLKKtzkpFmx6B3nyvDmgdJQgJ5qSmdggyHDLy/JIFsJDvPmoVnh0CrunoWqzkYOMFlf4GI6y+N9A2g4L5wlM3A2fyRa9o4B+x4/sWTBH+okMFZhn32QK7CN2T6BsGhBErQQUXfyYjNjEw=="

Once the execution is done, you can see the secret-conf.properties file located at /conf/security folder is updated with the Keystore and Secret Repository configuration details as shown below. This Secret Repository is configurable through this file.

Step 5: Access secrets in configuration files

Now you can refer to the encrypted secrets in the configuration files as below.

• In Server configurations — Use the $secret{alias} function in place of the plain-text secret as below.

[truststore]                   
password = "$secret{truststore_password}"

• In Synapse configurations — Use the vault lookup function in place of the plain-text secret as shown below.

<log level="custom">   
    <property expression="wso2:vault-lookup('admin_password')" name="secret"/> 
</log>

Step 6: (Re)Start the WSO2-MI server

While the server is starting up, the values defined in the secret-conf.properties file will be used to initialize the secret repository and the decryption crypto. Also, you will be asked to provide the KeyStore and Private Key Password for the latter purpose.

Additionally, the encrypted values along with their alias will be copied to cipher-text.properties file located at /conf/security folder. After that, the values inside this file will be decrypted to actual plain-text values and stored in an in-memory map for reference.

Now, if you check the trust-store password in the carbon.xml, you’ll see that the password is replaced by the alias as shown below.

Throughout this article, we discussed the implementation details of the WSO2 secure vault, the new features and improvements related to secret support available in the latest WSO2 MI-1.2.0, and steps to enable the secure vault in WSO2 MI. I really hope you enjoyed and learned something from this article! Please like and follow if you did. Also, if you have any questions, please leave a comment below. Cheers! 🍻

Useful Resources

WSO2 Enterprise Integrator

Micro Integrator

Encrypting Passwords

WSO2 Integration Studio