Use a vault for secrets

Need to provide secrets such as credentials to your robot? You can use a vault. Both local and Control Room vault is supported.

To better show you how to set up the vault, we have provided an example robot for you to play with.

Control Room vault - the preferred way to store secrets

The safest way to store secrets is to set up the vault in Control Room. You can use the Control Room vault when running your robots locally using VS Code with Robocorp extensions!

Configure your vault in Control Room in the relevant workspace using the UI. The name of the secret should match the name used in your code that reads the secret, for example, credentials. Provide the secrets as key-value pairs.

Local vault file - an alternative way for storing local secrets

If you don't want to use the Control Room vault for any reason, you can set up a local vault file.

Create a vault.json file outside your repository, for example, in your home directory (/Users/<your-username>/vault.json).

Never commit your vault file in version control.

Provide your vault values in the vault.json file, for example:

{
  "credentials": {
    "username": "some-username",
    "password": "some-password"
  }
}

By doing so, you have created a secret called credentials.

You can use any name for the vault file and the keys in the file.

Configure file vault support

When running in Control Room, your robot will automatically use the Control Room vault without the need for any configuration.

When running your robot locally and using a local vault file, you need to tell the library that it should read the secrets from a local file. You do this by setting the relevant environment variables in the devdata/env.json file, which is included in the example.

Note: rpaframework version 14.1.1 or newer recommended! There were some naming changes to vault functionality starting from version 11.

Edit the file setting the RPA_SECRET_FILE variable so that it points to the vault.json file you created in the previous step:

{
  "RPA_SECRET_MANAGER": "RPA.Robocorp.Vault.FileSecrets",
  "RPA_SECRET_FILE": "/Users/<your-username-here>/vault.json"
}

Windows: Escape file paths like this: "C:\\Users\\<your-username-here>\\vault.json"

This way, with no additional code changes, your robot will work both locally and in Control Room.

NOTE FOR RCC USERS: Robocorp VS Code extensions will automatically pick up the devdata/env.json file. While using RCC locally, you have to explicitly point to the file using the -e argument like so: rcc run -e devdata/env.json.

Read the vault values - Option 1: Robot script

We added the RPA.Robocorp.Vault library in the *** Settings *** section:

*** Settings ***
Library    RPA.Robocorp.Vault

We use the Get Secret keyword from the RPA.Robocorp.Vault library to fetch a secret by name credentials and store the secret to a variable. We can then access the properties of the secret by their name:

*** Tasks ***
Get and log the value of the vault secrets using the Get Secret keyword
    ${secret}=    Get Secret    credentials
    # Note: In real robots, you should not print secrets to the log.
    # This is just for demonstration purposes. :)
    Log    ${secret}[username]
    Log    ${secret}[password]

Read the vault values - Option 2: Python library

In the file variables/variables.py, we import the RPA Framework vault library and read the values from the vault:

from RPA.Robocorp.Vault import Vault

_secret = Vault().get_secret("credentials")

USER_NAME = _secret["username"]
PASSWORD = _secret["password"]

Any variables in a variables file that don't start with an underscore are exposed to Robot Framework

After this, ${USER_NAME} and ${PASSWORD} variables can be accessed in the robot script, as we see here:

*** Tasks ***
Get and log the value of the vault secrets using the imported variables file
    # Note: In real robots, you should not print secrets to the log.
    # This is just for demonstration purposes. :)
    # This works because we are importing the `variables.py` file:
    Log    ${USER_NAME}
    Log    ${PASSWORD}

The RPA Framework vault library handles both local and Control Room vault. It looks for the RPA_SECRET_MANAGER environment variable and defaults to Control Room vault.

Video instructions

Security notes

Your secrets are safely encrypted in Control Room. See the technical architecture and security article for more information regarding Control Room security.

Vault administration and governance

For larger teams and enterprises, how you decide to use and govern the Control Room vault is an important consideration because granting the administrator or developer workspace role allows a user to see all secrets stored within the workspace's vault. Generally, most enterprise compliance programs frown upon sharing passwords between team members, because it reduces transaction accountability. In addition, any robot runs with access to the Control Room vault, so there is risk that a bad actor could develop a bot to extract secrets from the vault.

Controlling these risks requires implementing a few key controls, such as the following:

• Workspaces should be configured to segregate production robots from test/development robots.
• Production secrets should be placed into the vault by appropriate administrators (such as IT System Administrators).
• Test/development workspaces should not contain any secrets associated to production systems.
• Test/development systems should not share credentials with production systems. In some cases, SSO may exist for both production and test systems. In those cases, it is best practice to create unique accounts which only have access in the test system (e.g. [email protected]).
• Developers should not have access to production workspaces. They can have limited access as long as it is read-only and does not include the ability to read from the vault. The default operator role works for this.
• Complex robots should utilize devoted robot user service accounts which have only those permissions needed to perform the functions associated with the automation. In some cases, it may make sense to create shared team robot users with access similar to all users within a specific business user team.
• Less complex robots, and/or those developed by citizen developers, may need to utilize personal user accounts. In these cases, to reduce the risk of shared passwords, private workspaces can be created for each user.

With regards to more complex automation use cases where robot user service accounts are used, there is an additional consideration related to license costs. If the robot needs to log into a system which charges a license cost per user, it is important to consider that cost and reduce it where possible. You must consider whether it is more important to create individual robot service accounts with limited access, or create fewer service accounts with greater access across the environment to reduce license costs. The exact balance is up to you and your own risk appetite.