This site contains the documentation that is relevant to older WSO2 product versions and offerings.
For the latest WSO2 documentation, visit

Working with Encrypted 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.

For more information on the Secure Vault implementation in WSO2 products, see Carbon Secure Vault Implementation.

In all WSO2 products, Secure Vault is commonly used for encrypting passwords and other sensitive information in configuration files. When you use WSO2 API-M, you can encrypt sensitive information contained in synapse configurations (i.e., mediation flow) in addition to the information in configuration files. For more information, see the following topics:

Encrypting passwords in configuration files

To encrypt passwords in configuration files, you simply have to update the and files that are stored in the <API-M_HOME>/conf/security directory and then run the Cipher tool that is shipped with the product. Go to the links given below to see instructions in the WSO2 administration guide:

Encrypting passwords for mediation flow

Before you begin
If you are using Windows, you need to have Ant ( installed before using the Cipher Tool.

The WSO2 API-M provides a UI that can be used for encrypting passwords and other sensitive information in synapse configurations. Follow the steps below.

  1. If you are using the Cipher tool for the first time in your environment, you must first enable the Cipher tool by executing the -Dconfigure command with the cipher tool script: 
    Note that the cipher tool uses the RSA encryption algorithm by default.

    1. Open a terminal and navigate to the <API-M_HOME>/bin directory.
    2. Execute one of the following commands to start the cipher tool:

      Do not combine the following commands and run them as a single command.

      • To use the cipher tool with the RSA encryption algorithm.

        • On Linux: ./ -Dconfigure

        • On Windows: ./ciphertool.bat -Dconfigure
          If you are using the Cipher tool for the first time, this command first initializes the tool for your product.

      • To use the cipher tool with any other encryption algorithm.

        • Support for any encryption algorithm other than RSA with the cipher tool is not supported out-of-the-box.

        • You need to get the latest product updates for your product to use this feature in the current version of WSO2 API-M. This feature is available as a product update from August 26, 2019 onwards.

          Note that you can deploy updates in a production environment only if you have a valid subscription with WSO2. Read more about WSO2 Updates.

        <encryption-algorithm>Make sure that the algorithm mentioned in the <API-M_HOME>/repository/conf/  file is the same as the value given when starting the cipher tool. Example:  RSA/ECB/OAEPwithSHA1andMGF1Padding

        • On Linux: ./ -Dorg.wso2.CipherTransformation=<encryption-algorithm>

          • Example: ./ -Dorg.wso2.CipherTransformation=RSA/ECB/OAEPwithSHA1andMGF1Padding

        • On Windows: ./ciphertool.bat -Dorg.wso2.CipherTransformation=<encryption-algorithm>

  2. When prompted, enter the primary key password, which is by default wso2carbon
    Enter the password and proceed.
  3. When prompted, enter the plain text password that you want to encrypt. 
    Enter the following element as the password and proceed.

    Enter Plain Text Value :admin

    Now, you will receive the encrypted value.

    Encrypted value is: 
  4. Start WSO2 API-M and sign in to the management console:
    1. Open a terminal and navigate to the <API-M_HOME>/bin directory.
    2. Execute one of the following scripts:
      • On Windows: wso2server.bat --run
      • On Linux/Mac OS: sh
    3. Sign in to the management console.
  5. Select Browse under Resources to access the registry browser and go to the  /_system/config/repository/ components/secure-vault location.

  6. Add the aliases and the encrypted value as a property.

Encrypting passwords in api-manager.xml file

The api-manager.xml file does not contain any plaintext passwords. Therefore, encrypting the plaintext passwords in user-mgt.xml file as shown in Encrypting Passwords with Cipher Tool is sufficient. We recommend having the same admin user on all nodes in a clustered setup.

However if you need to use an alias to encrypt passwords in the <APIM_HOME>/repository/conf/api-manager.xml file using the cipher tool, do the following.

To derive the alias, ignore the root XML element (i.e. <APIManager> ) in the api-manager.xml file. Denote the subsequent XML elements separated by a dot (.), according to the hierarchy. You can derive the alias AuthManager.Password from the xml example given below.

<APIManager xmlns:svns="http://org.wso2.securevault/configuration">

Following are some sample aliases derived for other passwords in the api-manager.xml file


Using encrypted passwords in mediation flow

To use the alias of an encrypted password in a mediation flow, you need to add the {wso2:vault-lookup('alias')}custom path expression when you define the mediation flow. 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 mediation flow can now be retrieved by using the  {wso2:vault-lookup('alias')} custom path expression to logically reference the password mapping.