New Vault OSS Now Includes Multi-factor Authentication! Learn more
  • Overview
    • Automated PKI Infrastructure
    • Data Encryption & Tokenization
    • Database Credential Rotation
    • Dynamic Secrets
    • Identity-based Access
    • Key Management
    • Kubernetes Secrets
    • Secrets Management
  • Enterprise
  • Tutorials
  • Docs
  • API
  • Community
GitHubTry Cloud
Download
    • v1.10.x (latest)
    • v1.9.x
    • v1.8.x
    • v1.7.x
    • v1.6.x
    • v1.5.x
    • v1.4.x
  • What is Vault?
  • Use Cases
    • CLI Quick Start
    • HCP Quick Start
    • Developer Quick Start

  • Browser Support
  • Installing Vault
    • Overview
    • Architecture
    • High Availability
    • Integrated Storage
    • Security Model
    • Telemetry
    • Token Authentication
    • Key Rotation
    • Replication
    • Limits and Maximums
    • Overview
    • 'Dev' Server
    • Seal/Unseal
    • Namespace API Lock
    • Lease, Renew, and Revoke
    • Authentication
    • Tokens
    • Identity
    • OIDC Provider
    • Response Wrapping
    • Policies
    • Password Policies
    • Username Templating
    • High Availability
    • Storage
      • Overview
      • Autopilot
    • PGP, GnuPG, and Keybase
    • Recovery Mode
    • Resource Quotas
      • Overview
      • FAQ
    • Transform
    • Mount Migration
    • Overview
      • Overview
      • TCP
    • replication
      • Overview
      • AliCloud KMS
      • AWS KMS
      • Azure Key Vault
      • GCP Cloud KMS
      • OCI KMS
      • HSM PKCS11 ENT
      • Vault Transit
    • sentinel
      • Overview
      • Consul
      • Kubernetes
      • Overview
      • Aerospike
      • Alicloud OSS
      • Azure
      • Cassandra
      • CockroachDB
      • Consul
      • CouchDB
      • DynamoDB
      • Etcd
      • Filesystem
      • FoundationDB
      • Google Cloud Spanner
      • Google Cloud Storage
      • In-Memory
      • Manta
      • MSSQL
      • MySQL
      • OCI Object Storage
      • PostgreSQL
      • Integrated Storage (Raft)
      • S3
      • Swift
      • Zookeeper
    • telemetry
    • ui
    • Log Completed Requests
    • Entropy Augmentation ENT
    • kms_library ENT
    • Overview
    • agent
      • Overview
      • disable
      • enable
      • list
      • Overview
      • disable
      • enable
      • help
      • list
      • move
      • tune
    • debug
    • delete
      • Overview
      • delete
      • destroy
      • enable-versioning
      • get
      • list
      • metadata
      • patch
      • put
      • rollback
      • undelete
      • Overview
      • lookup
      • renew
      • revoke
      • Overview
      • get
      • inspect
    • list
    • login
    • monitor
    • namespace
      • Overview
      • diagnose
      • generate-root
      • init
      • key-status
      • members
      • migrate
      • raft
      • rekey
      • rotate
      • seal
      • step-down
      • unseal
      • usage
    • path-help
      • Overview
      • deregister
      • info
      • list
      • register
      • reload
      • Overview
      • delete
      • fmt
      • list
      • read
      • write
    • read
      • Overview
      • disable
      • enable
      • list
      • move
      • tune
    • server
    • ssh
    • status
      • Overview
      • capabilities
      • create
      • lookup
      • renew
      • revoke
    • unwrap
    • version
    • version-history
    • write
    • Token Helpers
    • Overview
      • Overview
        • Overview
        • AliCloud
        • AppRole
        • AWS
        • Azure
        • Cert
        • CF
        • GCP
        • JWT
        • Kerberos
        • Kubernetes
        • Overview
        • File
      • Overview
        • Overview
        • Kubernetes
    • Templates
    • Windows service

    • Overview
    • Active Directory
    • AliCloud
    • AWS
    • Azure
    • Consul
    • Cubbyhole
      • Overview
      • Cassandra
      • Couchbase
      • Elasticsearch
      • HanaDB
      • IBM Db2
      • InfluxDB
      • MongoDB
      • MongoDB Atlas
      • MSSQL
      • MySQL/MariaDB
      • Oracle
      • PostgreSQL
      • Redshift
      • Snowflake
      • Custom
    • Google Cloud
    • Google Cloud KMS
      • Overview
      • Azure Key Vault
      • AWS KMS
      • GCP Cloud KMS
    • KMIP ENTERPRISE
      • Overview
      • K/V Version 1
      • K/V Version 2
      • Overview
      • Identity Tokens
      • OIDC Identity Provider
    • MongoDB Atlas
    • Nomad
    • OpenLDAP
    • PKI (Certificates)
    • RabbitMQ
      • Overview
      • Signed Certificates
      • SSH OTP
      • Dynamic Key
    • Terraform Cloud
    • TOTP
      • Overview
      • FF3-1 Tweak Usage
      • Tokenization Transform ENTERPRISE
    • Transit
    • Venafi (Certificates)
    • Overview
    • AppRole
    • AliCloud
    • AWS
    • Azure
    • Cloud Foundry
    • GitHub
    • Google Cloud
      • Overview
      • OIDC Providers
    • Kerberos
    • Kubernetes
    • LDAP
      • Overview
      • FAQ
    • Oracle Cloud Infrastructure
    • Okta
    • RADIUS
    • TLS Certificates
    • Tokens
    • Username & Password

    • App ID DEPRECATED
    • MFA LEGACY / UNSUPPORTED
    • Overview
    • File
    • Syslog
    • Socket
    • Overview
    • Plugin Architecture
    • Plugin Development
    • Plugin Management
    • Plugin Portal
  • Vault Integration Program
  • Troubleshoot

    • Overview
      • Overview
      • Agent Injector vs. Vault CSI Provider
        • Overview
        • Running Vault
        • Enterprise Licensing
        • Running Vault on OpenShift
        • Configuration
          • Overview
          • Development
          • Standalone with Load Balanced UI
          • Standalone with TLS
          • Standalone with Audit Storage
          • External Vault
          • Using Kubernetes Auth Method
          • HA Cluster with Consul
          • HA Cluster with Raft
          • HA Enterprise Cluster with Raft
          • HA Enterprise DR Clusters with Raft
          • HA Enterprise Performance Clusters with Raft
          • Vault Agent Injector TLS Configuration
          • Vault Agent Injector TLS with Cert-Manager
        • Overview
        • Annotations
        • Installation
        • Examples
        • Overview
        • Installation
        • Configurations
        • Examples
      • Overview
      • Vault Lambda Extension
      • Running Vault
      • Overview
      • Installation
      • Configuration
      • Troubleshooting
      • Overview
      • Installation
      • Troubleshooting

    • Overview
    • Upgrade Plugins
    • Upgrade to 1.10.x
    • Upgrade to 1.9.x
    • Upgrade to 1.8.x
    • Upgrade to 1.7.x
    • Upgrade to 1.6.3
    • Upgrade to 1.6.2
    • Upgrade to 1.6.1
    • Upgrade to 1.6.0
    • Upgrade to 1.5.3
    • Upgrade to 1.5.2
    • Upgrade to 1.5.1
    • Upgrade to 1.5.0
    • Upgrade to 1.4.6
    • Upgrade to 1.4.5
    • Upgrade to 1.4.4
    • Upgrade to 1.4.1
    • Upgrade to 1.4.0
    • Upgrade to 1.3.10
    • Upgrade to 1.3.9
    • Upgrade to 1.3.8
    • Upgrade to 1.3.5
    • Upgrade to 1.3.4
    • Upgrade to 1.3.3
    • Upgrade to 1.3.2
    • Upgrade to 1.3.0
    • Upgrade to 1.2.7
    • Upgrade to 1.2.6
    • Upgrade to 1.2.5
    • Upgrade to 1.2.4
    • Upgrade to 1.2.1
    • Upgrade to 1.2.0
    • Upgrade to 1.1.2
    • Upgrade to 1.1.1
    • Upgrade to 1.1.0
    • Upgrade to 1.0.0
    • Upgrade to 0.11.6
    • Upgrade to 0.11.2
    • Upgrade to 0.11.0
    • Upgrade to 0.10.4
    • Upgrade to 0.10.2
    • Upgrade to 0.10.0
    • Upgrade to 0.9.6
    • Upgrade to 0.9.3
    • Upgrade to 0.9.2
    • Upgrade to 0.9.1
    • Upgrade to 0.9.0
    • Upgrade to 0.8.0
    • Upgrade to 0.7.0
    • Upgrade to 0.6.4
    • Upgrade to 0.6.3
    • Upgrade to 0.6.2
    • Upgrade to 0.6.1
    • Upgrade to 0.6.0
    • Upgrade to 0.5.1
    • Upgrade to 0.5.0

    • Overview
    • 1.10.0
    • 1.9.0
    • 1.8.0
    • 1.7.0
    • 1.6.0
    • 1.5.0

    • Overview
    • FAQ

    • Overview
    • Feature Deprecation Notice and Plans
    • License
    • Client Count
    • Login MFA
    • Server Side Consistent Token

  • Glossary

    • Overview
      • Overview
      • Autoloading
      • FAQ
    • Replication
      • Overview
      • Behavioral Changes
      • Security
    • Automated Integrated Storage Snapshots
    • Lease Count Quotas
    • Entropy Augmentation
    • Seal Wrap / FIPS 140-2
    • Namespaces
    • Performance Standbys
    • Eventual Consistency
    • Control Groups
    • Managed Keys
      • Overview
      • Duo MFA
      • Okta MFA
      • PingID MFA
      • TOTP MFA
      • Overview
      • Examples
      • Properties
    • HCP Vault
