87350f927f
* agent/auto-auth: add exit_on_err configurable * changelog * Update backoff function to quit * Clarify doc * Fix test
226 lines
10 KiB
Plaintext
226 lines
10 KiB
Plaintext
---
|
|
layout: docs
|
|
page_title: Vault Agent Auto-Auth
|
|
description: |-
|
|
Vault Agent's Auto-Auth functionality allows easy and automatic
|
|
authentication to Vault in a variety of environments.
|
|
---
|
|
|
|
# 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](/docs/concepts/response-wrapping).
|
|
|
|
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](https://github.com/hashicorp/vault/blob/main/helper/dhutil/dhutil.go)
|
|
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`](https://www.vaultproject.io/api-docs/auth/approle#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](https://godoc.org/github.com/hashicorp/vault/api#SecretWrapInfo)
|
|
structure. Uses [duration format strings](/docs/concepts/duration-format).
|
|
|
|
- `min_backoff` `(string or integer: "1s")` - The minimum backoff time Agent
|
|
will delay before retrying after a failed auth attempt. The backoff will start
|
|
at the configured value and double (with some randomness) after successive
|
|
failures, capped by `max_backoff.` If Agent templating is being used, this
|
|
value is also used as the min backoff time for the templating server.
|
|
Uses [duration format strings](/docs/concepts/duration-format).
|
|
|
|
- `max_backoff` `(string or integer: "5m")` - The maximum time Agent will delay
|
|
before retrying after a failed auth attempt. The backoff will start at
|
|
`min_backoff` and double (with some randomness) after successive failures,
|
|
capped by `max_backoff.` If Agent templating is being used, this value is also
|
|
used as the max backoff time for the templating server. `max_backoff` is the
|
|
duration between retries, and **not** the duration that retries will be
|
|
performed before giving up. Uses [duration format strings](/docs/concepts/duration-format).
|
|
|
|
- `exit_on_err` `(bool: false)` - When set to true, Vault Agent will exit if any
|
|
errors occur during authentication. This configurable only affects login attempts
|
|
for new tokens (either intial or expired tokens) and will not exit for errors on
|
|
valid token renewals.
|
|
|
|
- `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](https://godoc.org/github.com/hashicorp/vault/api#SecretWrapInfo)
|
|
structure. Uses [duration format strings](/docs/concepts/duration-format).
|
|
|
|
- `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
|
|
|
|
```hcl
|
|
# 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"
|
|
}
|
|
}
|
|
}
|
|
```
|