mirror of https://github.com/hashicorp/consul
294 lines
11 KiB
Markdown
294 lines
11 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 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.
|
|
|
|
- `RootPKINamespace` / `root_pki_namespace` (`string: <optional>`) - The absolute namespace
|
|
that the `RootPKIPath` is in. Setting this parameter overrides the `Namespace` option for the `RootPKIPath`. Introduced in 1.12.3.
|
|
|
|
- `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`.
|
|
|
|
- `IntermediatePKINamespace` / `intermediate_pki_namespace` (`string: <optional>`) - The absolute namespace
|
|
that the `IntermediatePKIPath` is in. Setting this parameter overrides the `Namespace` option for the `IntermediatePKIPath`. Introduced in 1.12.3.
|
|
|
|
- `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 PKI can be managed by either Consul or by Vault. If you want to manually create and tune the PKI secret engines used to store the root and intermediate certificates, use Vault Managed PKI Paths. If you want to have the PKI automatically managed for you, use Consul Managed PKI Paths.
|
|
|
|
### 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/config/config-files#connect_ca_config
|
|
[`ca_provider`]: /docs/agent/config/config-files#connect_ca_provider
|
|
[`/connect/ca/configuration`]: /api-docs/connect/ca#update-ca-configuration
|