# Providers > Choose and configure the storage backends SecretSpec uses for secrets A provider is a storage backend from which SecretSpec reads secrets and, when supported, writes them. Providers let one `secretspec.toml` describe the secrets an application needs without requiring every environment to use the same secret store. For example, a developer can use the system keyring, CI can supply environment variables, and production can use a shared password manager or cloud secret manager. The secret definitions stay the same; only their provider configuration changes. ## Provider specifications Anywhere SecretSpec accepts a provider, you can use one of three forms: * A provider name, such as `keyring` or `env`. * A provider URI, such as `dotenv://.env.local` or `onepassword://Production`. The URI configures a particular instance of the provider. * A provider alias, such as `prod_vault`, defined in project or user configuration. Aliases are useful when a URI is shared by several secrets or should have a meaningful, store-independent name. **secretspec.toml** ```toml [providers] prod_vault = "onepassword://Production" [profiles.production] DATABASE_URL = { description = "Production database", providers = ["prod_vault"] } ``` ## Available providers | Provider | Storage backend | Read | Write | Encrypted at rest | TPM-backed keys | | ------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---- | ------ | -------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------- | | [keyring](/providers/keyring/) | [macOS Keychain](https://support.apple.com/guide/security/keychain-data-protection-secb0694df1a/web), [Windows Credential Manager](https://learn.microsoft.com/windows/win32/secauthn/credentials-management), or [Linux Secret Service](https://gnome.pages.gitlab.gnome.org/libsecret/) | ✓ | ✓ | ✓ | — | | [kdbx](/providers/kdbx/) (0.17+) | KeePass KDBX file (requires the `kdbx` build feature) | ✓ | KDBX 4 | ✓ | — | | [dotenv](/providers/dotenv/) | A `.env` file | ✓ | ✓ | ✗ | — | | [file](/providers/file/) (0.19+) | One plaintext byte file per secret (arbitrary bytes in 0.21+) | ✓ | ✓ | ✗ | — | | [env](/providers/env/) | Current process environment | ✓ | ✗ | ✗ | — | | [ejson](/providers/ejson/) (0.20+) | EJSON encrypted file (requires the `ejson` build feature and EJSON CLI) | ✓ | ✗ | ✓ | — | | [null](/providers/null/) (0.19+) | No storage; uses a manifest default, ephemeral generation, or an ephemeral run prompt | ✗ | ✗ | N/A | — | | [systemd-credential](/providers/systemd-credential/) (0.17+) | Credentials passed to the current systemd service (arbitrary bytes in 0.21+) | ✓ | ✗ | Depends on the unit’s credential source | [Via systemd-creds](https://www.freedesktop.org/software/systemd/man/latest/systemd-creds.html) | | [fly](/providers/fly/) (0.20+) | Fly.io application secrets through `flyctl` | ✗ | ✓ | ✓ | — | | [cloudflare](/providers/cloudflare/) (0.20+) | Cloudflare account-level Secrets Store through its REST API | ✗ | ✓ | ✓ | — | | [pass](/providers/pass/) | Unix `pass` password store | ✓ | ✓ | ✓ | [Via GnuPG](https://gnupg.org/blog/20210315-using-tpm-with-gnupg-2.3.html) | | [gopass](/providers/gopass/) (0.15+) | `gopass` password store (git-synced, GPG-encrypted) | ✓ | ✓ | ✓ | [Via GnuPG](https://gnupg.org/blog/20210315-using-tpm-with-gnupg-2.3.html) | | [protonpass](/providers/protonpass/) | Proton Pass | ✓ | ✓ | ✓ | — | | [passbolt](/providers/passbolt/) (0.19+) | Self-hosted Passbolt through `go-passbolt-cli` | ✓ | ✓ | ✓ | — | | [onepassword](/providers/onepassword/) | 1Password | ✓ | ✓ | ✓ | — | | [lastpass](/providers/lastpass/) | LastPass | ✓ | ✓ | ✓ | — | | [dashlane](/providers/dashlane/) (0.18+) | Dashlane, through the `dcli` CLI | ✓ | ✗ | ✓ | — | | [keeper](/providers/keeper/) (0.18+) | Keeper Secrets Manager (requires the `keeper` build feature) | ✓ | ✓ | ✓ | — | | [doppler](/providers/doppler/) (0.21+) | Doppler over its REST API (included by default; `doppler` feature for custom builds) | ✓ | ✓ | ✓ | — | | [gcsm](/providers/gcsm/) | Google Cloud Secret Manager (requires the `gcsm` build feature) | ✓ | ✓ | ✓ | — | | [awssm](/providers/awssm/) | AWS Secrets Manager, including `SecretBinary` (0.21+; requires the `awssm` build feature) | ✓ | ✓ | ✓ | — | | [awsps](/providers/awsps/) (0.18+) | AWS Systems Manager Parameter Store (requires the `awsps` build feature in 0.18+) | ✓ | ✓ | ✓ (`SecureString`) | — | | [scaleway](/providers/scaleway/) (0.17+) | Scaleway Secret Manager (requires the `scaleway` build feature) | ✓ | ✓ | ✓ | — | | [setec](/providers/setec/) (0.21+) | Tailscale Setec (requires the `setec` build feature) | ✓ | ✓ | ✓ | Depends on server key configuration | | [vault](/providers/vault/) | HashiCorp Vault (requires the `vault` build feature) | ✓ | ✓ | ✓ | — | | [openbao](/providers/openbao/) (0.17+) | OpenBao (requires the `openbao` build feature; 0.16 uses `openbao://` through `vault`) | ✓ | ✓ | ✓ | — | | [bw](/providers/bw/) (0.18+) | Bitwarden Password Manager via the `bw` CLI (requires the `bw` build feature) | ✓ | ✓ | ✓ | — | | [bws](/providers/bws/) | Bitwarden Secrets Manager (official `bws` CLI in SecretSpec 0.17+; requires the `bws` build feature) | ✓ | ✓ | ✓ | — | | [akv](/providers/akv/) | Azure Key Vault (requires the `akv` build feature) | ✓ | ✓ | ✓ | — | | [aac](/providers/aac/) (0.20+) | Azure App Configuration, including Key Vault-reference resolution (included by default; `aac` feature for custom builds) | ✓ | ✓ | ✓ | — | | [infisical](/providers/infisical/) (0.16+) | Infisical (requires the `infisical` build feature) | ✓ | ✓ | ✓ | — | | [age](/providers/age/) (0.17+) | An age-encrypted file (requires the `age` build feature) | ✓ | ✓ | ✓ | — | | [sops](/providers/sops/) (0.17+) | SOPS-encrypted files (requires the `sops` build feature and SOPS CLI) | ✓ | ✓ | ✓ | Depends on the configured SOPS key service | | [kubernetes](/providers/kubernetes/) (0.20+) | Kubernetes ConfigMaps and Secrets (requires the `kubernetes` build feature) | ✓ | ✓ | [Secrets can be encrypted at rest](https://kubernetes.io/docs/tasks/administer-cluster/encrypt-data/#ensure-all-secrets-are-encrypted) | — | “TPM-backed keys” means the local key used by the provider can be protected by a [TPM 2.0](https://trustedcomputinggroup.org/resource/tpm-library-specification/) through the provider path SecretSpec uses. Pass and Gopass inherit this capability from GnuPG when its encryption key is moved to the TPM. systemd credentials inherit it from [systemd-creds](https://www.freedesktop.org/software/systemd/man/latest/systemd-creds.html), which seals encrypted credentials to the TPM2 by default when the host has one. [libsecret has an optional TPM2-enabled file backend](https://gnome.pages.gitlab.gnome.org/libsecret/libsecret-tpm2.html), but SecretSpec’s Linux keyring transport uses the Secret Service D-Bus API rather than that file backend. macOS Keychain uses Apple’s Secure Enclave rather than a TPM, and [Windows Vault credentials are not protected by Credential Guard](https://learn.microsoft.com/windows/security/identity-protection/credential-guard/how-it-works). An em dash means SecretSpec has no documented TPM integration for that provider; it does not describe other hardware security used internally by the provider service. Each provider page starts with a minimal working example, then covers setup, project configuration, storage conventions, existing provider-native secrets, and CI/CD where applicable. ## Configure the default provider Run the interactive configuration command to select the user-global provider SecretSpec uses when a secret has no provider-specific configuration. SecretSpec 0.17+ provides an explicit `global` namespace; the legacy spelling without it remains supported: ```bash $ secretspec config global init # 0.17+ ``` SecretSpec 0.17+ can persist the provider and profile non-interactively: ```bash $ secretspec config global init --provider env --profile default ``` The resulting user configuration contains a default provider: **\~/.config/secretspec/config.toml** ```toml [defaults] provider = "keyring" profile = "development" # Optional default profile ``` Use `--provider` for a one-off override, or `SECRETSPEC_PROVIDER` for commands in the current shell or CI job: ```bash # Route every secret in this command to a project .env file. $ secretspec run --provider dotenv -- npm start # Route every secret in subsequent commands to existing environment variables. $ export SECRETSPEC_PROVIDER=env $ secretspec check ``` `SECRETSPEC_PROVIDER` is a whole-resolution override: it replaces every per-secret fallback chain. Integrations such as devenv should only export it when the user explicitly configures a whole-resolution provider override. When consuming a JSON or SDK resolution, do not feed its top-level `provider` display label back into `SECRETSPEC_PROVIDER`; mixed per-secret routes cannot be represented by one provider string. Only export `SECRETSPEC_PROVIDER` when the user explicitly selected a whole-resolution override. Per-secret `source_provider` remains the authoritative provenance. A provider URI can configure the selected backend more precisely: ```bash # Select a specific 1Password vault. $ secretspec run --provider "onepassword://Development" -- npm start # Select a specific dotenv file. $ secretspec run --provider "dotenv:/home/user/work/.env" -- npm test ``` ## Configure a project default provider chain (0.21+) **New in version 0.21** Use project `[defaults].providers` when every profile should use the same provider chain unless a profile or secret overrides it. The chain can name a user-global alias, allowing each developer to supply personal provider-native coordinates while the committed manifest stays the same: **secretspec.toml** ```toml [defaults] providers = ["developer"] [profiles.staging] DATABASE_PASSWORD = { description = "Personal staging database password" } ``` **\~/.config/secretspec/config.toml** ```toml [defaults.providers.developer] uri = "awsps://developer@us-east-1" ref = { item = "/{project}/{profile}/developers/alice/{key}" } ``` The alias’s existing `{project}`, `{profile}`, and `{key}` placeholders expand in the project that selects it. Only `alice` is user-specific. Do not also declare `developer` in the project’s `[providers]` table, because a project alias with the same name takes precedence over the user-global alias. ## Configure provider aliases Provider aliases can be declared at either project or user scope: * Define project aliases in the top-level `[providers]` table in `secretspec.toml`. Commit these aliases so team members and CI use the same mapping. * Define user aliases in `[defaults.providers]` in `~/.config/secretspec/config.toml`. Use these for personal mappings that should apply across projects. If both scopes define the same alias, the project alias takes precedence. **secretspec.toml** ```toml [providers] prod_vault = "onepassword://Production" shared_vault = "onepassword://Shared" local = "keyring://" [profiles.production] DATABASE_URL = { description = "Production database", providers = ["prod_vault", "local"] } SENTRY_DSN = { description = "Error reporting", providers = ["shared_vault", "local"] } ``` Provider lists may combine aliases, provider names, and inline provider URIs: **secretspec.toml** ```toml [profiles.production] DATABASE_URL = { description = "Production database", providers = ["onepassword://Production", "keyring"] } ``` ### Alias ref templates **New in version 0.19** A leaf alias can map the logical `{project}`, `{profile}`, and `{key}` into its provider’s native coordinates. This lets every link in a fallback chain—and each side of an import—use a different address: **secretspec.toml** ```toml [providers] remote = { uri = "onepassword://Production", ref = { item = "{project}-{profile}", field = "{key}" } } local = { uri = "dotenv://.env", ref = { item = "{key}" } } [profiles.production] API_KEY = { description = "API key", providers = ["remote", "local"] } ``` Use per-secret `refs = { alias = { item = "..." } }` for exceptions. See [Secret References](/concepts/references/#different-coordinates-per-provider-019) for precedence, import-only source aliases, and cached-route restrictions. Use the CLI to manage user-level aliases: ```bash # SecretSpec 0.17+ $ secretspec config global provider add prod_vault "onepassword://Production" $ secretspec config global provider list $ secretspec config global provider remove prod_vault ``` These commands modify only `~/.config/secretspec/config.toml`. Edit the top-level `[providers]` table directly to change project aliases. ## Provider credentials **New in version 0.15** Some providers need credentials before they can retrieve secrets. Examples include an access token for Bitwarden Secrets Manager, a Vault token or AppRole credentials, a 1Password service account token, and Azure service-principal credentials. An alias can load these credentials from another provider. This avoids storing long-lived provider credentials in a shell profile or CI variable when a secure store is available. The [provider credential reference](/reference/provider-credentials/) lists every accepted semantic name, its environment fallbacks, and the SecretSpec version that introduced it. ### Use the convention address In an alias’s `credentials` table, map each semantic credential name to the provider that stores it: **secretspec.toml** ```toml [providers] keyring = "keyring://" # Read the access token from keyring before connecting to Bitwarden. bws = { uri = "bws://a9230ec4-5507-4870-b8b5-b3f500587e4c", credentials = { access_token = "keyring" } } ``` A string value such as `"keyring"` is a provider specification. SecretSpec reads the credential from that provider at the conventional `{project}/{profile}/{credential}` address for the active project and profile. ### Use an explicit address Use a table with `provider` and `ref` when the credential already exists at a specific provider-native address: **secretspec.toml** ```toml [providers.vault_prod] uri = "vault://secret/myapp?auth=approle" credentials = { role_id = { provider = "onepassword", ref = { vault = "Infra", item = "vault-approle", field = "role_id" } }, secret_id = { provider = "onepassword", ref = { vault = "Infra", item = "vault-approle", field = "secret_id" } } } ``` The `ref` table uses the same provider-native coordinates as a secret [`ref`](/reference/configuration/#secret-references). ### Store provider credentials Use `config provider login` to prompt for every credential declared by an alias and write it to the configured source: ```bash $ secretspec config provider login bws Enter access_token for provider 'bws' (source: keyring): **** ✓ stored access_token in keyring at smoke/default/access_token ``` You can also create a user-level alias with a convention-address credential source from the CLI: ```bash $ secretspec config global provider add bws "bws://project-uuid" --credential access_token=keyring # 0.17+ $ secretspec config provider login bws ``` Provider credentials follow these rules: * **Configured credentials are authoritative.** When an alias declares a credential, SecretSpec reads its configured source. Providers may still use their conventional environment variables when no explicit credential is supplied. * **Credential bytes are preserved (0.21+).** Resolution keeps each credential as bytes. Interfaces that require text validate UTF-8 when consuming it; validation errors never select an environment fallback. Unix CLI environments accept non-UTF-8 bytes but cannot contain NUL bytes. A configured credential that resolves to an empty value is an error rather than a fall through to the environment. * **Credentials remain internal.** SecretSpec passes a retrieved credential to the destination provider in memory. It does not export the credential or include it in the environment of a process started by `secretspec run`. * **Credential chains are one hop.** A source provider cannot require provider credentials of its own. SecretSpec validates this before accessing the provider, preventing dependency cycles. * **Convention addresses are profile-specific.** A string source uses the active project and profile. Use a `ref` source when multiple projects or profiles should share one provider credential. * **Names are provider-specific.** The catalog above is exhaustive. Unsupported names are rejected before any source is read. * **External providers negotiate names (0.21+).** An out-of-tree endpoint asks for the URI-specific credentials it needs at runtime. Its alias does not need a `credentials` table: SecretSpec can load requested values from a provider-private operating-system keyring namespace, and `config provider login` discovers and stores them. A configured mapping remains useful as an explicit source override and is read only if the endpoint requests its name. * **A URI may not carry a credential (0.19+).** A provider URI with a password (`scheme://user:PASSWORD@host`) is rejected, as is a service account token in the `onepassword+token://` userinfo. A URI is committed to `secretspec.toml`, echoed into shell history, and printed by CI, so a credential written there is already disclosed. Use a provider credential or the provider’s environment variable instead. ## Next steps * Learn how [Provider fallback](/concepts/providers/fallback/) selects and orders sources. * Cache slow remote routes and diagnose remaining latency with [Provider caching](/concepts/providers/caching/) (0.17+). * Review the URI and authentication details for an individual provider in the [Providers](/providers/keyring/) section. * Learn how [Profiles](/concepts/profiles/) apply provider defaults to an environment. * Learn how [Secret references](/concepts/references/) separate provider selection from provider-native addresses.