open-vault/website/content/docs/secrets/consul.mdx

---
layout: docs
page_title: Consul - Secrets Engines
description: The Consul secrets engine for Vault generates tokens for Consul dynamically.
---

# Consul Secrets Engine

@include 'x509-sha1-deprecation.mdx'

@include 'consul-dataplane-compat.mdx'

The Consul secrets engine generates [Consul](https://www.consul.io/) API tokens
dynamically based on Consul ACL policies.

-> **Note:** See the Consul Agent [config documentation](https://developer.hashicorp.com/consul/docs/agent/config/config-files#acl-parameters)
for details on how to enable Consul's ACL system.

## 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.

1. (Optional) If you're only looking to set up a quick test environment, you can start a
    Consul Agent in dev mode in a separate terminal window.

    ```shell-session
    $ consul agent -dev -hcl "acl { enabled = true }"
    ```

1.  Enable the Consul secrets engine:

    ```shell-session
    $ vault secrets enable consul
    Success! 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.

1.  Configure Vault to connect and authenticate to Consul.

    Vault can bootstrap the Consul ACL system automatically if it is enabled and hasn't already
    been bootstrapped. 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.

    1.  Configuring Vault without previously bootstrapping the Consul ACL system:

        ```shell-session
        $ vault write consul/config/access \
            address="127.0.0.1:8500"
        Success! Data written to: consul/config/access
        ```

        ~> **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.

    1. Configuring Vault after manually bootstrapping the Consul ACL system:

        1.  For Consul 1.4 and above, use the command line to generate a token with the appropriate policy:

            ```shell-session
            $ CONSUL_HTTP_TOKEN="<bootstrap-token>" 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
            ```

            ```shell-session
            $ vault write consul/config/access \
                address="127.0.0.1:8500" \
                token="ef35f0f1-885b-0cab-573c-7c91b65a7a7e"
            Success! Data written to: consul/config/access
            ```

        1.  For Consul versions below 1.4, acquire a [management token][consul-mgmt-token] from Consul, using the
            `acl_master_token` from your Consul configuration file or another management token:

            ```shell-session
            $ 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:

            ```json
            {
            "ID": "7652ba4c-0f6e-8e75-5724-5e083d72cfe4"
            }
            ```

1.  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.

    1.  For Consul versions 1.8 and above, attach [a Consul node identity](https://developer.hashicorp.com/consul/commands/acl/token/create#node-identity) to the role.

        ```shell-session
        $ vault write consul/roles/my-role \
            node_identities="server-1:dc1" \
            node_identities="server-2:dc1"
        Success! Data written to: consul/roles/my-role
        ```

    1.  For Consul versions 1.5 and above, attach either [a role in Consul](https://developer.hashicorp.com/consul/api-docs/acl/roles) or [a Consul service identity](https://developer.hashicorp.com/consul/commands/acl/token/create#service-identity) to the role:

        ```shell-session
        $ vault write consul/roles/my-role consul_roles="api-server"
        Success! Data written to: consul/roles/my-role
        ```

        ```shell-session
        $ vault write consul/roles/my-role \
            service_identities="myservice-1:dc1,dc2" \
            service_identities="myservice-2:dc1"
        Success! Data written to: consul/roles/my-role
        ```

    1.  For Consul versions 1.4 and above, generate [a policy in Consul](https://learn.hashicorp.com/tutorials/consul/access-control-setup-production),
        and proceed to link it to the role:

        ```shell-session
        $ vault write consul/roles/my-role consul_policies="readonly"
        Success! Data written to: consul/roles/my-role
        ```

    1.  For Consul versions below 1.4, the policy must be base64-encoded. The policy language is
        [documented by Consul](https://developer.hashicorp.com/consul/docs/security/acl/acl-legacy). Support for this method is
        deprecated as of Vault 1.11.

        Write a policy and proceed to link it to the role:

        ```shell-session
        $ vault write consul/roles/my-role policy="$(echo 'key "" { policy = "read" }' | base64)"
        Success! 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 where duration is a [duration format strings](/docs/concepts/duration-format).

1.  You may further limit a role's access by adding the optional parameters `consul_namespace` and
    `partition`. Please refer to Consul's [namespace documentation](https://developer.hashicorp.com/consul/docs/enterprise/namespaces) and
    [admin partition documentation](https://developer.hashicorp.com/consul/docs/enterprise/admin-partitions) for further information about
    these features.

    1.  For Consul version 1.11 and above, link an admin partition to a role:

        ```shell-session
        $ vault write consul/roles/my-role consul_roles="admin-management" partition="admin1"
        Success! Data written to: consul/roles/my-role
        ```

    1.  For Consul versions 1.7 and above, link a Consul namespace to the role:

        ```shell-session
        $ vault write consul/roles/my-role consul_roles="namespace-management" consul_namespace="ns1"
        Success! Data written to: consul/roles/my-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:

```shell-session
$ 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
accessor            c81b9cf7-2c4f-afc7-1449-4e442b831f65
consul_namespace    ns1
local               false
partition           admin1
token               642783bf-1540-526f-d4de-fe1ac1aed6f0
```

!> **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](https://learn.hashicorp.com/tutorials/consul/vault-consul-secrets) for a
step-by-step tutorial.

## API

The Consul secrets engine has a full HTTP API. Please see the
[Consul secrets engine API](/api-docs/secret/consul) for more
details.

[consul-mgmt-token]: https://developer.hashicorp.com/consul/api-docs/acl#acl_create