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