What is a secret reference?

You can use secret references to load information from your 1Password vault into environment variables, configuration files or scripts without exposing any sensitive secrets in plain text.

A secret reference is a URI that looks like this:

op://<vault-name>/<item-name>/[section-name/]<field-name>

To replace a secret reference with their underlying value at runtime, you can use one of:

• op read
• op run
• op inject

Ok, how?

1. Copy secret reference

You can obtain the secret reference in a few ways.

Use the 1Password desktop app

Use the 1Password CLI

Use the op item get command:

2. Replace plaintext secrets with secret references

In your code, use secret references instead of plaintext secrets. So instead of something like this:

GITHUB_PERSONAL_ACCESS_TOKEN="ghp_abc12345678"

Do this instead:

GITHUB_PERSONAL_ACCESS_TOKEN="op://Development/GitHub/credentials/personal_token

3. Resolve the secret references

You have three options for replacing the secret references with the actual secrets at runtime:

• op read: this will write the secrets to stdout or to a file.
• op run: this will pass secrets as environment variables to a process.
• op inject: this will inject secrets into configuration files or scripts.

1. op read

Do this to print the secret to stdout:

op read op://development/GitHub/credentials/personal_token

You can also use the --out-file flaf to write the secret to a file instead of to stdout:

op read --out-file token.txt op://development/GitHub/credentials/personal_token

2. op run

Set your env variables to secret references:

export DB_USER="op://app-dev/db/user"
export DB_PASSWORD="op://app-dev/db/password"

Then assuming you have a app.js file that reads process.env.DB_USER and process.env.DB_PASSWORD, you can wrap your run script with op run:

op run -- node app.js

1Password will scan the environment variables for secret references, replace them with the values from 1Password and run the command (node app.js in this example) in a subprocess with the secrets made available as environment variables for the duration of the subprocess.

You can also use op run with env files by writing your env files like so:

DB_USER="op://app-dev/db/user"
DB_PASSWORD="op://app-dev/db/password"

Then running your script with op run --env-file:

op run --env-file="./node.env" -- node app.js

3. op inject

You can use op inject to replace secret references in a file or script with the secrets they reference.

To replace secret references in a file, you might have a config.yml.example file like this:

database:
    host: http://localhost
    port: 5432
    username: op://prod/mysql/username
    password: op://prod/mysql/password

And then use op inject to create a new config.yml file with the actual secrets:

op inject --in-file config.yml.tpl --out-file config.yml

To replace secret references in a shell command, you can do this:

echo "here is my GitHub token: op://development/GitHub/credentials/personal_token" | op inject

Which should output something like this:

here is my GitHub token: ghp_WzgPAEutsFRZH9uxWYtw

Links

• 1Password docs