»Consul Secrets Engine
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:
$ vault secrets enable consul
Success! Enabled the consul secrets engine at: consul/
$ vault secrets enable consulSuccess! Enabled the consul secrets engine at: consul/
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.
-
In 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:
$ curl \
--header "X-Consul-Token: my-management-token" \
--request PUT \
--data '{"Name": "sample", "Type": "management"}' \
https://consul.rocks/v1/acl/create
$ curl \ --header "X-Consul-Token: my-management-token" \ --request PUT \ --data '{"Name": "sample", "Type": "management"}' \ https://consul.rocks/v1/acl/create
Vault must have a management type token so that it can create and revoke ACL
tokens. The response will return a new token:
{
"ID": "7652ba4c-0f6e-8e75-5724-5e083d72cfe4"
}
{ "ID": "7652ba4c-0f6e-8e75-5724-5e083d72cfe4"}
For Consul 1.4 and above, use the command line to generate a token with the appropriate policy:
$ CONSUL_HTTP_TOKEN=d54fe46a-1f57-a589-3583-6b78e334b03b consul acl token create -policy-name=global-management
AccessorID: 865dc5e9-e585-3180-7b49-4ddc0fc45135
SecretID: ef35f0f1-885b-0cab-573c-7c91b65a7a7e
Description:
Local: false
Create Time: 2018-10-22 17:40:24.128188 -0700 PDT
Policies:
00000000-0000-0000-0000-000000000001 - global-management
$ CONSUL_HTTP_TOKEN=d54fe46a-1f57-a589-3583-6b78e334b03b consul acl token create -policy-name=global-managementAccessorID: 865dc5e9-e585-3180-7b49-4ddc0fc45135SecretID: ef35f0f1-885b-0cab-573c-7c91b65a7a7eDescription:Local: falseCreate Time: 2018-10-22 17:40:24.128188 -0700 PDTPolicies: 00000000-0000-0000-0000-000000000001 - global-management
-
Configure Vault to connect and authenticate to Consul:
$ vault write consul/config/access \
address=127.0.0.1:8500 \
token=7652ba4c-0f6e-8e75-5724-5e083d72cfe4
Success! Data written to: consul/config/access
$ vault write consul/config/access \ address=127.0.0.1:8500 \ token=7652ba4c-0f6e-8e75-5724-5e083d72cfe4Success! Data written to: consul/config/access
-
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, or a set of policies.
When users generate credentials, they are generated against this role. For Consul versions below 1.4:
$ vault write consul/roles/my-role policy=$(base64 <<< 'key "" { policy = "read" }')
Success! Data written to: consul/roles/my-role
$ vault write consul/roles/my-role policy=$(base64 <<< 'key "" { policy = "read" }')Success! Data written to: consul/roles/my-role
The policy must be base64-encoded. The policy language is documented by Consul.
For Consul versions 1.4 and above, generate a policy in Consul, and proceed to link it to the role:
$ vault write consul/roles/my-role policies=readonly
Success! Data written to: consul/roles/my-role
$ vault write consul/roles/my-role policies=readonlySuccess! Data written to: consul/roles/my-role
Token lease duration: If you do not specify a value for ttl
(or lease
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".
»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:
$ vault read consul/creds/my-role
Key Value
--- -----
lease_id consul/creds/my-role/b2469121-f55f-53c5-89af-a3ba52b1d6d8
lease_duration 768h
lease_renewable true
token 642783bf-1540-526f-d4de-fe1ac1aed6f0
$ vault read consul/creds/my-roleKey Value--- -----lease_id consul/creds/my-role/b2469121-f55f-53c5-89af-a3ba52b1d6d8lease_duration 768hlease_renewable truetoken 642783bf-1540-526f-d4de-fe1ac1aed6f0
When using Consul 1.4, the response will include the accessor for the token
$ vault read consul/creds/my-role
Key Value
--- -----
lease_id consul/creds/my-role/7miMPnYaBCaVWDS9clNE0Nv3
lease_duration 768h
lease_renewable true
accessor 6d5a0348-dffe-e87b-4266-2bec03800abb
token bc7a42c0-9c59-23b4-8a09-7173c474dc42
$ vault read consul/creds/my-roleKey Value--- -----lease_id consul/creds/my-role/7miMPnYaBCaVWDS9clNE0Nv3lease_duration 768hlease_renewable trueaccessor 6d5a0348-dffe-e87b-4266-2bec03800abbtoken bc7a42c0-9c59-23b4-8a09-7173c474dc42
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.
»Learn
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.