HashiConf 2025 Don't miss the live stream of HashiConf Day 2 happening now View live stream
Vault Home

Authenticate to Vault using the SPIFFE auth method with SPIRE

Enterprise

Appropriate Vault Enterprise  license required

You can authenticate to Vault using the SPIFFE auth method with SPIRE (SPIFFE Runtime Environment), a production-ready implementation of the full SPIFFE framework and set of standards for identifying and securing communications between application services.

If you are not familiar with SPIFFE, refer to the SPIFFE overview for information about how SPIFFE authentication works in Vault.

Follow these steps as written. Running them on production hosts changes their configuration. Refer to the setup guide for general configuration instructions.

Requirements

Set up Vault and SPIRE

This section walks through the minimum configuration needed to get a workload authenticating to Vault using SPIRE. This section does not cover SPIRE installation or hardening. Refer to the SPIRE documentation for more information.

Note

This walkthrough runs SPIRE and Vault on the same local machine, so the following steps use localhost. Substitute your own reachable addresses if any of these components run on separate hosts.

Set up the SPIRE server

Set up a SPIRE server. A SPIRE agent connects to the server to issue SVIDs to workloads.

  1. Create a working directory for the SPIRE server.

    $ mkdir ~/spire-server && cd ~/spire-server

    This step is necessary for the minimal setup shown in this doc. Typically the SPIRE Server and SPIRE Agent run on different nodes. You are isolating the configuration and data directory here to avoid conflicts.

  2. Create a minimal SPIRE server config.

    $ tee spire-server.conf <<EOF
# spire-server.conf
server {
  trust_domain = "example.org"
  bind_address = "0.0.0.0"
  bind_port    = "8081"
  data_dir     = "./.data"

  federation {
    bundle_endpoint {
      address = "0.0.0.0"
      port    = 8443

      profile "https_spiffe" {}
    }
  }
}

