Vault

Hero image for Vault

At Nimble, unsurprisingly, we manage a lot of secrets: account credentials, API keys, certificates…

Those secrets are important. They safeguard the integrity of many kinds of data, both internally and for our clients. It is our responsibility to manage those secrets carefully.

Meet Vault

Vault is a highly secure secrets management application. It features different levels of protection and all the secrets stored in it are encrypted at rest.

If you’re looking for the Vault setup documentation or need details about groups and policies, head 👉 this way

Where is the Vault?

Our Vault is accessible at https://vault.nimblehq.co:8200.

How to Access Vault?

All Nimble team members and only Nimble team members can access Vault with their username and password. Needless to say that your credentials are super secret.

Using Vault

Vault GUI

Vault has a straightforward GUI that you will be using most of the time. It works similarly to a more traditional password manager: use your login and password to sign in and browse the secrets in the Vault.

It differs in some ways though.

Vault is not a password manager, so you won’t find a list of entries with a username and a password field.

Instead, the secrets in Vault each have their folder.

This also means that Vault can store more than just passwords.

For each entry, you can find and add any other relevant secret information (API keys, certificates, etc.).

Adding Secrets

To add a new secret to Vault, browse to the right location, and click the “Create secret” link in the top right corner.

Create secret

You will then be prompted to give your secret a name and to add any number of key-value pairs.

Adding a secret

Vault CLI

While the GUI which Vault provides will be enough for daily usage of the Vault, some operations can only be done via the CLI.

Vault CLI

Most of the cases where the CLI will be needed are administration use cases such as:

  • Re-rolling keys in case of security breach,
  • Querying specific data for batch updating.

There is one use case that every user should know about: changing your password.

CLI Standalone App

The built-in CLI tool only allows for a limited number of operations. In order to gain access to all of the CLI operations, you’ll need to download the standalone CLI application from Vault’s website: https://www.vaultproject.io/downloads.html.

Setting Up the CLI Tool

After you’ve downloaded the Vault CLI tool, there is a couple of steps that you need to take before being able to connect to the Vault.

  • Move vault to /usr/local/bin
mv ~/Downloads/vault /usr/local/bin
  • Export the Vault address in your bash profile
echo export VAULT_ADDR=https://vault.nimblehq.co:8200 >> ~/.bashrc

Most terminal replacement applications like zshell would read from it so it should work in all cases.

You can now use Vault CLI and access our Vault. For help with the Vault commands, type vault -help.

Before doing any operation though, you need to authenticate with your username and password. To do so, type in:

vault login -method=userpass username={username}

Don’t forget to replace {username} with your actual username. The CLI will then prompt for your password.

Vault Token Helper (Optional)

In order to avoid having to authenticate every time you want to use Vault, you can store your token locally. Vault will then read this token for every request you make.

To get your token, you need to log in with the method detailed above (the userpass method). Your token will show up in the console after a successful login.

Vault User Token

Once you found your token, export it to your bash profile:

echo export VAULT_TOKEN=xxx-xxx-xxx-xxx-xxx >> ~/.bashrc

From here on out, you can simply call vault from the console without the need to authenticate.

Changing Your Password

Changing a user password can be done from the built-in CLI interface and doesn’t require the standalone CLI application.

One of the most basic things that you will want to do is to change your account password. It can’t be done from the GUI, though. For that, you’ll need to use Vault’s built-in CLI.

Open the CLI panel and type the following:

vault write auth/userpass/users/{username} password={new_password}

Make sure to replace {username} by your actual username and {password} by the password you want to use.

Access Level

In the pursuit of a failproof secrets management system, all users don’t have the same access level. Our Vault has specific policies in place to make sure that each user has access to everything they need and not more.

If the secret that you’re looking for doesn’t show up in Vault, either it’s not there, or you don’t have access to it.

If you need a secret that you don’t have access to, send a request in the Slack channel #vault-requests specifying the Vault folder you need access to. We always try to make our policies as fine-tuned as possible, but there are so many things in Vault that it’s easy to miss one.

Access permissions are updated synchronously with squad rotations to provide access to only what is required at any given time. As a consequence, when rotating to a new project, you will gain access to the new project credentials but you will not have access to the previous project credentials anymore.

When to Update Vault?

If you’re wondering whether or not you should add a secret to Vault, fear not. The following flowchart will clear up any doubt you may have.

Vault add flowchart

How to Add Secrets

It’s Vault’s flexibility that makes it so useful in safely keeping all sorts of secrets. The downside is that, without following certain common rules, it can become messy.

Secrets Naming

Whenever possible, the secret name should be the name of the tool/Saas/application it relates to.

If not applicable, the name should be as clear and straightforward as possible. Remember that colleagues will come looking for that secret; let’s make it easy for them to find it.

Keys Naming

Similarly to the secret name, the keys for all key-value pairs should be simple and clear. Don’t use cryptic terms, use simple words. Just like with coding, others shouldn’t need a manual to understand how your secrets work ;)

Storing Username and Passwords

When storing a username and password pair, we follow a pretty standard convention:

  • The username’s key should be username
  • The password’s key should be password

Example

Let’s add the username and password for Heroku using our secret naming and keys naming conventions.

  • Secret name: Heroku
  • Path: nimble/general/Heroku
Key Value
username XXXXX
password XXXXX