Type '/' to Search

»Vault Agent

A valid client token must accompany most requests to Vault. This includes all API requests, as well as via the Vault CLI and other libraries. Therefore, Vault clients must first authenticate with Vault to acquire a token. Vault provides several different authentication methods to assist in delivering this initial token.

Client authentication

If the client can securely acquire the token, all subsequent requests (e.g., request database credentials, read key/value secrets) are processed based on the trust established by a successful authentication.

This means that client application must invoke the Vault API to authenticate with Vault and manage the acquired token, in addition to invoking the API to request secrets from Vault. This implies code changes to client applications along with additional testing and maintenance of the application.

The following code example implements Vault API to authenticate with Vault through AppRole auth method, and then uses the returned client token to read secrets at kv-v2/data/creds.

package main

import (
    ...snip...
    vault "github.com/hashicorp/vault/api"
)

// Fetches a key-value secret (kv-v2) after authenticating via AppRole
func getSecretWithAppRole() (string, error) {
    config := vault.DefaultConfig()

    client := vault.NewClient(config)
    wrappingToken := ioutil.ReadFile("path/to/wrapping-token")
    unwrappedToken := client.Logical().Unwrap(strings.TrimSuffix(string(wrappingToken), "\n"))

    secretID := unwrappedToken.Data["secret_id"]
    roleID := os.Getenv("APPROLE_ROLE_ID")

    params := map[string]interface{}{
        "role_id":   roleID,
        "secret_id": secretID,
    }
    resp := client.Logical().Write("auth/approle/login", params)
    client.SetToken(resp.Auth.ClientToken)

    secret, err := client.Logical().Read("kv-v2/data/creds")
    if err != nil {
        return "", fmt.Errorf("unable to read secret: %w", err)
    }

    data := secret.Data["data"].(map[string]interface{})

    ...snip...
}
package main

