mirror of https://github.com/hashicorp/consul
370 lines
15 KiB
Markdown
370 lines
15 KiB
Markdown
---
|
|
layout: docs
|
|
page_title: Service Mesh Certificate Authority - Vault
|
|
description: >-
|
|
You can use a Vault PKI secrets engine as the Consul service mesh's certificate authority to secure your service mesh. Learn how to configure the Vault CA as a root CA or an intermediate CA connected to an existing PKI system, and how to manage PKI paths with either Vault or Consul.
|
|
---
|
|
|
|
# Vault as a Service Mesh Certificate Authority
|
|
|
|
You can configure Consul to use [Vault](https://www.vaultproject.io/) as the certificate authority (CA) so that Vault can manage and sign certificates distributed to services in the mesh.
|
|
The Vault CA provider uses the [Vault PKI secrets engine](https://www.vaultproject.io/docs/secrets/pki) to generate and sign certificates.
|
|
This page describes how configure the Vault CA provider.
|
|
|
|
> **Tutorial:** Complete the [Vault as Consul Service Mesh Certification Authority](/consul/tutorials/vault-secure/vault-pki-consul-connect-ca) tutorial for hands-on guidance on how to configure Vault as the Consul service mesh certification authority.
|
|
|
|
## Requirements
|
|
|
|
- Refer to [Service Mesh Certificate Authority Overview](/docs/connect/ca) for important background information about how Consul manages certificates with configurable CA providers.
|
|
|
|
- Vault 0.10.3 to 1.10.x.
|
|
|
|
~> **Compatibility warning:** Do not use Vault v1.11.0+ as Consul's Connect CA provider — the intermediate CA becomes unable to issue the leaf nodes required by service mesh, and by Consul client agents if using auto-encrypt or auto-config and using TLS for agent communication. If you are already using Vault 1.11+ as a Connect CA, refer to this [Knowledge Base article](https://support.hashicorp.com/hc/en-us/articles/11308460105491) for more information about the underlying cause and recommended workaround.
|
|
|
|
## Enable Vault as the CA
|
|
|
|
You can enable Vault as the CA by configuring Consul to use `"vault"` as the CA provider
|
|
and including the required provider configuration options.
|
|
You can provide the CA configuration in the server agents' configuration file
|
|
or in the body of a `PUT` request to the
|
|
[`/connect/ca/configuration`](/api-docs/connect/ca#update-ca-configuration) API endpoint.
|
|
Refer to the [Configuration Reference](#configuration-reference) for details about configuration options and for example use cases.
|
|
|
|
The following example shows the required configurations for a default implementation:
|
|
|
|
<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 = "<vault-token-with-necessary-policy>"
|
|
root_pki_path = "connect-root"
|
|
intermediate_pki_path = "connect-dc1-intermediate"
|
|
}
|
|
}
|
|
```
|
|
|
|
</CodeBlockConfig>
|
|
|
|
<CodeBlockConfig highlight="2,4-7">
|
|
|
|
```json
|
|
{
|
|
"Provider": "vault",
|
|
"Config": {
|
|
"Address": "http://localhost:8200",
|
|
"Token": "<vault-token-with-necessary-policy>",
|
|
"RootPKIPath": "connect-root",
|
|
"IntermediatePKIPath": "connect-dc1-intermediate"
|
|
}
|
|
}
|
|
```
|
|
|
|
</CodeBlockConfig>
|
|
|
|
</CodeTabs>
|
|
|
|
## Configuration Reference
|
|
|
|
You can specify the following configuration options.
|
|
Note that a configuration option's name may differ between API calls and the agent configuration file.
|
|
The first key refers to the option name for use in API calls.
|
|
The key after the slash refers to the corresponding option name in the agent 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-docs/system/mounts)
|
|
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 Consul service mesh certificates.
|
|
|
|
The `RootPKIPath` is the PKI engine for the root certificate.
|
|
Consul uses this root certificate to sign the intermediate certificate.
|
|
Consul does not 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 signs all leaf
|
|
certificates, and Consul may periodically generate new intermediates for
|
|
automatic rotation. Therefore, Consul requires write access to this path.
|
|
|
|
For each path, if the path does not exist, Consul attempts to mount and initialize
|
|
a PKI secrets engine at that path. For this operation to succeed,
|
|
the provided [Vault token](#token) must have the [required Vault privileges](#vault-acl-policies).
|
|
If the path does already exist, Consul uses the PKI secrets engine at that path as configured.
|
|
|
|
### Configure Vault ACL policies ((#vault-acl-policies))
|
|
|
|
The Vault CA provider requires a [Vault token](#token) with a specific set of Vault privileges
|
|
depending on whether you would prefer to control mount configuration from Vault or to delegate
|
|
that responsibility to Consul.
|
|
|
|
Use [Vault-managed PKI paths](#vault-managed-pki-paths) to obtain the following benefits:
|
|
- Enables use of a root CA external to Consul by instantiating the PKI secrets engine at
|
|
[`RootPKIPath`](#rootpkipath) with an intermediate certificate
|
|
- Retain full control over PKI mount creation, and over `RootPKIPath` mount configuration
|
|
|
|
Otherwise, use [Consul-managed PKI paths](#consul-managed-pki-paths) to let Consul fully automate PKI management.
|
|
|
|
The following sections describe the Vault policy needed for both options.
|
|
The policy snippets use placeholder values for `RootPKIPath` and `IntermediatePKIPath`.
|
|
Replace them to match the path values in your CA provider configuration.
|
|
|
|
#### Define a policy for Vault-managed PKI paths ((#vault-managed-pki-paths))
|
|
|
|
To use Vault-managed PKI paths, you must first instantiate and configure PKI secrets engines at
|
|
`RootPKIPath` and `IntermediatePKIPath`.
|
|
|
|
Then, attach the following Vault ACL policy to the CA provider's
|
|
[Vault token](#token) or [auth method](#authmethod):
|
|
|
|
1. Allow Consul to read both PKI mounts and to manage the intermediate PKI mount configuration:
|
|
|
|
<CodeBlockConfig filename="vault-managed-pki-policy.hcl">
|
|
|
|
```hcl
|
|
path "/sys/mounts/<root_pki_path>" {
|
|
capabilities = [ "read" ]
|
|
}
|
|
|
|
path "/sys/mounts/<intermediate_pki_path>" {
|
|
capabilities = [ "read" ]
|
|
}
|
|
|
|
path "/sys/mounts/<intermediate_pki_path>/tune" {
|
|
capabilities = [ "update" ]
|
|
}
|
|
```
|
|
|
|
</CodeBlockConfig>
|
|
|
|
1. Allow Consul read-only access to the root PKI engine, to automatically rotate
|
|
intermediate CAs as needed, and full use of the intermediate PKI engine:
|
|
|
|
<CodeBlockConfig filename="vault-managed-pki-policy.hcl">
|
|
|
|
```hcl
|
|
path "/<root_pki_path>/" {
|
|
capabilities = [ "read" ]
|
|
}
|
|
|
|
path "/<root_pki_path>/root/sign-intermediate" {
|
|
capabilities = [ "update" ]
|
|
}
|
|
|
|
path "/<intermediate_pki_path>/*" {
|
|
capabilities = [ "create", "read", "update", "delete", "list" ]
|
|
}
|
|
```
|
|
</CodeBlockConfig>
|
|
|
|
1. Allow Consul to renew its Vault token if the token is renewable.
|
|
The rule enables the token to be renewed whether it is provided
|
|
[directly](#token) in the CA provider configuration or presented in an [auth method](#authmethod).
|
|
|
|
<CodeBlockConfig filename="vault-managed-pki-policy.hcl">
|
|
|
|
```hcl
|
|
path "auth/token/renew-self" {
|
|
capabilities = [ "update" ]
|
|
}
|
|
|
|
path "auth/token/lookup-self" {
|
|
capabilities = [ "read" ]
|
|
}
|
|
```
|
|
|
|
</CodeBlockConfig>
|
|
|
|
#### Define a policy for Consul-managed PKI paths ((#consul-managed-pki-paths))
|
|
|
|
To use Consul-managed PKI paths, ensure no PKI secrets engines are mounted at
|
|
`RootPKIPath` and `IntermediatePKIPath`.
|
|
|
|
Then, attach the following Vault ACL policy to the CA provider's
|
|
[Vault token](#token) or [auth method](#authmethod):
|
|
|
|
1. Allow Consul to create and manage both PKI engines:
|
|
|
|
<CodeBlockConfig filename="consul-managed-pki-policy.hcl">
|
|
|
|
```hcl
|
|
path "/sys/mounts/<root_pki_path>" {
|
|
capabilities = [ "create", "read", "update", "delete", "list" ]
|
|
}
|
|
|
|
path "/sys/mounts/<intermediate_pki_path>" {
|
|
capabilities = [ "create", "read", "update", "delete", "list" ]
|
|
}
|
|
|
|
path "/sys/mounts/<intermediate_pki_path>/tune" {
|
|
capabilities = [ "update" ]
|
|
}
|
|
```
|
|
</CodeBlockConfig>
|
|
|
|
1. Allow Consul full use of both PKI engines:
|
|
|
|
<CodeBlockConfig filename="consul-managed-pki-policy.hcl">
|
|
|
|
```hcl
|
|
path "/<root_pki_path>/*" {
|
|
capabilities = [ "create", "read", "update", "delete", "list" ]
|
|
}
|
|
|
|
path "/<intermediate_pki_path>/*" {
|
|
capabilities = [ "create", "read", "update", "delete", "list" ]
|
|
}
|
|
```
|
|
|
|
</CodeBlockConfig>
|
|
|
|
1. Allow Consul to renew its Vault token if the token is renewable.
|
|
The rule enables the token to be renewed whether it is provided
|
|
[directly](#token) in the CA provider configuration or presented in an [auth method](#authmethod).
|
|
|
|
<CodeBlockConfig filename="consul-managed-pki-policy.hcl">
|
|
|
|
```hcl
|
|
path "auth/token/renew-self" {
|
|
capabilities = [ "update" ]
|
|
}
|
|
|
|
path "auth/token/lookup-self" {
|
|
capabilities = [ "read" ]
|
|
}
|
|
```
|
|
|
|
</CodeBlockConfig>
|
|
|
|
#### Additional Vault ACL policies for sensitive operations
|
|
|
|
Additional Vault permissions are required while you perform the
|
|
following CA provider configuration changes:
|
|
- Changing the provider from Vault to a different provider, such as Consul's built-in provider
|
|
- Changing the `RootPKIPath`
|
|
|
|
Those configuration modifications trigger a root CA change that requires an
|
|
extremely privileged root cross-sign operation.
|
|
For that operation to succeed, the CA provider's [Vault token](#token) or
|
|
[auth method](#authmethod) must contain the following rule:
|
|
|
|
<CodeBlockConfig filename="temporary-sensitive-operation-pki-policy.hcl">
|
|
|
|
```hcl
|
|
path "<root_pki_path>/root/sign-self-issued" {
|
|
capabilities = [ "sudo", "update" ]
|
|
}
|
|
```
|
|
</CodeBlockConfig>
|
|
|
|
We recommend using the following process when performing such a CA provider
|
|
configuration change to minimize the time that a privileged Vault token is in use:
|
|
1. Create a new Vault token that includes both the `root/sign-self-issued`
|
|
permission and the standard permissions for the current Consul or Vault
|
|
managed PKI paths.
|
|
1. Modify the CA provider configuration to use that new Vault token.
|
|
1. Perform the CA provider configuration change that triggers the extremely privileged
|
|
root cross-sign operation. If the configuration change maintains Vault
|
|
as the provider but modifies `RootPKIPath`, the configuration change must
|
|
include a Vault token or auth method with standard permissions for the new
|
|
Consul or Vault managed PKI paths.
|