Skip to main content
The PKI Secrets Engine in HashiCorp Vault dynamically issues and manages X.509 certificates for TLS and mutual TLS (mTLS) use cases. It automates private key generation, CSR submission, CA signing, and certificate retrieval—enforcing Vault’s authentication methods and ACL policies to authorize issuance.

​
Key Benefits of Vault PKI

FeatureBenefit
Automated Key & CSR GenerationEliminates manual certificate workflows
Short-lived CertificatesReduces reliance on revocation lists; improves security posture
Unique Certificates per WorkloadPrevents sharing, wildcard, or self-signed usage
Ephemeral TTLsEnsures certificates expire quickly
Integration with Existing CA HierarchiesActs as an intermediate CA under an offline root
The image is a slide about the PKI Secrets Engine, highlighting its benefits such as short TTLs for certificates, ease of allocation, and prevention of certificate sharing and MITM attacks. It also features a Vault certification badge and a cartoon character.
Workloads can request certificates at runtime and discard them on shutdown, avoiding long-lived revocation lists.

​
Vault as an Intermediate CA

Vault typically functions as an intermediate CA, integrating seamlessly with your offline root CA. The flow is:
  1. Vault generates an intermediate CSR.
  2. You sign it with the offline root CA.
  3. You import the signed intermediate certificate into Vault.
  4. Vault issues end-entity certificates on behalf of your root.
The image is a slide about the PKI Secrets Engine, explaining the use of Vault as an intermediate CA, its integration with existing CA structures, and its capability to perform root and intermediate CA functions. It includes a Vault certification badge and a cartoon character.
Never expose your root CA online. Keep the root CA offline and only use Vault’s intermediate for runtime operations.

​
Certificate Management Architecture

A typical deployment architecture:
  1. Root CA (offline, long-lived)
  2. Vault running the PKI Secrets Engine (intermediate CA)
  3. Clients (VMs, containers, applications) that authenticate to Vault and request certificates
The image illustrates a common architecture for certificate management, showing a Root Certificate Authority, a Vault with a PKI Secrets Engine as an Intermediate CA, and a process for requesting and responding with certificates.
Clients receive their unique certificates and private keys securely at runtime.

​
Enabling the PKI Secrets Engine

Enable Vault’s PKI engine at the default or a custom path: 
# Enable at default path "pki/"
vault secrets enable pki

# Or enable at custom path "hcvop_int/"
vault secrets enable -path=hcvop_int pki

​
Tuning the Maximum TTL

Set the maximum lease TTL to enforce certificate lifetimes: 
# Default PKI: max TTL = 30 days
vault secrets tune -max-lease-ttl=720h pki

# Custom PKI at "hcvop_int/": max TTL = 1 year
vault secrets tune -max-lease-ttl=8760h hcvop_int

​
Generating and Signing an Intermediate CSR

  1. Generate CSR in Vault (outputs JSON, extract CSR): 
    vault write -format=json \
  hcvop_int/intermediate/generate/internal \
  common_name="hcvop.com Intermediate" \
  | jq -r '.data.csr' > pki_intermediate.csr
  2. Sign CSR with your offline root CA and save as intermediate.cert.pem.
  3. Import the signed certificate back into Vault: 
    vault write hcvop_int/intermediate/set-signed \
  [email protected]

​
Configuring CA and CRL URLs

Clients fetch the issuer certificate and CRL via these URLs embedded in issued certs: 
vault write pki/config/urls \
  issuing_certificates="https://vault.example.com:8200/v1/pki/ca" \
  crl_distribution_points="https://vault.example.com:8200/v1/pki/crl"

​
Defining PKI Roles

A role in Vault maps policies to certificate settings (allowed domains, TTLs, SANs).
The image is an informational slide about PKI roles, explaining the mapping between a policy and configuration in a secrets engine, with notable configurations listed. It includes a Vault certification badge and a cartoon character illustration.

​
Example Role Configurations

The image describes unique PKI roles with configurations for web, internal apps, and Kubernetes apps, detailing allowed domains, subdomain permissions, and maximum TTL. It also includes a Vault certification badge and a cartoon character.
Role NameAllowed DomainsSubdomainsBare DomainsMax TTL
web_dmz_roledmz.hcvop.com✓✗720h
internal_appsapp.hcvop.com✓—24h
k8s_appsk8s.hcvop.com✓✗4h

​
Creating a PKI Role

vault write pki/roles/web_dmz_role \
  allowed_domains=dmz.hcvop.com \
  allow_subdomains=true \
  allow_bare_domains=false \
  allow_glob_domains=false \
  max_ttl=720h \
  allow_localhost=true \
  organization=hcvop \
  country=US
The image illustrates a process for creating roles in a Vault system, showing how different PKI roles request certificates for various applications. It includes icons representing Vault, roles, and applications, with a certification badge in the top right corner.
Applications authenticate to Vault and request certificates based on their assigned role.

​
Issuing Certificates

Issue a certificate for a given role: 
vault write pki/issue/web_dmz_role \
  common_name=dmzhcp01.dmz.hcvop.com \
  alt_names=portal.dmz.hcvop.com \
  max_ttl=720h
Response fields:
  • certificate: TLS certificate (PEM)
  • issuing_ca: CA certificate chain (Vault intermediate)
  • private_key: Private key (returned only once)
  • private_key_type: Key algorithm (e.g., rsa)
  • serial_number: Unique cert serial number
Always save the private_key immediately; Vault does not retain it for later retrieval.

​
Revoking Certificates

Revoke by serial number: 
vault write pki/revoke \
  serial_number="4d:00:01:30:20:2c:5e:31:ba:a9:7b"
The response includes revocation time in Unix and RFC 3339 formats.

​
Cleaning Up the Certificate Store

Periodically tidy expired and revoked certificates: 
vault write pki/tidy \
  tidy_cert_store=true \
  tidy_revoked_certs=true
Vault logs the tidy operation—monitor server logs for completion status.

​
References

Watch Video