luxolus
/
open-consul
2
0
Fork 0
Code Issues 1 Pull Requests Packages Releases Wiki Activity

docs: clarify Vault CA provider permissions needed (#15478)

This commit is contained in:
Jared Kirschner 2022-12-03 09:17:33 -05:00 committed by GitHub
parent 145289dc08
commit f73f0eb17f
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
3 changed files with 230 additions and 145 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

20
website/content/api-docs/connect/ca.mdx
View File

@ -169,6 +169,13 @@ The table below shows this endpoint's support for
The corresponding CLI command is [`consul connect ca set-config`](/commands/connect/ca#set-config).
~> **If currently using Vault CA provider:**
If you intend to change the CA provider from Vault to another,
or to change the Vault provider's [`RootPKIPath`](/docs/connect/ca/vault#rootpkipath),
you must temporarily elevate the privileges of the Vault token
or auth method in use as described in the
[Vault CA provider documentation](/docs/connect/ca/vault#additional-vault-acl-policies-for-sensitive-operations).
### JSON Request Body Schema
- `Provider` `(string: <required>)` - Specifies the CA provider type to use.
@ -177,11 +184,14 @@ The corresponding CLI command is [`consul connect ca set-config`](/commands/conn
for the chosen provider. For more information on configuring the Connect CA
providers, see [Provider Config](/docs/connect/ca).
- `ForceWithoutCrossSigning` `(bool: <optional>)` - Indicates that the CA change
should be forced to complete even if the current CA doesn't support cross
signing. Changing root without cross-signing may cause temporary connection
failures until the rollout completes. See [Forced Rotation Without
Cross-Signing](/docs/connect/ca#forced-rotation-without-cross-signing)
- `ForceWithoutCrossSigning` `(bool: false)` - Indicates that the CA change
should be forced to complete even if the current CA doesn't support root cross-signing.
~> **Caution:** Setting this field to `true` will cause temporary connection failures
until service mesh proxies and/or Consul client agents receive a new certificate
that establishes trust with the new root.
Do not use this field unless you are sure you need it.
Refer to [Forced Rotation Without Cross-Signing](/docs/connect/ca#forced-rotation-without-cross-signing)
for more detail.
### Sample Payload

18
website/content/commands/connect/ca.mdx
View File

@ -97,6 +97,13 @@ Configuration updated!
The return code will indicate success or failure.
~> **If currently using Vault CA provider:**
If you intend to change the CA provider from Vault to another,
or to change the Vault provider's [`RootPKIPath`](/docs/connect/ca/vault#rootpkipath),
you must temporarily elevate the privileges of the Vault token
or auth method in use as described in the
[Vault CA provider documentation](/docs/connect/ca/vault#additional-vault-acl-policies-for-sensitive-operations).
#### Command Options
- `-config-file` - (required) Specifies a JSON-formatted file to use for the new configuration.
@ -104,10 +111,13 @@ The return code will indicate success or failure.
[Update CA Configuration API](/api-docs/connect/ca#update-ca-configuration).
- `-force-without-cross-signing` `(bool: <optional>)` - Indicates that the CA change
should be forced to complete even if the current CA doesn't support cross
signing. Changing root without cross-signing may cause temporary connection
failures until the rollout completes. See [Forced Rotation Without
Cross-Signing](/docs/connect/ca#forced-rotation-without-cross-signing)
should be forced to complete even if the current CA doesn't support root cross-signing.
~> **Caution:** Use of this flag will cause temporary connection failures
until service mesh proxies and/or Consul client agents receive a new certificate
that establishes trust with the new root.
Do not use this flag unless you are sure you need it.
Refer to [Forced Rotation Without Cross-Signing](/docs/connect/ca#forced-rotation-without-cross-signing)
for more detail.
#### API Options

337
website/content/docs/connect/ca/vault.mdx
View File

@ -7,40 +7,30 @@ description: >-
# Vault as a Service Mesh Certificate Authority
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.
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.
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.
-> **Tip:** Complete the [tutorial](https://learn.hashicorp.com/tutorials/consul/vault-pki-consul-connect-ca?in=consul/vault-secure) to learn how to configure Vault as the Consul Connect service mesh Certification Authority.
> **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
Prior to using Vault as a CA provider for Consul, the following requirements
must be met:
- 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 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.
- Vault 0.10.3 to 1.10.x.
~> **Note:** Do not use Vault v1.11.0+ as Consul's Connect CA provider — the intermediate CA will become 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.
~> **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.
## Configuration
## Enable Vault as the CA
The Vault CA is enabled by setting the CA provider to `"vault"` and
setting the required configuration values.
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 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:
The following example shows the required configurations for a default implementation:
<CodeTabs heading="Connect CA configuration" tabs={["Agent configuration", "API"]}>
@ -53,9 +43,9 @@ connect {
ca_provider = "vault"
ca_config {
address = "http://localhost:8200"
token = "..."
token = "<vault-token-with-necessary-policy>"
root_pki_path = "connect-root"
intermediate_pki_path = "connect-intermediate"
intermediate_pki_path = "connect-dc1-intermediate"
}
}
```
@ -69,9 +59,9 @@ connect {
"Provider": "vault",
"Config": {
"Address": "http://localhost:8200",
"Token": "<token>",
"Token": "<vault-token-with-necessary-policy>",
"RootPKIPath": "connect-root",
"IntermediatePKIPath": "connect-intermediate"
"IntermediatePKIPath": "connect-dc1-intermediate"
}
}
```
@ -80,11 +70,12 @@ connect {
</CodeTabs>
The configuration options are listed below.
## Configuration Reference
-> **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.
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.
@ -115,7 +106,6 @@ The configuration options are listed below.
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.
@ -130,7 +120,7 @@ The configuration options are listed below.
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
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
@ -181,124 +171,199 @@ The configuration options are listed below.
@include 'http_api_connect_ca_common_options.mdx'
## Root and Intermediate PKI Paths
### 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.
for managing Consul service mesh 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 `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 is used to sign all leaf
certificates and Consul may periodically generate new intermediates for
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.
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.
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.
## Vault ACL Policies
### Configure Vault ACL policies ((#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.
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.
### Vault Managed PKI Paths
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
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.
Otherwise, use [Consul-managed PKI paths](#consul-managed-pki-paths) to let Consul fully automate PKI management.
In this example the `RootPKIPath` is `connect_root` and the `IntermediatePKIPath`
is `connect_inter`. These values should be updated for your environment.
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.
<CodeBlockConfig filename="vault-managed-pki-policy.hcl">
#### 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
# Existing PKI Mounts
path "/sys/mounts" {
capabilities = [ "read" ]
}
path "/sys/mounts/connect_root" {
capabilities = [ "read" ]
}
path "/sys/mounts/connect_inter" {
capabilities = [ "read" ]
}
# Needed for Consul 1.11+
path "/sys/mounts/connect_inter/tune" {
capabilities = [ "update" ]
}
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" ]
path "<root_pki_path>/root/sign-self-issued" {
capabilities = [ "sudo", "update" ]
}
```
</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" ]
}
# Needed for Consul 1.11+
path "/sys/mounts/connect_inter/tune" {
capabilities = [ "update" ]
}
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
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.