import (
    ...snip...
    vault "github.com/hashicorp/vault/api"
)

// Fetches a key-value secret (kv-v2) after authenticating via AppRole
func getSecretWithAppRole() (string, error) {
    config := vault.DefaultConfig()

    client := vault.NewClient(config)
    wrappingToken := ioutil.ReadFile("path/to/wrapping-token")
    unwrappedToken := client.Logical().Unwrap(strings.TrimSuffix(string(wrappingToken), "\n"))

    secretID := unwrappedToken.Data["secret_id"]
    roleID := os.Getenv("APPROLE_ROLE_ID")

    params := map[string]interface{}{
        "role_id":   roleID,
        "secret_id": secretID,
    }
    resp := client.Logical().Write("auth/approle/login", params)
    client.SetToken(resp.Auth.ClientToken)

    secret, err := client.Logical().Read("kv-v2/data/creds")
    if err != nil {
        return "", fmt.Errorf("unable to read secret: %w", err)
    }

    data := secret.Data["data"].(map[string]interface{})

    ...snip...
}

For some Vault deployments, making (and maintaining) these changes to applications may not be a problem, and may actually be preferred. This may be applied to scenarios where you have a small number of applications or you want to keep strict, customized control over how each application interacts with Vault. However, in other situations where you have a large number of applications, as in large enterprises, you may not have the resources or expertise to update and maintain the Vault integration code for every application. When third party applications are being deployed by the application, it is prohibited to add the Vault integration code.

Vault Agent aims to remove this initial hurdle to adopt Vault by providing a more scalable and simpler way for applications to integrate with Vault.

»What is Vault Agent?

