Skip to main content

Identity-Authenticated Vault Secret Fields

· 2 min read
Noel Jackson
Noel Jackson
Community Contributor

Structured secrets rarely agree on a single field name, and an ambient Vault token can silently cross an authentication boundary. That combination forces teams to reshape secret documents or wrap Atmos just to pass one short-lived credential into another identity.

The Problem​

The auth-secrets plugin could read a store's conventional scalar value, but it could not select an arbitrary field from a Vault or OpenBao KV document. Vault-backed stores also could not consume credentials produced by a native Atmos identity, leaving ambient or static tokens outside the identity chain.

The Fix​

Secret references now use path for the document location and can name an exact top-level field. Identities map those credentials into their environment with explicit spec.env templates. Vault and OpenBao stores can also bind to a native Atmos identity that emits environment/v1 credentials containing VAULT_TOKEN.

When an identity is configured, its token is exclusive: Atmos does not fall back to options.token or an ambient VAULT_TOKEN if authentication fails. The resolved credentials remain isolated from the Atmos process environment.

How to Use It​

Configure a Vault or OpenBao secret store with an identity, then select the source field in an auth-secrets credential reference:

stores:
  platform:
    type: hashicorp-vault
    secret: true
    identity: openbao/session
    options:
      address: https://openbao.example.com
      mount: secret

auth:
  providers:
    deployment-secrets:
      kind: secrets/store
      spec:
        credentials:
          token:
            store: platform
            path: platform/deploy/example
            field: access_token
  identities:
    deployment:
      kind: secrets/env
      via:
        provider: deployment-secrets
      spec:
        env:
          SERVICE_TOKEN: '{{ .credentials.token }}'

The store's openbao/session identity must emit VAULT_TOKEN; the referenced document may use any top-level field name and may still contain a separate legacy value field. The deployment identity maps the selected credential into SERVICE_TOKEN for its child process. For hyphenated credential names, use a template such as {{ index .credentials "api-access-key" }}. Missing credential references fail authentication; plain strings stay literal.

Get Involved​

Try the native identity chain with a Vault or OpenBao KV v2 store and share feedback on field selection, token lifecycle, and error messages in the Atmos issue tracker.