1---
2layout: "docs"
3page_title: "Consul - Secrets Engines"
4sidebar_title: "Consul"
5sidebar_current: "docs-secrets-consul"
6description: |-
7  The Consul secrets engine for Vault generates tokens for Consul dynamically.
8---
9
10# Consul Secrets Engine
11
12The Consul secrets engine generates [Consul](https://www.consul.io) API tokens
13dynamically based on Consul ACL policies.
14
15## Setup
16
17Most secrets engines must be configured in advance before they can perform their
18functions. These steps are usually completed by an operator or configuration
19management tool.
20
211. Enable the Consul secrets engine:
22
23    ```text
24    $ vault secrets enable consul
25    Success! Enabled the consul secrets engine at: consul/
26    ```
27
28    By default, the secrets engine will mount at the name of the engine. To
29    enable the secrets engine at a different path, use the `-path` argument.
30
312. In Consul versions below 1.4, acquire a [management token][consul-mgmt-token] from Consul, using the
32`acl_master_token` from your Consul configuration file or another management
33token:
34
35    ```sh
36    $ curl \
37        --header "X-Consul-Token: my-management-token" \
38        --request PUT \
39        --data '{"Name": "sample", "Type": "management"}' \
40        https://consul.rocks/v1/acl/create
41    ```
42
43    Vault must have a management type token so that it can create and revoke ACL
44    tokens. The response will return a new token:
45
46    ```json
47    {
48      "ID": "7652ba4c-0f6e-8e75-5724-5e083d72cfe4"
49    }
50    ```
51For Consul 1.4 and above, use the command line to generate a token with the appropriate policy:
52
53   ```sh
54   $ CONSUL_HTTP_TOKEN=d54fe46a-1f57-a589-3583-6b78e334b03b consul acl token create -policy-name=global-management
55   AccessorID:   865dc5e9-e585-3180-7b49-4ddc0fc45135
56   SecretID:     ef35f0f1-885b-0cab-573c-7c91b65a7a7e
57   Description:
58   Local:        false
59   Create Time:  2018-10-22 17:40:24.128188 -0700 PDT
60   Policies:
61       00000000-0000-0000-0000-000000000001 - global-management
62   ```
63
643. Configure Vault to connect and authenticate to Consul:
65
66    ```text
67    $ vault write consul/config/access \
68        address=127.0.0.1:8500 \
69        token=7652ba4c-0f6e-8e75-5724-5e083d72cfe4
70    Success! Data written to: consul/config/access
71    ```
72
734. Configure a role that maps a name in Vault to a Consul ACL policy. Depending on your Consul version,
74you will either provide a policy document and a token_type, or a set of policies.
75When users generate credentials, they are generated against this role. For Consul versions below 1.4:
76
77    ```text
78    $ vault write consul/roles/my-role policy=$(base64 <<< 'key "" { policy = "read" }')
79    Success! Data written to: consul/roles/my-role
80    ```
81The policy must be base64-encoded. The policy language is [documented by Consul](https://www.consul.io/docs/internals/acl.html).
82
83For Consul versions 1.4 and above, [generate a policy in Consul](https://www.consul.io/docs/guides/acl.html), and proceed to link it
84to the role:
85    ```text
86    $ vault write consul/roles/my-role policies=readonly
87    Success! Data written to: consul/roles/my-role
88    ```
89
90## Usage
91
92After the secrets engine is configured and a user/machine has a Vault token with
93the proper permission, it can generate credentials.
94
95Generate a new credential by reading from the `/creds` endpoint with the name
96of the role:
97
98```text
99$ vault read consul/creds/my-role
100Key                Value
101---                -----
102lease_id           consul/creds/my-role/b2469121-f55f-53c5-89af-a3ba52b1d6d8
103lease_duration     768h
104lease_renewable    true
105token              642783bf-1540-526f-d4de-fe1ac1aed6f0
106```
107
108When using Consul 1.4, the response will include the accessor for the token
109
110```text
111$ vault read consul/creds/my-role
112Key                Value
113---                -----
114lease_id           consul/creds/my-role/7miMPnYaBCaVWDS9clNE0Nv3
115lease_duration     768h
116lease_renewable    true
117accessor           6d5a0348-dffe-e87b-4266-2bec03800abb
118token              bc7a42c0-9c59-23b4-8a09-7173c474dc42
119```
120## API
121
122The Consul secrets engine has a full HTTP API. Please see the
123[Consul secrets engine API](/api/secret/consul/index.html) for more
124details.
125
126[consul-mgmt-token]: https://www.consul.io/docs/agent/http/acl.html#acl_create
127