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 Auto-Auth

The Auto-Auth functionality of Vault Agent allows for easy authentication in a wide variety of environments.

»Functionality

Auto-Auth consists of two parts: a Method, which is the authentication method that should be used in the current environment; and any number of Sinks, which are locations where the agent should write a token any time the current token value has changed.

When the agent is started with Auto-Auth enabled, it will attempt to acquire a Vault token using the configured Method. On failure, it will exponentially back off and then retry. On success, unless the auth method is configured to wrap the tokens, it will keep the resulting token renewed until renewal is no longer allowed or fails, at which point it will attempt to reauthenticate.

Every time an authentication is successful, the token is written to the configured Sinks, subject to their configuration.

»Advanced Functionality

Sinks support some advanced features, including the ability for the written values to be encrypted or response-wrapped.

Both mechanisms can be used concurrently; in this case, the value will be response-wrapped, then encrypted.

»Response-Wrapping Tokens

There are two ways that tokens can be response-wrapped by the agent:

  1. By the auth method. This allows the end client to introspect the creation_path of the token, helping prevent Man-In-The-Middle (MITM) attacks. However, because the agent cannot then unwrap the token and rewrap it without modifying the creation_path, the agent is not able to renew the token; it is up to the end client to renew the token. The agent stays daemonized in this mode since some auth methods allow for reauthentication on certain events.

  2. By any of the token sinks. Because more than one sink can be configured, the token must be wrapped after it is fetched, rather than wrapped by Vault as it's being returned. As a result, the creation_path will always be sys/wrapping/wrap, and validation of this field cannot be used as protection against MITM attacks. However, this mode allows the agent to keep the token renewed for the end client and automatically reauthenticate when it expires.

»Encrypting Tokens

Support for encrypted tokens is experimental; if input/output formats change, we will make every effort to provide backwards compatibility.

Tokens can be encrypted, using a Diffie-Hellman exchange to generate an ephemeral key. In this mechanism, the client receiving the token writes a generated public key to a file. The sink responsible for writing the token to that client looks for this public key and uses it to compute a shared secret key, which is then used to encrypt the token via AES-GCM. The nonce, encrypted payload, and the sink's public key are then written to the output file, where the client can compute the shared secret and decrypt the token value.

NOTE: Token encryption is not a protection against MITM attacks! The purpose of this feature is for forward-secrecy and coverage against bare token values being persisted. A MITM that can write to the sink's output and/or client public-key input files could attack this exchange. Using TLS to protect the transit of tokens is highly recommended.

To help mitigate MITM attacks, additional authenticated data (AAD) can be provided to the agent. This data is written as part of the AES-GCM tag and must match on both the agent and the client. This of course means that protecting this AAD becomes important, but it provides another layer for an attacker to have to overcome. For instance, if the attacker has access to the file system where the token is being written, but not to read agent configuration or read environment variables, this AAD can be generated and passed to the agent and the client in ways that would be difficult for the attacker to find.

When using AAD, it is always a good idea for this to be as fresh as possible; generate a value and pass it to your client and agent on startup. Additionally, agent uses a Trust On First Use model; after it finds a generated public key, it will reuse that public key instead of looking for new values that have been written.

If writing a client that uses this feature, it will likely be helpful to look at the dhutil library. This shows the expected format of the public key input and envelope output formats.

»Configuration

The top level auto_auth block has two configuration entries:

  • method (object: required) - Configuration for the method

  • sinks (array of objects: optional) - Configuration for the sinks

»Configuration (Method)

Auto-auth does not support using tokens with a limited number of uses. Vault Agent does not track the number of uses remaining, and may allow the token to expire before attempting to renew it. For example, if using AppRole auto-auth, you must use 0 (meaning unlimited) as the value for token_num_uses.

These are common configuration values that live within the method block:

  • type (string: required) - The type of the method to use, e.g. aws, gcp, azure, etc. Note: when using HCL this can be used as the key for the block, e.g. method "aws" {...}.

  • mount_path (string: optional) - The mount path of the method. If not specified, defaults to a value of auth/<method type>.

  • namespace (string: optional) - Namespace in which the mount lives. The order of precedence is: this setting lowest, followed by the environment variable VAULT_NAMESPACE, and then the highest precedence command-line option -namespace. If none of these are specified, defaults to the root namespace. Note that because sink response wrapping and templating are also based on the client created by auto-auth, they use the same namespace.

  • wrap_ttl (string or integer: optional) - If specified, the written token will be response-wrapped by the agent. This is more secure than wrapping by sinks, but does not allow the agent to keep the token renewed or automatically reauthenticate when it expires. Rather than a simple string, the written value will be a JSON-encoded SecretWrapInfo structure. Values can be an integer number of seconds or a stringish value like 5m.

  • max_backoff (string or integer: "5m") - The maximum time Agent will delay before retrying after a failed auth attempt. The backoff will start at 1 second and double (with some randomness) after successive failures, capped by max_backoff. max_backoff is the duration between retries, and not the duration that retries will be performed before giving up.

  • config (object: required) - Configuration of the method itself. See the sidebar for information about each method.

»Configuration (Sinks)

These configuration values are common to all Sinks:

  • type (string: required) - The type of the method to use, e.g. file. Note: when using HCL this can be used as the key for the block, e.g. sink "file" {...}.

  • wrap_ttl (string or integer: optional) - If specified, the written token will be response-wrapped by the sink. This is less secure than wrapping by the method, but allows the agent to keep the token renewed and automatically reauthenticate when it expires. Rather than a simple string, the written value will be a JSON-encoded SecretWrapInfo structure. Values can be an integer number of seconds or a stringish value like 5m.

  • dh_type (string: optional) - If specified, the type of Diffie-Hellman exchange to perform, meaning, which ciphers and/or curves. Currently only curve25519 is supported.

  • dh_path (string: required if dh_type is set) - The path from which the agent should read the client's initial parameters (e.g. curve25519 public key).

  • derive_key (bool: false) - If specified, the final encryption key is calculated by using HKDF-SHA256 to derive a key from the calculated shared secret and the two public keys for enhanced security. This is recommended if backward compatibility isn't a concern.

  • aad (string: optional) - If specified, additional authenticated data to use with the AES-GCM encryption of the token. Can be any string, including serialized data.

  • aad_env_var (string: optional) - If specified, AAD will be read from the given environment variable rather than a value in the configuration file.

  • config (object: required) - Configuration of the sink itself. See the sidebar for information about each sink.

»Auto Auth Example

# Other Vault Agent configuration blocks
# ...

auto_auth {
  method {
    type = "approle"

    config = {
      role_id_file_path = "/etc/vault/roleid"
      secret_id_file_path = "/etc/vault/secretid"
    }
  }

  sink {
    type = "file"

    config = {
      path = "/tmp/file-foo"
    }
  }
}
# Other Vault Agent configuration blocks
# ...

auto_auth {
  method {
    type = "approle"

    config = {
      role_id_file_path = "/etc/vault/roleid"
      secret_id_file_path = "/etc/vault/secretid"
    }
  }

  sink {
    type = "file"

    config = {
      path = "/tmp/file-foo"
    }
  }
}
github logoEdit this page
DocsAPILearnCommunityPrivacySecurityPress KitConsent Manager