mirror of https://github.com/hashicorp/consul
286 lines
10 KiB
Markdown
286 lines
10 KiB
Markdown
---
|
|
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.
|
|
|
|
-> **NOTE**: A Learn [tutorial](https://learn.hashicorp.com/tutorials/consul/vault-pki-consul-connect-ca?in=consul/vault-secure) is available to help you configure Vault as the Consul Connect service mesh Certification Authority.
|
|
|
|
## 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: ""`) - 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.
|
|
|
|
!> **Warning:** You must either provide a token or configure an auth method below.
|
|
|
|
- `AuthMethod` / `auth_method` (`map: nil`) - Vault auth method to use for logging in to Vault.
|
|
Please see [Vault Auth Methods](https://www.vaultproject.io/docs/auth) for more information
|
|
on how to configure individual auth methods. If auth method is provided, Consul will obtain a
|
|
a new token from Vault when the token can no longer be renewed.
|
|
|
|
- `Type`/ `type` (`string: ""`) - The type of Vault auth method.
|
|
|
|
- `MountPath`/ `mount_path` (`string: <AuthMethod.Type>`) - The mount path of the auth method.
|
|
If not provided the auth method type will be used as the mount path.
|
|
|
|
- `Params`/`params` (`map: nil`) - The parameters to configure the auth method. Please see
|
|
[Vault Auth Methods](https://www.vaultproject.io/docs/auth) for information on how to configure the
|
|
auth method you wish to use. If using the Kubernetes auth method,
|
|
Consul will read the service account token from the
|
|
default mount path `/var/run/secrets/kubernetes.io/serviceaccount/token` if the `jwt` parameter
|
|
is not provided.
|
|
|
|
|
|
- `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 the
|
|
`RootCertTTL` value as the root certificate's TTL. If the `RootCertTTL` is not set,
|
|
a [`max_lease_ttl`](https://www.vaultproject.io/api/system/mounts#max_lease_ttl)
|
|
of 87600 hours, or 10 years is applied by default as of Consul 1.11 and later. Prior to Consul 1.11,
|
|
the root certificate TTL was set to 8760 hour, or 1 year, and was not configurable.
|
|
The root certificate will expire at the end of the specified period.
|
|
|
|
When WAN Federation is enabled, each secondary datacenter must use the same Vault cluster and share the same `root_pki_path`
|
|
with the primary datacenter.
|
|
|
|
To use an intermediate certificate as the primary CA in Consul initialize the
|
|
`RootPKIPath` in Vault with a PEM bundle. The first certificate in the bundle
|
|
must be the intermediate certificate that Consul will use as the primary CA.
|
|
The last certificate in the bundle must be a root certificate. The bundle
|
|
must contain a valid chain, where each certificate is followed by the certificate
|
|
that authorized it.
|
|
|
|
- `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.
|
|
|
|
When WAN Federation is enabled, every secondary
|
|
datacenter must specify a unique `intermediate_pki_path`.
|
|
|
|
- `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.
|
|
|
|
- `Namespace` / `namespace` (`string: <optional>`) - The Vault Namespace that
|
|
the `Token` and PKI Certificates are a part of. Vault Namespaces are a Vault
|
|
Enterprise feature. Added in Consul 1.11.0
|
|
|
|
@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
|