1Password Plugin

Our 1Password plugin enables secure loading of values from 1Password vaults using declarative instructions within your .env files.

For local development, it (optionally) supports authenticating using the local 1Password desktop app, including using biometric unlock. Otherwise, it uses a service account making it suitable for CI/CD and production environments.

This plugin is compatible with any 1Password account type (personal, family, teams, business), but note that rate limits vary by account type.

In a JS/TS project, you may install the @varlock/1password-plugin package as a normal dependency. Otherwise you can just load it directly from your .env.schema file, as long as you add a version specifier. See the plugins guide for more instructions on installing plugins.

# 1. Load the plugin
# @plugin(@varlock/1password-plugin)
#
# 2. Initialize the plugin - see below for more details on options
# @initOp(token=$OP_TOKEN, allowAppAuth=forEnv(dev), account=acmeco)
# ---

# 3. Add a service account token config item (if applicable)
# @type=opServiceAccountToken @sensitive
OP_TOKEN=

If your secrets are already stored in 1Password, you may not need to do anything. However, if secrets live in a vault that holds other sensitive data, you should create a new vault and move your secrets to it, because the access system of 1Password is based on vaults, not individual items.

You can create multiple vaults to segment access to different environments, services, etc. This can be done using any 1Password app, the web app, or the CLI. link

Remember to grant access to necessary team members, particularly if you plan on using the desktop app auth method during local development, as they will be authenticating as themselves.

If you plan on using data from 1Password in deployed environments (CI/CD, production, etc), you will need to create a service account to allow machine-to-machine authentication. You could also use a service account for local development, although we recommend using the desktop app auth method described below for convenience.

This service account token will now serve as your secret-zero - which grants access to the rest of your sensitive data stored in 1Password.

1. Create a new service account and grant access to necessary vault(s). This is a special account used for machine-to-machine communication. This can only be done in the 1Password web interface. Be sure to save the new service account token in another vault so you can find it later. link

2. Wire up the service account token in your config. Add a config item of type opServiceAccountToken to hold the token value, and reference it when initializing the plugin.

   # @plugin(@varlock/1password-plugin)
   # @initOp(token=$OP_TOKEN)
   # ---
   # @type=opServiceAccountToken @sensitive
   OP_TOKEN=

3. Set your service account token in deployed environments. Copy the token value from where you saved it earlier, and set it in deployed environments using your platform’s env var management UI. Be sure to use the same name as you defined in your schema (e.g. OP_TOKEN).

During local development, you may find it convenient to skip the service account tokens and instead rely on your local 1Password desktop app (via the CLI integration), including using its biometric unlocking features.

1. Opt-in while initializing the plugin

   # @plugin(@varlock/1password-plugin)
   # @initOp(token=$OP_TOKEN, allowAppAuth=true)

   You may use other functions to conditionally enable this, for example forEnv(dev).

2. Specify 1Password account (optional)

   # @plugin(@varlock/1password-plugin)
   # @initOp(token=$OP_TOKEN, allowAppAuth=true, account=acmeco)

   This value is passed through under the --account flag to the op CLI, and accepts account shorthand, sign-in address, account ID, or user ID.

   You can run op account list to see your available accounts. The shorthand is the subdomain of your x.1password.com sign-in address.

   This is optional, but recommended if you have access to multiple 1Password accounts, to ensure you connect to the correct one.

3. Ensure the op CLI is installed. docs

4. Enable the desktop app + CLI integration. docs

With this option enabled, if the resolved service account token is empty, we will call out to the op cli installed on your machine (it must be in your $PATH) and use the auth it provides. With the desktop app integration enabled, it will call out and may trigger biometric verification to unlock. It is secure and very convenient!

Once the plugin is installed and initialized, you can start adding config items that load values from 1Password using the op() resolver function.

You can wire up individual items to specific fields in by using 1Password secret references.

DB_PASS=op(op://my-vault/database-password/password)

If you have multiple plugin instances, the op() function accepts an optional first parameter to specify which instance id to use.

# @initOp(id=dev, token=$OP_TOKEN_DEV, allowAppAuth=true)
# @initOp(id=prod, token=$OP_TOKEN_PROD, allowAppAuth=false)
# ---
DEV_ITEM=op(dev, op://vault-name/item-name/field-name)
PROD_ITEM=op(prod, op://vault-name/item-name/field-name)

# @initOp(id=notProd, token=$OP_TOKEN, allowAppAuth=forEnv(dev), account=acmeco)
# ---
# @type=opServiceAccountToken
OP_TOKEN=

# @type=opServiceAccountToken
OP_TOKEN=

ITEM=op(op://vault-name/item-name/field-name)

# example using a plugin instance id
ITEM_WITH_INSTANCE_ID=op(prod, op://vault-name/item-name/field-name)