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

website/content/api-docs/connect/ca.mdx

@@ -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
+- `ForceWithoutCrossSigning` `(bool: false)` - Indicates that the CA change
-  should be forced to complete even if the current CA doesn't support cross
+  should be forced to complete even if the current CA doesn't support root cross-signing.
-  signing. Changing root without cross-signing may cause temporary connection
+
-  failures until the rollout completes. See [Forced Rotation Without
+  ~> **Caution:** Setting this field to `true` will cause temporary connection failures
-  Cross-Signing](/docs/connect/ca#forced-rotation-without-cross-signing)
+  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

website/content/commands/connect/ca.mdx

@@ -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
+  should be forced to complete even if the current CA doesn't support root cross-signing.
-  signing. Changing root without cross-signing may cause temporary connection
+
-  failures until the rollout completes. See [Forced Rotation Without
+  ~> **Caution:** Use of this flag will cause temporary connection failures
-  Cross-Signing](/docs/connect/ca#forced-rotation-without-cross-signing)
+  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

website/content/docs/connect/ca/vault.mdx

@@ -7,40 +7,30 @@ description: >-
 
 # Vault as a Service Mesh Certificate Authority
 
-Consul can be used with [Vault](https://www.vaultproject.io/) to
+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. 
-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. 
-The Vault CA provider uses the
+This page describes how configure the Vault CA provider.
-[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.
+> **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.
-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.
 
 ## Requirements
 
-Prior to using Vault as a CA provider for Consul, the following requirements
+- Refer to [Service Mesh Certificate Authority Overview](/docs/connect/ca) for important background information about how Consul manages certificates with configurable CA providers.
-must be met:
 
-- **Vault 0.10.3 or later.** Consul uses URI SANs in the PKI engine which
+- Vault 0.10.3 to 1.10.x.
-  were introduced in Vault 0.10.3. Prior versions of Vault are not
-  compatible with Connect.
 
-~> **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
+You can enable Vault as the CA by configuring Consul to use `"vault"` as the CA provider
-setting the required configuration values.
+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 following example shows the required configurations for a default implementation:
-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"]}>
 
@@ -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
+You can specify the following configuration options.
-   (after the `/`) is used if you are adding the configuration to the agent's
+Note that a configuration option's name may differ between API calls and the agent configuration file.
-   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
+The `RootPKIPath` is the PKI engine for the root certificate.
-use this root certificate to sign the intermediate certificate. Consul will
+Consul uses this root certificate to sign the intermediate certificate.
-never attempt to write or modify any data within the root PKI path.
+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
+signed with the root certificate. The intermediate signs all leaf
-certificates and Consul may periodically generate new intermediates for
+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
+For each path, if the path does not exist, Consul attempts to mount and initialize
-initialize it. This requires additional privileges by the Vault token in use.
+a PKI secrets engine at that path. For this operation to succeed,
-If the paths already exist, Consul will use them as configured.
+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.
+Otherwise, use [Consul-managed PKI paths](#consul-managed-pki-paths) to let Consul fully automate PKI management.
-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`
+The following sections describe the Vault policy needed for both options.
-is `connect_inter`. These values should be updated for your environment.
+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 "<root_pki_path>/root/sign-self-issued" {
-path "/sys/mounts" {
+  capabilities = [ "sudo", "update" ]
-  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" ]
 }
 ```
-
 </CodeBlockConfig>
 
-### Consul Managed PKI Paths
+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:
-The following Vault policy allows Consul to create and manage the PKI paths in Vault.
+1. Create a new Vault token that includes both the `root/sign-self-issued`
-Consul is granted the ability to create the PKI mount points and given full
+   permission and the standard permissions for the current Consul or Vault
-control of the Root and Intermediate or Leaf CA for Connect clients.
+   managed PKI paths.
-
+1. Modify the CA provider configuration to use that new Vault token.
-In this example the `RootPKIPath` is `connect_root` and the `IntermediatePKIPath`
+1. Perform the CA provider configuration change that triggers the extremely privileged
-is `connect_inter`. These values should be updated for your environment.
+   root cross-sign operation. If the configuration change maintains Vault
-
+   as the provider but modifies `RootPKIPath`, the configuration change must
-<CodeBlockConfig filename="consul-managed-pki-policy.hcl">
+   include a Vault token or auth method with standard permissions for the new
-
+   Consul or Vault managed PKI paths.
-```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