open-consul/website/source/docs/connect/ca/vault.html.md
Paul Banks a84b82b3df
connect: Add AWS PCA provider (#6795)
* Update AWS SDK to use PCA features.

* Add AWS PCA provider

* Add plumbing for config, config validation tests, add test for inheriting existing CA resources created by user

* Unparallel the tests so we don't exhaust PCA limits

* Merge updates

* More aggressive polling; rate limit pass through on sign; Timeout on Sign and CA create

* Add AWS PCA docs

* Fix Vault doc typo too

* Doc typo

* Apply suggestions from code review

Co-Authored-By: R.B. Boyer <rb@hashicorp.com>
Co-Authored-By: kaitlincarter-hc <43049322+kaitlincarter-hc@users.noreply.github.com>

* Doc fixes; tests for erroring if State is modified via API

* More review cleanup

* Uncomment tests!

* Minor suggested clean ups
2019-11-21 17:40:29 +00:00

112 lines
4.5 KiB
Markdown

---
layout: "docs"
page_title: "Connect - Certificate Management"
sidebar_current: "docs-connect-ca-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/index.html)
to generate and sign certificates.
-> This page documents the specifics of the Vault CA provider.
Please read the [certificate management overview](/docs/connect/ca.html)
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.
* `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/index.html)
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.