PKI secrets engine - quick start - root CA setup
This document provides a brief overview of setting up a Vault PKI Secrets Engine with a Root CA certificate.
Mount the backend
The first step to using the PKI backend is to mount it. Unlike the kv
backend, the pki backend is not mounted by default.
Configure a CA certificate
Next, Vault must be configured with a CA certificate and associated private key. We'll take advantage of the backend's self-signed root generation support, but Vault also supports generating an intermediate CA (with a CSR for signing) or setting a PEM-encoded certificate and private key bundle directly into the backend.
Generally you'll want a root certificate to only be used to sign CA intermediate certificates, but for this example we'll proceed as if you will issue certificates directly from the root. As it's a root, we'll want to set a long maximum life time for the certificate; since it honors the maximum mount TTL, first we adjust that:
That sets the maximum TTL for secrets issued from the mount to 10 years. (Note that roles can further restrict the maximum TTL.)
Now, we generate our root certificate:
The returned certificate is purely informational; it and its private key are safely stored in the backend mount.
Set URL configuration
Generated certificates can have the CRL location and the location of the issuing certificate encoded. These values must be set manually and typically to FQDN associated to the Vault server, but can be changed at any time.
Configure a role
The next step is to configure a role. A role is a logical name that maps to a policy used to generate those credentials. For example, let's create an "example-dot-com" role:
Issue certificates
By writing to the roles/example-dot-com path we are defining the
example-dot-com role. To generate a new certificate, we simply write
to the issue endpoint with that role name: Vault is now configured to create
and manage certificates!
Vault has now generated a new set of credentials using the example-dot-com
role configuration. Here we see the dynamically generated private key and
certificate.
Using ACLs, it is possible to restrict using the pki backend such that trusted operators can manage the role definitions, and both users and applications are restricted in the credentials they are allowed to read.
If you get stuck at any time, simply run vault path-help pki or with a
subpath for interactive help output.
Tutorial
Refer to the Build Your Own Certificate Authority (CA) guide for a step-by-step tutorial.
Have a look at the PKI Secrets Engine with Managed Keys for more about how to use externally managed keys with PKI.
API
The PKI secrets engine has a full HTTP API. Please see the PKI secrets engine API for more details.