Vault Agent is a client daemon that provides the following features:

  • Auto-Auth - Automatically authenticate to Vault and manage the token renewal process for locally-retrieved dynamic secrets.
  • Caching - Allows client-side caching of responses containing newly created tokens and responses containing leased secrets generated off of these newly created tokens. The agent also manages the renewals of the cached tokens and leases.
  • Windows Service - Allows running the Vault Agent as a Windows service.
  • Templating - Allows rendering of user-supplied templates by Vault Agent, using the token generated by the Auto-Auth step.

»Auto-Auth

Vault Agent allows easy authentication to Vault in a wide variety of environments. Please see the Auto-Auth docs for information.

Auto-Auth functionality takes place within an auto_auth configuration stanza.

»Caching

Vault Agent allows client-side caching of responses containing newly created tokens and responses containing leased secrets generated off of these newly created tokens. Please see the Caching docs for information.

»API

»Quit

This endpoints triggers shutdown of the agent. By default, it is disabled, and can be enabled per listener using the agent_api stanza. It is recommended to only enable this on trusted interfaces, as it does not require any authorization to use.

MethodPath
POST/agent/v1/quit

»Cache

See the caching page for details on the cache API.

»Configuration

These are the currently-available general configuration option:

  • vault (vault: <optional>) - Specifies the remote Vault server the Agent connects to.

  • auto_auth (auto_auth: <optional>) - Specifies the method and other options used for Auto-Auth functionality.

  • cache (cache: <optional>) - Specifies options used for Caching functionality.

  • listener (listener: <optional>) - Specifies the addresses and ports on which the Agent will respond to requests.

  • pid_file (string: "") - Path to the file in which the agent's Process ID (PID) should be stored

  • exit_after_auth (bool: false) - If set to true, the agent will exit with code 0 after a single successful auth, where success means that a token was retrieved and all sinks successfully wrote it

  • template (template: <optional>) - Specifies options used for templating Vault secrets to files.

  • template_config (template_config: <optional>) - Specifies templating engine behavior.

  • telemetry (telemetry: <optional>) – Specifies the telemetry reporting system. See the telemetry Stanza section below for a list of metrics specific to Agent.

»vault Stanza

There can at most be one top level vault block and it has the following configuration entries:

  • address (string: <optional>) - The address of the Vault server. This should be a complete URL such as https://127.0.0.1:8200. This value can be overridden by setting the VAULT_ADDR environment variable.

  • ca_cert (string: <optional>) - Path on the local disk to a single PEM-encoded CA certificate to verify the Vault server's SSL certificate. This value can be overridden by setting the VAULT_CACERT environment variable.

  • ca_path (string: <optional>) - Path on the local disk to a directory of PEM-encoded CA certificates to verify the Vault server's SSL certificate. This value can be overridden by setting the VAULT_CAPATH environment variable.

  • client_cert (string: <optional>) - Path on the local disk to a single PEM-encoded CA certificate to use for TLS authentication to the Vault server. This value can be overridden by setting the VAULT_CLIENT_CERT environment variable.

  • client_key (string: <optional>) - Path on the local disk to a single PEM-encoded private key matching the client certificate from client_cert. This value can be overridden by setting the VAULT_CLIENT_KEY environment variable.

  • tls_skip_verify (string: <optional>) - Disable verification of TLS certificates. Using this option is highly discouraged as it decreases the security of data transmissions to and from the Vault server. This value can be overridden by setting the VAULT_SKIP_VERIFY environment variable.

  • tls_server_name (string: <optional>) - Name to use as the SNI host when connecting via TLS. This value can be overridden by setting the VAULT_TLS_SERVER_NAME environment variable.

»retry Stanza

The vault stanza may contain a retry stanza that controls how failing Vault requests are handled, whether these requests are issued in order to render templates, or are proxied requests coming from the proxy cache subsystem. Auto-auth, however, has its own notion of retrying and is not affected by this section.

For requests from the templating engine, Agent will reset its retry counter and perform retries again once all retries are exhausted. This means that templating will retry on failures indefinitely unless exit_on_retry_failure from the template_config stanza is set to true.

Here are the options for the retry stanza:

  • num_retries (int: 12) - Specify how many times a failing request will be retried. A value of 0 translates to the default, i.e. 12 retries. A value of -1 disables retries. The environment variable VAULT_MAX_RETRIES overrides this setting.

There are a couple of subtleties to be aware of here. First, requests originating from the proxy cache will only be retried if they resulted in specific HTTP result codes: any 50x code except 501 ("not implemented"), as well as 412 ("precondition failed"); 412 is used in Vault Enterprise 1.7+ to indicate a stale read due to eventual consistency. Requests coming from the template subsystem are retried regardless of the failure.

