This site contains the documentation that is relevant to older WSO2 product versions and offerings.
For the latest WSO2 documentation, visit https://wso2.com/documentation/.
Working with Passwords in the ESB profile
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.
Go to the WSO2 administration guide for more information about the Secure Vault implementation in WSO2 products.
In all WSO2 products, Secure Vault is commonly used for encrypting passwords and other sensitive information in configuration files. When you use the ESB profile of WSO2 EI, you can encrypt sensitive information contained in synapse configurations in addition to the information in configuration files. See the following topics:
Encrypting passwords in configuration files
To encrypt passwords in configuration files, you simply have to update the cipher-text.properties
and cipher-tool.properties
files that are stored in the <EI_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 using the automated process.
- Encrypting passwords using the manual process. This is relevant when the location of the configuration files (that contain the elements to be encrypted) cannot be specified using an xpath in the
cipher
-tool.properties
file. - Changing already encrypted passwords.
- Resolving already encrypted passwords.
Encrypting passwords for synapse configurations
Before you begin, be sure that your registry database has write-access enabled. Open the registry.xml
file (stored in the <EI_HOME>/conf/
directory) and ensure that the <readOnly>
element is set to false
as shown below.
<currentDBConfig>wso2registry</currentDBConfig> <readOnly>false</readOnly> <enableCache>true</enableCache> <registryRoot>/</registryRoot>
This is necessary because the passwords you encrypt using the management console of the ESB profile are written to the registry DB. If the registry does not have write-access enabled, the required functions on the management console will be disabled.
The ESB profile of WSO2 EI provides a UI that can be used for encrypting passwords and other sensitive information in synapse configurations. Follow the steps below.
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 command used for initializing the Cipher tool is the same command that is used for encrypting the passwords of configuration files.
- Open a terminal and navigate to the
<EI_HOME>/bin
directory. - Execute one of the following commands:
On Linux:
./ciphertool.sh -Dconfigure
On Windows:
./ciphertool.bat -Dconfigure
- The following message will be prompted: "[Please Enter Primary KeyStore Password of Carbon Server :]". Enter the keystore password (which is "wso2carbon" for the default keystore ) and proceed.
If the script execution is successful, you will see the following message: "Secret Configurations are written to the property file successfully".
- Open a terminal and navigate to the
- Start the ESB profile of WSO2 EI and sign in to the management console:
- Open a terminal and navigate to the
<EI_HOME>/bin
directory. - Execute one of the following scripts:
- On Windows:
integrator.bat --run
- On Linux/Mac OS:
sh integrator.sh
- On Windows:
- Sign in to the management console.
- Open a terminal and navigate to the
- Go to Manage -> Secure Vault Tool and then click Manage Passwords on the Main tab of the management console. The Secure Vault Password Management screen appears.
- Click Add New Password to encrypt and store, and then specify values for the given fields as shown below. This creates a new password entry in the registry, which is encrypted with the alias (Vault Key) that you specify.
- Vault Key: The alias for the password.
- Password: The actual password.
- Re-enter password: The password that you specified as the actual password.
- Click Add, and the password will be encrypted.
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.
Updating the password validation
This is available only as a WUM update and is effective from 12th July 2018 (2018-7-12). For more information on updating WSO2 Enterprise Integrator, see Getting Started with WUM.
The default expression used for password validation is ^[\\S]{5,30}$
. This allows the password to have 5 to 30 characters.
If you want to change the expression that is used to validate the password, you need to add the org.wso2.SecureVaultPasswordRegEx
system property to the <EI_HOME>/conf/carbon.properties
file.
Example:
org.wso2.SecureVaultPasswordRegEx=^[\\S]{5,60}$