mirror of https://github.com/hashicorp/consul
187 lines
6.3 KiB
Markdown
187 lines
6.3 KiB
Markdown
---
|
|
layout: docs
|
|
page_title: Connect - Certificate Management
|
|
sidebar_title: Vault
|
|
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. An example configuration
|
|
is shown below:
|
|
|
|
```hcl
|
|
connect {
|
|
enabled = true
|
|
ca_provider = "vault"
|
|
ca_config {
|
|
address = "http://localhost:8200"
|
|
token = "..."
|
|
root_pki_path = "connect-root"
|
|
intermediate_pki_path = "connect-intermediate"
|
|
}
|
|
}
|
|
```
|
|
|
|
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're adding configuring 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 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 doesn't
|
|
exist, Consul will attempt to mount and configure this automatically.
|
|
|
|
- `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 doesn't 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 need to
|
|
also set tls_key_file.
|
|
|
|
- `KeyFile` / `key_file` (`string: ""`) - Specifies the path to the private
|
|
key used for Vault communication. If this is set then you need to also 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.
|
|
|
|
## 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.
|
|
|
|
```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" ]
|
|
}
|
|
```
|
|
|
|
### 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.
|
|
|
|
```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" ]
|
|
}
|
|
```
|