Skip to main content

Load secrets into the environment

With 1Password CLI, you can provision secret references as environment variables to simplify the process of creating multiple configurations for different environments. Secret references allow you to edit your secrets in 1Password without having to make any changes to your configuration settings or put any plaintext secrets in code.

After you've set your environment variables to secret references, you can use op run to provision an app with the secrets it requires.

Many applications that follow the popular 12-Factor App guidelines source their secrets from the environment.

tip

We recommend using 1Password Service Accounts to follow the principle of least privilege. Service accounts support restricting 1Password CLI to specific vaults, so that processes in your authorized terminal session can only access items required for a given purpose.

CAUTION

You should assume that processes on your computer can access the environment of other processes run by the same user. Be aware of this when supplying secrets through environment variables.

Requirements

Before you can load secrets into the environment, you'll need to:

  1. Sign up for 1Password.
  2. Install 1Password CLI.
  3. Store the secrets you want to provision in your 1Password account.

Step 1: Copy secret references

  1. Open and unlock the 1Password desktop app.
  2. Open the item where the secret you want to reference is stored.
  3. Click next to the field that contains the secret you want to reference, then click Copy Secret Reference.
An item in 1Password with the Copy Secret Reference option selected.An item in 1Password with the Copy Secret Reference option selected.

If a field doesn't have the Copy Secret Reference option, you can use the secret reference syntax to write your own.

Step 2: Pass the secrets to the application

To provision an app with the secrets it needs, map the secret references to the appropriate environment variables, then use op run to pass the secrets to the application.

There are two ways to do this:

Export environment variables

You can individually export environment variables as secret references from the command line.

  1. Export the necessary environment variables:

  2. Run op run -- with your command for starting the app:

Use environment (.env) files

Environment files allow you to define multiple (secret) environment variables with KEY=VALUE statements separated by a newline. These files have the .env extension.

You can check environment files into source control and use the same environment everywhere. For example, if you use environment files for your test secrets, you can run your tests both locally and in CI without having to provision the secrets separately.

prod.env

To use environment files with op run, specify the path to the environment file with the flag --env-file:

Environment file syntax rules

The .env file parsing engine follows the following rules:

  • Environment variables are defined as KEY=VALUE statements separated by a newline.

  • Variables can span multiple lines if they are enclosed in either ' or ":

  • Empty lines are skipped.

  • Lines beginning with # are treated as comments. Comments can also be placed inline after KEY=VALUE statements.

  • Empty values become empty strings. For example, EMPTY= will set the environment variable EMPTY to the empty string.

  • If a value is surrounded by single or double quotes, these quotes do not end up in the evaluated value. So KEY="VALUE" and KEY='VALUE' both evaluate to KEY and VALUE.

  • Occurrences of $VAR_NAME or ${VAR_NAME} are replaced with their respective value from the environment.

  • A variable defined in a .env file can be referred to later in the same file:

  • Special characters can be escaped with \. For example, MY_VAR = "\$SOME_VAR that is not actually replaced." results in the following value for MY_VAR: $SOME_VAR that is not actually replaced..

  • Inner quotes are maintained, so JSON={"foo":"bar"} evaluates to JSON and {"foo":"bar"}.

  • Variables do not get replaced in values that are enclosed in single quotes. So KEY='$SOME_VAR' evaluates to KEY and $SOME_VAR.

  • Template syntax can be used in the VALUE to inject secrets. The KEY can only contain template variables.

  • Template parsing is performed after .env file parsing, so you cannot use the former to construct the latter.

  • Leading and trailing whitespace of both KEY and VALUE segments are ignored, so KEY = VALUE is parsed the same as KEY=VALUE.

  • Single and double quoted values maintain both leading and trailing whitespace, so KEY=" some value " evaluates to KEY and  some value .

  • These files should use UTF-8 character encoding.

Step 3: Differentiate between environments

If you have different sets of secrets for different environments, you can use a single environment file to pass the appropriate secrets to the application.

To do this, make sure you structure your 1Password secrets in the same way across all your environments. For example: dev/mysql/password and prod/mysql/password.

Then, include an externally set variable ($VARIABLE_NAME) in place of the vault name for each secret in your environment file. This will allow you to specify which set of secrets you use with each environment.

For example, in the following .env file, $APP_ENV is the externally set environment variable:

app.env

To use the set of secrets from the dev vault to deploy an app in the development environment:

Next step: Run in production

Now that the application works with the right configuration locally, you can use 1Password CLI with a 1Password Connect Server to provision secrets in production environments. You can also set up 1Password CLI in CI, and define your secret references alongside other configurations.

Learn more

Was this page helpful?