Consul secrets engine
Note: This engine can use external X.509 certificates as part of TLS or signature validation. Verifying signatures against X.509 certificates that use SHA-1 is deprecated and will no longer be usable without a workaround starting in Vault 1.12. See the deprecation FAQ for more information.
The Consul secrets engine generates Consul API tokens dynamically based on Consul ACL policies.
Setup
Most secrets engines must be configured in advance before they can perform their functions. These steps are usually completed by an operator or configuration management tool.
Enable the Consul secrets engine:
By default, the secrets engine will mount at the name of the engine. To enable the secrets engine at a different path, use the
-path
argument.Configure Vault to connect and authenticate to Consul.
Vault can bootstrap the Consul ACL system automatically if it hasn't already been done. If you have already bootstrapped the ACL system, then you will need to provide Vault with a management token. This can either be the bootstrap token or another management token you've created yourself.
Configuring Vault without previously bootstrapping the Consul ACL system:
Note: Vault will silently store the bootstrap token as the configuration token when it performs the automatic bootstrap; it will not be presented to the user. If you need another management token, you will need to generate one by writing a Vault role with the
global-management
policy and then reading new creds back from it.Configuring Vault after manually bootstrapping the Consul ACL system:
For Consul 1.4 and above, use the command line to generate a token with the appropriate policy:
For Consul versions below 1.4, acquire a management token from Consul, using the
acl_master_token
from your Consul configuration file or another management token:Vault must have a management type token so that it can create and revoke ACL tokens. The response will return a new token:
Configure a role that maps a name in Vault to a Consul ACL policy. Depending on your Consul version, you will either provide a policy document and a token type, a list of policies or roles, or a set of service or node identities. When users generate credentials, they are generated against this role.
For Consul versions 1.8 and above, attach a Consul node identity to the role.
For Consul versions 1.5 and above, attach either a role in Consul or a Consul service identity to the role:
For Consul versions 1.4 and above, generate a policy in Consul, and proceed to link it to the role:
For Consul versions below 1.4, the policy must be base64-encoded. The policy language is documented by Consul. Support for this method is deprecated as of Vault 1.11.
Write a policy and proceed to link it to the role:
Token lease duration: If you do not specify a value for
ttl
(orlease
for Consul versions below 1.4) the tokens created using Vault's Consul secrets engine are created with a Time To Live (TTL) of 30 days. You can change the lease duration by passing-ttl=<duration>
to the command above with "duration" being a string with a time suffix like "30s" or "1h".
You may further limit a role's access by adding the optional parameters
consul_namespace
andpartition
. Please refer to Consul's namespace documentation and admin partition documentation for further information about these features.For Consul version 1.11 and above, link an admin partition to a role:
For Consul versions 1.7 and above, link a Consul namespace to the role:
Usage
After the secrets engine is configured and a user/machine has a Vault token with the proper permission, it can generate credentials.
Generate a new credential by reading from the /creds
endpoint with the name
of the role:
Expired token rotation: Once a token's TTL expires, then Consul operations will no longer be allowed with it.
This requires you to have an external process to rotate tokens. At this time, the recommended approach for operators
is to rotate the tokens manually by creating a new token using the vault read consul/creds/my-role
command. Once
the token is synchronized with Consul, apply the token to the agents using the Consul API or CLI.
Tutorial
Refer to Administer Consul Access Control Tokens with Vault for a step-by-step tutorial.
API
The Consul secrets engine has a full HTTP API. Please see the Consul secrets engine API for more details.