Automation V3: Secrets Management and Encryption
Automation honors the following principles with regard to passwords and secrets:
- Automation never exposes secrets in clear text in its UI or log files.
- Automation never transmits secrets in clear text over networks. This includes localhost connections.
- Automation does not rely on encryption keys that are built into the software (as these can be extracted by reverse compilation). These are always used in combination with a user-supplied secrets password that is used to salt the encryption.
- Secrets passwords are never stored by Automation but instead supplied by the user when required.
Secret types
Automation needs to store various secrets depending on the type of connection.
- Passwords are required for Salesforce, secured websites, Email and Database connections.
- Security Tokens and Client Secrets are required for certain types of Salesforce connection.
Browser providers
User account passwords are required to connect to third-party browser and mobile device hosting services such as Perfecto Mobile and SauceLabs.
Test environments
Test Environments allow you to specify alternate details for connections in Provar:
- The Test Environment is built into the tool.
- Additional Test Environments can be defined in the Settings view.
When a new connection is created, details are always supplied for the Test Environment. Alternate details can then be supplied for specific Test Environments, if desired.
For example, a SalesUser connection can be defined that:
- Connects using UatSalesUser / password1 for the Test Environment
- Connects using ProdSalesUser / password2 for the PROD Test Environment.
At runtime, Provar uses any specific connection details for the active Test Environment, failing which the connection details are used.
Storage
Provar stores all secrets in centralized .secrets files. These are stored at the root of the Test Project and can either be encrypted or in plain text.
The main .secrets file contains all secrets for the Test Environment and also the secrets for Test Environments that do not have their own encryption passwords.
Where Test Environments have been encrypted with their own passwords, their secrets are stored in a separate .secrets file.
External secrets management
Some customers would prefer not to store their .secrets files in their Source Control Repositories (e.g. GitHub).
To accommodate this, Provar’s ANT task allows secrets to be supplied via specially named environment variables. This allows the secrets to be managed outside of Provar, for example, by the password plugin for Jenkins.
Encryption
Provar allows secrets to be encrypted for entire Test Projects and also for individual Test Environments. This allows a PROD Test Environment, for example, to have its own secrets password that is only known to selected Provar users.
These approaches can be mixed and matched as follows:
- All secrets can be unencrypted. This is the default state for newly created Test Projects.
- The main .secrets file can be unencrypted and selected Test Environments encrypted with their own secrets passwords.
- The main .secrets file can be encrypted with the main secrets password and selected Test Environments encrypted with their own secrets passwords.
Encryption scheme
The encryption is done via the Jasypt open-source library using the user-supplied secrets password as the encryption salt:
- If the Test Project is encrypted then all secrets for the Test Environment are encrypted in the main .secrets file together with the secrets for any unencrypted Test Environments.
- If a Test Environment is encrypted then its secrets are encrypted in a separate .secrets file.
Secrets Password Requirements
Secrets passwords need to meet the following requirements.
- Must be at least 8 characters long
- Must contain an uppercase character
- Must contain a lowercase character
- Must contain a numeric character
- May contain special characters.
Enabling encryption
Newly created (and pre-existing) Test Projects are not encrypted by default:
The Encryption Controls located in Settings > Preferences allow your Test Project to be encrypted.
After selecting Encrypt Secrets, a modal will appear asking for your password for encryption.
Once your password is confirmed, you should see a success message.
After successfully Encrypt .secrets file looks like this with encrypted format.
Note: The .secrets file cannot be accessed directly from within Provar Automation V3, but must be opened using Notepad, Visual Studio Code, or some other text editor.
Encryption management
Once encrypted, the following encryption options are available in Settings > Preferences > Encryption Controls.
Change Encryption Password
Change Encryption Password allows the secrets to be re-encrypted with a new password. Change Encryption Password requires the existing password to be entered.
Lock Encryption
This will add an additional layer of protection to your Test Project.
Change Lock Password
Change Lock Password allows the Lock to be re-encrypted with a new password. Change Lock Password requires the existing password to be entered.
Reset Secrets Encryption
For Test Projects, it removes the encryption and sets all secrets to empty values.
The existing password is not required for Reset Secrets Encryption.
Secrets password entry in Automation
When a Test Project is opened in Automation the user is prompted for the main secrets password if the Test Project is encrypted. Automation shuts down if no valid password is supplied after three attempts.
Switching to encrypted test environments
The user is subsequently prompted for Test Environment passwords if:
- They select an encrypted Test Environment in the Settings Toolbar. The Test Environment is automatically selected after three unsuccessful attempts.
- They attempt to edit the alternate connection details for an encrypted Test Environment. The edit dialog does not open after three unsuccessful attempts.
- When they change the Test Environment on for an alternate connection to an encrypted one.
Invalid password attempts
Automation shuts down if the main secrets password is not supplied within 3 attempts.
- Automation automatically switches to the Test Environment if the password for an encrypted Test Environment is not supplied within three attempts.
- Automation does not allow alternate connection details to be modified if the password for an encrypted Test Environment is not supplied within three attempts.
- Automation prevents the Test Environment for alternate connection details being modified if the password for an encrypted Test Environment is not supplied within three attempts.
Note:
- Because Automation has no reliable way of storing invalid password attempt counters, these counters are reset when Test Projects are re-opened.
- The number of unsuccessful password attempts is tracked independently for each Test Environment until the Test Project is reopened.
- Secrets password entry under ANT
Main secrets password
The main secrets password can be supplied in two different ways when running under ANT:
- Via the secretsPassword property of the TestRunner task.
- Via the ProvarSecretsPassword environment variable.
Test environment secrets passwords
The secrets passwords for Test Environments can be supplied:
- Via the testEnvironmentSecretsPassword property of the TestRunner task.
- Via the ProvarSecretsPassword environment variable.
Example build file with an encrypted Test Environment and encrypted Test Project:
Example of a successful test execution via ANT:
Invalid password processing
Automation validates the Test Environment passwords first, then the test project passwords when the ANT task starts. If either password is invalid then:
- No tests are run
- An error outcome is returned.
Example of an incorrect or missing test project secrets password:
Example of an incorrect or missing test environment secrets password:
Lock Encryption User Flow
To Lock Encryption
Considering the project or environment is already encrypted.
- Users will see a Lock Encryption option from the Encryption Controls in the Preferences view.
- Users have the option to lock the Encryption using a separate password.
Unencrypt Locked Project
Once the project is encrypted and locked, it can be shared with other users.
- When other users import the project, they must enter the password to access and use it, following a flow similar to our current process.
- The Remove Secrets Encryption option will always be enabled for the users if the project is Encrypted.
- When users attempt to unencrypt the project, they will be prompted to provide both Encryption and Lock passwords.
It can not be unencrypted if both passwords are not provided.
To Change Lock Password
- Choose Change lock Password from the Encryption Controls section in the Preferences view:
Only the users who have the Encryption password will be able to change the lock password.
