1PASSWORD WITH SWAMP
Swamp keeps secrets in vaults. Behaviors, workflows and data refer to a secret
by name and never hold its value. The @swamp/1password extension adds a vault
type that keeps those secrets in 1Password. With it, swamp vault put,
swamp vault get, swamp vault list-keys, swamp vault delete,
swamp vault annotate and swamp vault inspect all work on items in a
1Password vault you choose. A behavior definition reads a secret with an
expression such as ${{ vault.get('my-1password', 'my-api-key') }}, and Swamp
resolves it when the behavior runs.
Get started
curl -fsSL https://swamp-club.com/install.sh | sh swamp repo init swamp extension pull @swamp/1passwordHow the extension works
The extension provides one vault type, @swamp/1password. Every operation runs
the 1Password CLI, op, as a child process, so op must be installed and on
PATH on every machine that runs Swamp. Each Swamp vault points at one
1Password vault through the required op_vault setting. Two optional settings
control how op connects. op_account selects an account by shorthand or UUID.
op_service_account_token_file reads a service account token from a file and
passes it only to the op process.
The op CLI can sign in with a service account token in
OP_SERVICE_ACCOUNT_TOKEN, through 1Password desktop app integration, or
through a Connect Server using OP_CONNECT_HOST and OP_CONNECT_TOKEN. Vault
commands also need you to be signed in to a Swamp account.
Addressing secrets
Swamp vault keys map onto 1Password items in three ways:
- A bare name such as
my-api-keyrefers to thepasswordfield of the item with that name. - A path such as
db-credentials/usernamerefers to one field of an item. - A full URI such as
op://Private/db-credentials/usernamegoes toopunchanged.
If you want to keep related values as fields of one item, follow Store secrets in specific 1Password item fields.
Where to start
If you have not used a 1Password vault with Swamp before, the getting started tutorial goes from pulling the extension to referencing a stored secret. CI and server setups that should not export a token into the whole shell can use the steps in Authenticate a 1Password vault with a token file. If a machine is signed in to more than one 1Password account, Use a specific 1Password account for a vault shows how to pin each vault to one account. Understanding 1Password as a Swamp vault covers the reasons behind the key formats and authentication modes. Every configuration setting is listed in the extension reference.
The extension also emits OpenTelemetry spans for each vault operation and each
op call. Once a tracer is set up as described in
Set Up OpenTelemetry, you can trace
failures and latency back to the 1Password call that caused them.
1Password documentation
Getting started with 1Password vaults in Swamp
Create a Swamp vault backed by 1Password, store a first secret through the op CLI, list its keys, and reference it from a behavior definition with vault.get.
Tutorials →Authenticate a 1Password vault with a token file
Configure the @swamp/1password vault to read a service account token from a file with op_service_account_token_file, so the token reaches only the op process.
How-to Guides →Store secrets in specific 1Password item fields
Write 1Password secrets by item name, item/field path or op:// URI, list the stored keys, and reference a single field from a Swamp behavior definition.
How-to Guides →Use a specific 1Password account for a vault
Point a Swamp vault at one 1Password account with the op_account setting when the op CLI is signed in to several accounts, then confirm which keys it can see.
How-to Guides →1Password extensions
Every Swamp extension for 1Password: behavior types, global arguments, methods, vault configuration and the data each one writes, read from the registry.
Reference →Understanding 1Password as a Swamp vault
How the @swamp/1password vault maps Swamp vault keys onto 1Password items and fields, which authentication modes it supports, and how teams split vaults.
Explanation →