The Auto-Auth functionality of Vault Agent and Vault Proxy allow foreasy authentication in a wide variety of environments.
Auto-Auth consists of two parts: a Method, which is the authentication methodthat should be used in the current environment; and any number of Sinks, whichare locations where the agent should write a token any time the current tokenvalue has changed.
When Vault Agent or Vault Proxy are started with Auto-Auth enabled, it will attempt to acquire aVault token using the configured Method. On failure, it will exponentially backoff and then retry. On success, unless the auth method is configured to wrapthe tokens, it will keep the resulting token renewed until renewal is no longerallowed or fails, at which point it will attempt to reauthenticate.
Every time an authentication is successful, the token is written to theconfigured Sinks, subject to their configuration.
Advanced functionality
Sinks support some advanced features, including the ability for the writtenvalues to be encrypted orresponse-wrapped.
Both mechanisms can be used concurrently; in this case, the value will beresponse-wrapped, then encrypted.
Response-Wrapping tokens
There are two ways that tokens can be response-wrapped:
By the auth method. This allows the end client to introspect the
creation_pathof the token, helping prevent Man-In-The-Middle (MITM)attacks. However, because auto-auth cannot then unwrap the token and rewrapit without modifying thecreation_path, we are not able to renew thetoken; it is up to the end client to renew the token. Agent and Proxy bothstay daemonized in this mode since some auth methods allow for reauthenticationon certain events.By any of the token sinks. Because more than one sink can be configured, thetoken must be wrapped after it is fetched, rather than wrapped by Vault asit's being returned. As a result, the
creation_pathwill always besys/wrapping/wrap, and validation of this field cannot be used asprotection against MITM attacks. However, this mode allows auto-auth to keepthe token renewed for the end client and automatically reauthenticate whenit expires.
Encrypting tokens
Support for encrypted tokens is experimental; if input/output formatschange, we will make every effort to provide backwards compatibility.
Tokens can be encrypted, using a Diffie-Hellman exchange to generate anephemeral key. In this mechanism, the client receiving the token writes agenerated public key to a file. The sink responsible for writing the token tothat client looks for this public key and uses it to compute a shared secretkey, which is then used to encrypt the token via AES-GCM. The nonce, encryptedpayload, and the sink's public key are then written to the output file, wherethe client can compute the shared secret and decrypt the token value.
NOTE: Token encryption is not a protection against MITM attacks! The purposeof this feature is for forward-secrecy and coverage against bare token valuesbeing persisted. A MITM that can write to the sink's output and/or clientpublic-key input files could attack this exchange. Using TLS to protect thetransit of tokens is highly recommended.
To help mitigate MITM attacks, additional authenticated data (AAD) can beprovided to Agent and Proxy. This data is written as part of the AES-GCM tag and mustmatch on both Agent and Proxy and the client. This of course means that protectingthis AAD becomes important, but it provides another layer for an attacker tohave to overcome. For instance, if the attacker has access to the file systemwhere the token is being written, but not to read configuration or readenvironment variables, this AAD can be generated and passed to Agent or Proxy andthe 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 or Proxy on startup. Additionally,Agent and Proxy 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 beenwritten.
If writing a client that uses this feature, it will likely be helpful to lookat thedhutillibrary. This shows the expected format of the public key input and envelopeoutput formats.
The top level auto_auth block has two configuration entries:
method
(object: required)- Configuration for the methodsinks
(array of objects: optional)- Configuration for the sinks
Configuration (Method)
Auto-auth does not support using tokens with a limited number of uses. Auto-authdoes not track the number of uses remaining, and may allow the token toexpire before attempting to renew it. For example, if using AppRole auto-auth,you must use 0 (meaning unlimited) as the value fortoken_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 forthe block, e.g.method "aws" {...}.mount_path
(string: optional)- The mount path of the method. If notspecified, defaults to a value ofauth/<method type>.namespace
(string: optional)- Namespace in which the mount lives.The order of precedence is: this setting lowest, followed by theenvironment variableVAULT_NAMESPACE, and then the highest precedencecommand-line option-namespace.If none of these are specified, defaults to the root namespace.Note that because sink response wrapping and templating are also basedon the client created by auto-auth, they use the same namespace.If specified alongside thenamespaceoption in the Vault Stanza ofVault Agent orVault Proxy, thatconfiguration will take precedence on everything except auto-auth.wrap_ttl
(string or integer: optional)- If specified, the written tokenwill be response-wrapped by auto-auth. This is more secure than wrapping bysinks, but does not allow the auto-auth to keep the token renewed orautomatically reauthenticate when it expires. Rather than a simple string,the written value will be a JSON-encodedSecretWrapInfostructure. Uses duration format strings.min_backoff
(string or integer: "1s")- The minimum backoff time auto-authwill delay before retrying after a failed auth attempt. The backoff will startat the configured value and double (with some randomness) after successivefailures, capped bymax_backoff.If Agent templating is being used, thisvalue is also used as the min backoff time for the templating server.Uses duration format strings.max_backoff
(string or integer: "5m")- The maximum time Agent will delaybefore retrying after a failed auth attempt. The backoff will start atmin_backoffand double (with some randomness) after successive failures,capped bymax_backoff.If Agent templating is being used, this value is alsoused as the max backoff time for the templating server.max_backoffis theduration between retries, and not the duration that retries will beperformed before giving up. Uses duration format strings.exit_on_err
(bool: false)- When set to true, Vault Agent and Vault Proxywill exit if any errors occur during authentication. This configurable only affects loginattempts for new tokens (either initial or expired tokens) and will not exit for errors onvalid token renewals.config
(object: required)- Configuration of the method itself. See thesidebar 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 tokenwill be response-wrapped by the sink. This is less secure than wrapping bythe method, but allows auto-auth to keep the token renewed and automaticallyreauthenticate when it expires. Rather than a simple string, the writtenvalue will be a JSON-encodedSecretWrapInfostructure. Uses duration format strings.dh_type
(string: optional)- If specified, the type of Diffie-Hellman exchange toperform, meaning, which ciphers and/or curves. Currently onlycurve25519issupported.dh_path
(string: required if dh_type is set)- The path from which theauto-auth should read the client's initial parameters (e.g. curve25519 publickey).derive_key
(bool: false)- If specified, the final encryption key iscalculated by using HKDF-SHA256 to derive a key from the calculated sharedsecret and the two public keys for enhanced security. This is recommendedif backward compatibility isn't a concern.aad
(string: optional)- If specified, additional authenticated data touse with the AES-GCM encryption of the token. Can be any string, includingserialized data.aad_env_var
(string: optional)- If specified, AAD will be read from thegiven environment variable rather than a value in the configuration file.config
(object: required)- Configuration of the sink itself. See thesidebar for information about each sink.
Auto auth examples
Auto-Auth configuration objects take two separate forms when specified in HCLand JSON. The following examples are meant to clarify the differences betweenthe two formats.
Sinks (HCL format)
The HCL format may define any number of sink objects with an optional wrappingsinks {...} object.
Note: The corresponding JSON format must specify a"sinks" : [...] array to encapsulate all sink JSON objects.
// Other Vault Agent or Vault Proxy configuration blocks// ...auto_auth { method { type = "approle" config = { role_id_file_path = "/etc/vault/roleid" secret_id_file_path = "/etc/vault/secretid" } } sinks { sink { type = "file" config = { path = "/tmp/file-foo" } } }}The following valid HCL omits the wrapping sinks object while specifyingmultiple sinks.
// Other Vault Agent or Vault Proxy 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" } } sink { type = "file" config = { path = "/tmp/file-bar" } }}Sinks (JSON format)
The following JSON configuration illustrates the need for a sinks: [...] arraywrapping any number of sink objects.
{ "auto_auth" : { "method" : [ { type = "approle" config = { role_id_file_path = "/etc/vault/roleid" secret_id_file_path = "/etc/vault/secretid" } } ], "sinks" : [ { "sink" : { type = "file" config = { path = "/tmp/file-foo" } } } ] }}Multiple sinks are defined by appending more sink objects within the sinksarray:
{ "auto_auth" : { "method" : [ { type = "approle" config = { role_id_file_path = "/etc/vault/roleid" secret_id_file_path = "/etc/vault/secretid" } } ], "sinks" : [ { "sink" : { type = "file" config = { path = "/tmp/file-foo" } } }, { "sink" : { type = "file" config = { path = "/tmp/file-bar" } } } ] }}