Second, templating retries may be performed by both the templating engine and the cache proxy if Agent persistent cache is enabled. This is due to the fact that templating requests go through the cache proxy when persistence is enabled.

Third, the backoff algorithm used to set the time between retries differs for the template and cache subsystems. This is a technical limitation we hope to address in the future.

»listener Stanza

Agent supports one or more listener stanzas. In addition to the standard listener configuration, an Agent's listener configuration also supports the following:

  • require_request_header (bool: false) - Require that all incoming HTTP requests on this listener must have an X-Vault-Request: true header entry. Using this option offers an additional layer of protection from Server Side Request Forgery attacks. Requests on the listener that do not have the proper X-Vault-Request header will fail, with a HTTP response status code of 412: Precondition Failed.

  • agent_api (agent_api: <optional>) - Manages optional Agent API endpoints.

»agent_api Stanza

  • enable_quit (bool: false) - If set to true, the agent will enable the quit API.

»telemetry Stanza

Vault Agent supports the telemetry stanza and collects various runtime metrics about its performance, the auto-auth and the cache status:

MetricDescriptionType
vault.agent.auth.failureNumber of authentication failurescounter
vault.agent.auth.successNumber of authentication successescounter
vault.agent.proxy.successNumber of requests successfully proxiedcounter
vault.agent.proxy.client_errorNumber of requests for which Vault returned an errorcounter
vault.agent.proxy.errorNumber of requests the agent failed to proxycounter
vault.agent.cache.hitNumber of cache hitscounter
vault.agent.cache.missNumber of cache missescounter

»Start Vault Agent

To run Vault Agent:

  1. Download the Vault binary where the client application runs (virtual machine, Kubernetes pod, etc.)

  2. Create a Vault Agent configuration file. (See the Example Configuration section for an example configuration.)

  3. Start a Vault Agent with the configuration file.

    Example:

    $ vault agent -config=/etc/vault/agent-config.hcl
    
    $ vault agent -config=/etc/vault/agent-config.hcl
    

    To get help, run:

    $ vault agent -h
    
    $ vault agent -h
    

»Example Configuration

An example configuration, with very contrived values, follows:

pid_file = "./pidfile"

vault {
  address = "https://127.0.0.1:8200"
  retry {
    num_retries = 5
  }
}

auto_auth {
  method "aws" {
    mount_path = "auth/aws-subaccount"
    config = {
      type = "iam"
      role = "foobar"
    }
  }

  sink "file" {
    config = {
      path = "/tmp/file-foo"
    }
  }

  sink "file" {
    wrap_ttl = "5m"
    aad_env_var = "TEST_AAD_ENV"
    dh_type = "curve25519"
    dh_path = "/tmp/file-foo-dhpath2"
    config = {
      path = "/tmp/file-bar"
    }
  }
}

cache {
  use_auto_auth_token = true
}

listener "unix" {
  address = "/path/to/socket"
  tls_disable = true

  agent_api {
    enable_quit = true
  }
}

listener "tcp" {
  address = "127.0.0.1:8100"
  tls_disable = true
}

template {
  source = "/etc/vault/server.key.ctmpl"
  destination = "/etc/vault/server.key"
}

template {
  source = "/etc/vault/server.crt.ctmpl"
  destination = "/etc/vault/server.crt"
}
pid_file = "./pidfile"

vault {
  address = "https://127.0.0.1:8200"
  retry {
    num_retries = 5
  }
}

auto_auth {
  method "aws" {
    mount_path = "auth/aws-subaccount"
    config = {
      type = "iam"
      role = "foobar"
    }
  }

  sink "file" {
    config = {
      path = "/tmp/file-foo"
    }
  }

  sink "file" {
    wrap_ttl = "5m"
    aad_env_var = "TEST_AAD_ENV"
    dh_type = "curve25519"
    dh_path = "/tmp/file-foo-dhpath2"
    config = {
      path = "/tmp/file-bar"
    }
  }
}

cache {
  use_auto_auth_token = true
}

listener "unix" {
  address = "/path/to/socket"
  tls_disable = true

  agent_api {
    enable_quit = true
  }
}

listener "tcp" {
  address = "127.0.0.1:8100"
  tls_disable = true
}

template {
  source = "/etc/vault/server.key.ctmpl"
  destination = "/etc/vault/server.key"
}

template {
  source = "/etc/vault/server.crt.ctmpl"
  destination = "/etc/vault/server.crt"
}
github logoEdit this page
DocsAPILearnCommunityPrivacySecurityPress KitConsent Manager