Skip to content

Encrypting Synapse Passwords

All WSO2 products are shipped with a Secure Vault implementation that allows you to store encrypted passwords that are mapped to aliases. This approach allows you to use the aliases instead of the actual passwords in your configurations for better security. For example, some configurations require the admin username and password. If the admin user's password is "admin", you could use UserManager.AdminUser.Password as the password alias. You will then map that alias to the actual "admin" password using Secure Vault. The WSO2 product will then look up this alias in Secure Vault during runtime, decrypt and use its password.

Encrypting passwords for synapse configurations

Follow the steps given below:

  1. Open a command terminal and navigate to the MI_HOME/bin/ directory.
  2. If you are using the Cipher tool for the first time in your environment, you must enable the Cipher tool by executing the -Dconfigure command with the Cipher tool script. Execute the following command to initialize the cipher tool:

    OS Command
    Linux bash -Dconfigure
    Mac OS ./ -Dconfigure
    Windows ciphertool.bat -Dconfigure


    If you are using Linux, make sure to run the script using bash as explained above.

  3. Execute the following command to initialize secure vault:


    If you are using Windows, be sure to update the securevault.bat file with the following configuration before encrypting passwords.

    set CARBON_CLASSPATH=.\conf
        FOR %%c in ("%CARBON_HOME%\wso2\components\plugins\*.jar") DO (
        set CARBON_CLASSPATH=!CARBON_CLASSPATH!;".\wso2\components\plugins\%%~nc%%~xc")

    OS Command
    Linux/Mac OS sh
    Windows securevault.bat

  4. You can then enter the secret alias (vault key) for the password that you want to encrypt. For example, enter 'PasswordAlias'.

    [Please Enter the Secret Alias] PasswordAlias
  5. In the next step, enter the password of the keystore that is used for secure vault in the product. If the default product keystore is used, the password is 'wso2carbon'.

    [Please Enter Primary KeyStore Password of Carbon Server : ]
  6. Specify the plain text password that should be encrypted. By default, you are required to specify a string value with 5 to 30 characters as the password.


    If you want to change the default password requirement (password length and character composition), add the following parameter in the deployment.toml file (stored in the <MI_HOME>/conf directory) and specify a regex value with the requirement.

    org.wso2.SecureVaultPasswordRegEx = "any_valid_regex"

    [Enter Plain Text Value : ]
    [Please Enter Value Again : ]

The encrypted password is stored in the file as shown below. This file is stored in the <MI_HOME>/registry/config/repository/components/secure-vault/ directory.

#Secure Vault keys for micro integrator
#Thu Sep 27 14:38:33 IST 2018


If you're running securevault on a fresh Micro Integrator distribution, you may have to manually create the file inside the <MI_HOME>/registry/config/repository/components/secure-vault/ directory to avoid the error mentioned in MI-1060

Using encrypted passwords in synapse configurations

To use the alias of an encrypted password in a synapse configuration, you need to add the {wso2:vault-lookup('alias')} custom path expression when you define the synapse configuration. For example, instead of hard coding the admin user's password as <Password>admin</Password> , you can encrypt and store the password using the AdminUser.Password alias as follows: <Password>{wso2:vault-lookup('AdminUser.Password')}</Password>.

This password in the synapse configuration can now be retrieved by using the {wso2:vault-lookup('alias')} custom path expression to logically reference the password mapping.