open-consul/website/content/docs/connect/ca/vault.mdx

---
layout: docs
page_title: Connect - Certificate Management
description: >-
  Consul can be used with Vault to manage and sign certificates. The Vault CA
  provider uses the Vault PKI secrets engine to generate and sign certificates.
---

# Vault as a Connect CA

Consul can be used with [Vault](https://www.vaultproject.io) to
manage and sign certificates.
The Vault CA provider uses the
[Vault PKI secrets engine](https://www.vaultproject.io/docs/secrets/pki)
to generate and sign certificates.

-> This page documents the specifics of the Vault CA provider.
Please read the [certificate management overview](/docs/connect/ca)
page first to understand how Consul manages certificates with configurable
CA providers.

## Requirements

Prior to using Vault as a CA provider for Consul, the following requirements
must be met:

- **Vault 0.10.3 or later.** Consul uses URI SANs in the PKI engine which
  were introduced in Vault 0.10.3. Prior versions of Vault are not
  compatible with Connect.

## Configuration

The Vault CA is enabled by setting the CA provider to `"vault"` and
setting the required configuration values.

The configuration may either be provided in the agent's configuration file using
the [`ca_provider`] and [`ca_config`] options, or configured using the
[`/connect/ca/configuration`] API endpoint.

Example configurations are shown below:

<CodeTabs heading="Connect CA configuration" tabs={["Agent configuration", "API"]}>

<CodeBlockConfig filename="/etc/consul.d/config.hcl" highlight="4,6-9">

```hcl
# ...
connect {
  enabled = true
  ca_provider = "vault"
  ca_config {
    address = "http://localhost:8200"
    token = "..."
    root_pki_path = "connect-root"
    intermediate_pki_path = "connect-intermediate"
  }
}
```

</CodeBlockConfig>

<CodeBlockConfig highlight="2,4-7">

```json
{
  "Provider": "vault",
  "Config": {
    "Address": "http://localhost:8200",
    "Token": "<token>",
    "RootPKIPath": "connect-root",
    "IntermediatePKIPath": "connect-intermediate"
  }
}
```

</CodeBlockConfig>

</CodeTabs>

The configuration options are listed below.

-> **Note**: The first key is the value used in API calls, and the second key
   (after the `/`) is used if you are adding the configuration to the agent's
   configuration file.

- `Address` / `address` (`string: <required>`) - The address of the Vault
  server.

- `Token` / `token` (`string: <required>`) - A token for accessing Vault.
  This is write-only and will not be exposed when reading the CA configuration.
  This token must have [proper privileges](#vault-acl-policies) for the PKI
  paths configured. In Consul 1.8.5 and later, if the token has the [renewable](https://www.vaultproject.io/api-docs/auth/token#renewable)
  flag set, Consul will attempt to renew its lease periodically after half the
  duration has expired.

- `RootPKIPath` / `root_pki_path` (`string: <required>`) - The path to
  a PKI secrets engine for the root certificate. If the path does not
  exist, Consul will mount a new PKI secrets engine at the specified path with
  a [`max_lease_ttl`](https://www.vaultproject.io/api/system/mounts#max_lease_ttl)
  of 8760 hours, or 1 year. This TTL value specifies the expiry period of the
  root certificate and is currently not configurable.

- `IntermediatePKIPath` / `intermediate_pki_path` (`string: <required>`) -
  The path to a PKI secrets engine for the generated intermediate certificate.
  This certificate will be signed by the configured root PKI path. If this
  path does not exist, Consul will attempt to mount and configure this
  automatically.

- `CAFile` / `ca_file` (`string: ""`) - Specifies an optional path to the CA
  certificate used for Vault communication. If unspecified, this will fallback
  to the default system CA bundle, which varies by OS and version.

- `CAPath` / `ca_path` (`string: ""`) - Specifies an optional path to a folder
  containing CA certificates to be used for Vault communication. If
  unspecified, this will fallback to the default system CA bundle, which
  varies by OS and version.

- `CertFile` / `cert_file` (`string: ""`) - Specifies the path to the
  certificate used for Vault communication. If this is set, then you also need to
  set `key_file`.

- `KeyFile` / `key_file` (`string: ""`) - Specifies the path to the private
  key used for Vault communication. If this is set, then you also need to set
  `cert_file`.

- `TLSServerName` / `tls_server_name` (`string: ""`) - Specifies an optional
  string used to set the SNI host when connecting to Vault via TLS.

- `TLSSkipVerify` / `tls_skip_verify` (`bool: false`) - Specifies if SSL peer
  validation should be enforced.

@include 'http_api_connect_ca_common_options.mdx'

## Root and Intermediate PKI Paths

The Vault CA provider uses two separately configured
[PKI secrets engines](https://www.vaultproject.io/docs/secrets/pki)
for managing Connect certificates.

The `RootPKIPath` is the PKI engine for the root certificate. Consul will
use this root certificate to sign the intermediate certificate. Consul will
never attempt to write or modify any data within the root PKI path.

The `IntermediatePKIPath` is the PKI engine used for storing the intermediate
signed with the root certificate. The intermediate is used to sign all leaf
certificates and Consul may periodically generate new intermediates for
automatic rotation. Therefore, Consul requires write access to this path.

If either path does not exist, then Consul will attempt to mount and
initialize it. This requires additional privileges by the Vault token in use.
If the paths already exist, Consul will use them as configured.

## Vault ACL Policies

### Vault Managed PKI Paths

The following Vault policy allows Consul to use pre-existing PKI paths in Vault.
Consul is granted read-only access to the PKI mount points and the Root CA, but is
granted full control of the Intermediate or Leaf CA for Connect clients.

In this example the `RootPKIPath` is `connect_root` and the `IntermediatePKIPath`
is `connect_inter`. These values should be updated for your environment.

<CodeBlockConfig filename="vault-managed-pki-policy.hcl">

```hcl
# Existing PKI Mounts
path "/sys/mounts" {
  capabilities = [ "read" ]
}

path "/sys/mounts/connect_root" {
  capabilities = [ "read" ]
}

path "/sys/mounts/connect_inter" {
  capabilities = [ "read" ]
}

path "/connect_root/" {
  capabilities = [ "read" ]
}

path "/connect_root/root/sign-intermediate" {
  capabilities = [ "update" ]
}

path "/connect_inter/*" {
  capabilities = [ "create", "read", "update", "delete", "list" ]
}

path "auth/token/renew-self" {
	capabilities = [ "update" ]
}

path "auth/token/lookup-self" {
	capabilities = [ "read" ]
}
```

</CodeBlockConfig>

### Consul Managed PKI Paths

The following Vault policy allows Consul to create and manage the PKI paths in Vault.
Consul is granted the ability to create the PKI mount points and given full
control of the Root and Intermediate or Leaf CA for Connect clients.

In this example the `RootPKIPath` is `connect_root` and the `IntermediatePKIPath`
is `connect_inter`. These values should be updated for your environment.

<CodeBlockConfig filename="consul-managed-pki-policy.hcl">

```hcl
# Consul Managed PKI Mounts
path "/sys/mounts" {
  capabilities = [ "read" ]
}

path "/sys/mounts/connect_root" {
  capabilities = [ "create", "read", "update", "delete", "list" ]
}

path "/sys/mounts/connect_inter" {
  capabilities = [ "create", "read", "update", "delete", "list" ]
}

path "/connect_root/*" {
  capabilities = [ "create", "read", "update", "delete", "list" ]
}

path "/connect_inter/*" {
  capabilities = [ "create", "read", "update", "delete", "list" ]
}
```

</CodeBlockConfig>

<!-- Reference style links -->
[`ca_config`]: /docs/agent/options#connect_ca_config
[`ca_provider`]: /docs/agent/options#connect_ca_provider
[`/connect/ca/configuration`]: /api-docs/connect/ca#update-ca-configuration