SecretHub Best Practices

The Best Practices on this page give you a head-start in using SecretHub efficiently and securely.

Repository Structure

Using SecretHub effectively for bigger projects begins with a solid repository structure. This can seem daunting at first, but if you apply a few basic principles, you can easily keep things organized:

• Use a repository for each project. A project is defined as a logically separated part of your infrastructure. For example, if you have multiple products, each of them probably deserves their own repository.
• Use directories to create structure within repositories.
• Use the desired access control as a guidance for creating directories. For example, if you want different access rules for you production and development environment, you can create a directory dev/ and prod/ in the root of the repository.
• Combine all secrets for a service in a single directory. For example, all secrets for your api-server go into a single directory.
• Try to not to nest directories deeper than 3 levels, so this would be the maximum org/repo/dir1/dir2/dir3/secret. This is not enforced by SecretHub, so if you have a good reason, feel free deviate from this.
• If you use a system that does not support having different credentials for each service that needs access to it, place the secrets in a directory named shared/. In this directory, create a subdirectory for each of these systems. For an example, see the next section.

Example

We applied these guidelines on the SecretHub organization ACME that has several products, for which one of them the repository structure is shown below:

acme/
├── productivity-tool/
│   ├── dev/
│   │   ├── api-server/
│   │   │   ├── analytics-key
│   │   │   ├── db-username
│   │   │   └── db-password
│   │   ├── invoice-sender/
│   │   |   └── sendgrid-token
│   │   └── shared/
│   │       └── legacy-billing-system/
│   │            ├── username
│   │            └── password
│   └── prod/
│       ├── api-server/
│       │   ├── analytics-key
│       │   ├── db-username
│       │   └── db-password
│       ├── invoice-sender/
│       |   └── sendgrid-token
│       └── shared/
│           └── legacy-billing-system/
│                ├── username
│                └── password
└── spin-off-project/
    └── ...

ACME has a productivity-tool that has prod and a dev environment. They run two services: an API server and a serverless job that sends invoices. Both of them have a set of unique secrets. However, they also need access to the legacy-billing-system. This system only supports 1 username and password. Therefore these credentials are placed in the shared/ directory.

The service account used for the API server on prod has access rules that provides access to two directories:

acme/productivity-tool/prod/api-server
acme/productivity-tool/prod/shared/legacy-billing-system

Naming

You have quite some freedom in choosing names for secrets and directories: they each can be up to 32 characters long and contain letters, numbers, dashes, underscores and dots.

To keep things consistent, we do have some recommendations:

• Make names descriptive, but no longer than necessary. For example, use password instead of secret-password.
• Only use abbreviations where they are generally used within your team. So db instead of database generally is fine, but don’t invent st to save some characters on stripe-token.
• It is recommended to use either snake_case or kebab-case, but whichever you choose, it is important to stay consistent.
• Even though paths are case-insensitive, it is recommended to only use lowercase letters to maintain visual consistency.

Credentials

Credentials allow SecretHub to perform authenticate users and services and unlock the power of end-to-end encryption. Because of their power, they require some care. Below you can find recommendations for the usage of credentials for your user account and service accounts.

User Account

As a user, you need a user credential on every machine (e.g. your laptop and a desktop) you want to access SecretHub from. Here are some recommendations for using them:

• Don’t copy a single user credential to multiple machines, but create one credential per machine you use. This allows you to revoke the access from individual machines if you were to lose one. See this page on how to setup credentials for multiple machines.
• Use a passphrase to protect your credentials. If you have not done so already, use secrethub config update-passphrase to set a passphrase for the credential you are currently using. It is called a pass phrase for a reason: using a lengthy phrase not only strengthens security, but it is also relatively easy to remember. Using the same passphrase for credentials on different machines is okay, but it is advised not to use the same passphrase for any other services.
• Create a backup code and store it safely offline, for example in a safe deposit box. You can create backup code with secrethub credential backup. Be aware that because of the end-to-end encryption model SecretHub uses, we are unable to restore access to repositories and secrets in case you lose all your credentials.

Service Accounts

Service accounts are used for non-human interaction with SecretHub. They are created by creating a new service account with the secrethub service command. Every service account has one unique credential. Here are some recommendations for service accounts and their credentials:

• Use a unique service account for every place where you use SecretHub. So do not reuse the same service account for a CI Pipeline and a serverless function. This allows you to give every service account the minimum access it needs and allows for per-service revocation in case this would be necessary.
• Set a description for the service account by providing the --description flag to the init command. By doing this, you can always easily find which account is used for what purpose.
• For supported platforms, use an Identity Provider instead of a key credential. This gives you the benefit of not having to manage a key for these service accounts. Currently we have an Identity Provider for AWS. More Cloud Service Providers will be supported soon.