plugins {
  DataStore "sql" {
    plugin_data {
      database_type     = "sqlite3"
      connection_string = "./.data/datastore.sqlite3"
    }
  }
  NodeAttestor "join_token" {
    plugin_data {}
  }
  KeyManager "disk" {
    plugin_data {
      keys_path = "./.data/keys.json"
    }
  }
}
EOF

    Warning

    bind_address = "0.0.0.0" and the federation address = "0.0.0.0" bind to all network interfaces. This is acceptable for a local lab environment where SPIRE runs on the same machine as the workload. In production, replace both values with the specific IP address or hostname the SPIRE server should listen on.

    Note

    Bundle endpoints always use TLS — there is no plain-HTTP mode. The https_spiffe profile authenticates the endpoint using the SPIRE server's own SVID, so it does not need a certificate from an external CA or a real, resolvable domain, which is why it is used here. The alternative https_web profile does require an externally issued certificate (or ACME automation) and is a better fit if you are federating with an endpoint Vault reaches over the public internet. Refer to SPIRE's Federation docs for additional information on both profiles.

  3. Start the SPIRE server.

    $ spire-server run -config ./spire-server.conf &

  4. Create a one-time join token for the SPIRE agent to connect to.

    $ JOIN_TOKEN=$(spire-server token generate -spiffeID spiffe://example.org/agent/example-node | sed 's/^Token: //')

    This example uses join-token node attestation. A join token is single-use, similar to a Vault wrapping token. It bootstraps exactly one agent and is then no longer valid. Production deployments should use a platform-specific node attestor (aws_iid, gcp_iit, k8s_psat, x509pop, or another supported attestor) instead of shared join tokens.

Set up the SPIRE agent

The agent is what actually issues SVIDs to workloads. The SPIRE server and a registration entry alone do not enable authentication.

  1. Create a working directory for the SPIRE agent.

    $ mkdir ~/spire-agent && cd ~/spire-agent

  2. Get the trust bundle from the SPIRE server and save it to a file.

    $ spire-server bundle show > initial_bundle.crt

    The SPIRE Agent will need this when you start the agent.

  3. Create a minimal SPIRE agent config.

    $ tee spire-agent.conf <<EOF
# agent.conf
agent {
  data_dir          = "./.data"
  server_address    = "127.0.0.1"
  server_port       = "8081"
  socket_path       = "/tmp/spire-agent/public/api.sock"
  trust_bundle_path = "./initial_bundle.crt"
  trust_domain      = "example.org"
}
 
plugins {
  NodeAttestor "join_token" {
    plugin_data {}
  }
  KeyManager "disk" {
    plugin_data {
      directory = "./.data"
    }
  }
  WorkloadAttestor "unix" {
    plugin_data {}
  }
}
EOF

    The trust_bundle_path requires manually copying the server's initial trust bundle onto the node before the agent's first start. In a production environment, provision this file through your existing configuration management and secrets injection workflow at provisioning time. Alternatively, use trust_bundle_url to fetch the bundle. Refer to SPIRE's agent configuration reference for both options.

  4. Start the agent with the join token from the server configuration section.

    $ spire-agent run -config spire-agent.conf -joinToken $JOIN_TOKEN &

Register a workload

  1. Register a workload on the SPIRE server. The selector used when registering the workload must match the agent configuration.

    $ spire-server entry create \
   -parentID spiffe://example.org/agent/example-node \
   -spiffeID  spiffe://example.org/ns/prod/sa/payment-service \
   -selector  unix:uid:$(id -u)

    The WorkloadAttestor unix plugin in the agent configuration matches the unix:uid:... selector. Replace both together if you are attesting workloads a different way (Kubernetes, Docker, or another supported platform). The example command uses $(id -u) to capture your own UID at run time. This works as long as you are the one both registering the entry and later fetching the SVID. In a real deployment where an operator registers entries for a separate service account, substitute that account's UID explicitly. $(id -u) captures the operator's UID, not the workload's.

  2. Request a workload SVID.

    $ spire-agent api fetch x509 -write ~/spire-agent

    This writes ~/spire-agent/svid.0.pem and ~/spire-agent/svid.0.key.

    Manually fetching and writing an SVID to disk confirms the setup works, but it does not rotate or renew the SVID. Production workloads should call the Workload API directly using a SPIFFE SDK, or use SPIFFE Helper.

Configure the Vault auth method

Configure Vault with the SPIFFE auth method to match the SPIRE configuration.

  1. Create a working directory for the Vault server.

    $ mkdir ~/vault-dev && cd ~/vault-dev

  2. Export your Vault Enterprise license as an environment variable.

    $ export VAULT_LICENSE=C10WMSH0W...snip...S3ASM3STR33T

  3. Start a Vault dev mode server.

    $ vault server -dev -dev-tls -dev-root-token-id root &

    The dev server runs completely in memory and listens on localhost on TCP port 8200 with TLS enabled. At runtime, the dev server also automatically unseals and prints the unseal key and initial root token values to stdout.

    Root tokens

    The dev mode server starts with an initial root token value set.

    Root token use should be extremely guarded in production environments because it provides full access to the Vault server.

    You can supply the root token value to start Vault in dev mode for convenience and to keep the steps here focused on the learning goals of this tutorial.

  4. Copy the environment variables for the Vault dev mode server.

    Note

    Copy the full VAULT_CACERT=... from your dev mode server's output.

  5. Export the required Vault environment variables.

    $ export VAULT_TOKEN=root VAULT_ADDR=https://127.0.0.1:8200 VAULT_CACERT='/path/from/stdout'

  6. Request the trust bundle for Vault.

    $ spire-server bundle show -format spiffe > initial_bundle.jwks

  7. Enable the SPIFFE auth method. 

    $ vault auth enable \
  -passthrough-request-headers="Authorization" \
  spiffe

  8. Write the SPIFFE auth method configuration.

    $ vault write auth/spiffe/config \
    trust_domain="example.org" \
    profile="https_spiffe_bundle" \
    bundle=@initial_bundle.jwks \
    endpoint_url="https://127.0.0.1:8443" \
    endpoint_spiffe_id="spiffe://example.org/spire/server" \
    audience="vault"

    audience is mount-wide, not per-role. Every role on this mount shares this same JWT audience allow-list. X.509-SVIDs carry no aud claim, so X.509-SVID auth is unaffected by this setting.

  9. Create a role for the workload.

    $ vault write auth/spiffe/role/payment-role \
  workload_id_patterns="ns/prod/sa/payment-service" \
  token_policies="payment-vault-policy" \
  token_ttl="1h"

    workload_id_patterns matches on the workload ID — the SPIFFE ID with the spiffe://<trust_domain>/ prefix stripped, not the full URI. Supports * (prefix) and + (single path segment) wildcards.

Authenticate a workload to Vault

Production services use a SPIFFE SDK (go-spiffe for Go, py-spiffe for Python, java-spiffe for Java, or another SPIFFE SDK implementation) to call the Workload API directly.

This walkthrough uses the spire-agent CLI and curl to authenticate to Vault.

  1. Use curl to authenticate to Vault.

    $ curl \
    --cacert "$VAULT_CACERT" \
    --cert ~/spire-agent/svid.0.pem \
    --key ~/spire-agent/svid.0.key \
    --request POST \
    --data '{"role": "payment-role"}' \
    $VAULT_ADDR/v1/auth/spiffe/login | jq

    Example output:

    {
  "request_id": "0f7905fb-6194-c4c7-5f0a-5c5bf4f042c5",
  "lease_id": "",
  "renewable": false,
  "lease_duration": 0,
  "data": null,
  "wrap_info": null,
  "warnings": null,
  "auth": {
    "client_token": "hvs.CAESID_Uge-45...example...WRzUmdicTJ3UEpVZ2o",
    "accessor": "MTBqnsBvoRuhqMN3kYFt0iRS",
    "policies": [
      "default",
      "payment-vault-policy"
    ],
    "token_policies": [
      "default",
      "payment-vault-policy"
    ],
    "metadata": {
      "role": "payment-role",
      "spiffe_id": "spiffe://example.org/ns/prod/sa/payment-service",
      "trust_domain": "example.org"
    },
    "lease_duration": 3600,
    "renewable": true,
    "entity_id": "707d32fd-8021-7fc7-9d08-c3c9a7ae7374",
    "token_type": "service",
    "orphan": true,
    "mfa_requirement": null,
    "num_uses": 0
  },
  "mount_type": ""
}

    Optionally set "type" in the request body (auto, cert, or jwt) to force which SVID source Vault should use. auto (the default) prefers a JWT-SVID if present, falling back to the peer X.509 certificate.

    After successful validation, Vault returns a client token bound to the role's policies.

SPIFFE plugin API

The SPIFFE auth method has a full HTTP API. Refer to the SPIFFE auth API documentation for additional information.

Terraform

You can use the vault_auth_backend resource to enable the SPIFFE auth method and the vault_spiffe_auth_backend_config to manage the configuration.

Edit this page on GitHub