Vault PKI Engine: Practical Guide to Certificate Issuance & Management (Associate/Ops)

This article distills practical guidance for safely issuing and managing certificates with Vault's PKI engine, aligned with the Associate/Ops certification scope.

Grounded in stable features from the official documentation, it walks through terminology, setup, role design, operations, security, and troubleshooting end-to-end.

PKI Engine Overview and Core Terminology

Vault's PKI engine is a dedicated secrets engine that issues and revokes X.509 certificates from an internal or external Root CA / Intermediate CA, and serves CRLs and (depending on version) OCSP responses. Operations revolve around roles, which define constraints such as allowed domains, SANs, TTL, key type/size, and Key Usage.

The recommended design uses an offline Root CA to sign an Intermediate CA, then mounts that Intermediate CA in Vault to handle day-to-day issuance. CRL distribution points and issuing-CA URLs are configured as public endpoints via pki/config/urls.

A point of frequent confusion on both the exam and in practice is the TTL boundary. The request-time ttl cannot exceed either the role's max_ttl or the engine's max-lease-ttl (set via tune). Revocation is done by serial_number, and CRLs should be configured for auto-rebuild so clients always receive the latest state.

• Roles are the heart of the issuance policy (allowed_domains, allow_subdomains, key_type, max_ttl, etc.)
• ttl ≤ role.max_ttl ≤ mount.max_lease_ttl (exceeding any of these fails)
• Offline Root + Vault Intermediate CA is the production standard
• Publish CRL and issuing-CA URLs externally via pki/config/urls
• Choose between CSR signing (sign/<role>) and key-included issuance (issue/<role>) based on requirements

Issuance flow (offline Root + Vault Intermediate CA)

 [Client]                          [Vault (pki_int)]                      [Offline Root]
    |   CSR (optional)  issue/sign         |   verify policy/role          |  used only to sign
    |------------------------------------->|--------------------------------|  intermediate once
    |                                      |                                 |
    |<------------ cert/key/chain ---------|                                 |
    |                                      |-- CRL build / OCSP (ver.dep) --|
    |<------------- CRL/OCSP --------------|                                 |

 Notes:
 - Vault holds the Intermediate CA. The Root stays offline.
 - Issuance: issue/<role> generates and returns the private key; sign/<role> signs an external CSR.
 - CRL/OCSP distribution URLs are configured via pki/config/urls.

Conceptual section (CLI examples follow in later sections)

# This section covers terminology and the big picture.
# See later sections for actual commands.

Setup: From Minimal Config to Production

A minimal setup uses a single mount with an embedded Root CA for immediate issuance, but production runs on an offline Root + Vault Intermediate CA. Splitting Root and Intermediate into separate mounts cleanly separates TTL and operational policies.

Configure URL publication (issuing_certificates, crl_distribution_points) early so applications can immediately reach the certificate chain and the CRL.

• Separate the Root mount (pki_root) from the Intermediate mount (pki_int)
• Sign the Intermediate CA's CSR with the Root, then import the bundle into pki_int
• Always configure pki_int/config/urls (so the CA chain and CRL are externally reachable)
• Define roles → test issuance → verify CRL auto-rebuild

Typical procedure (offline Root + Vault Intermediate CA)

# 1) Create mounts (separating Root/Intermediate is recommended)
vault secrets enable -path=pki_root pki
vault secrets tune  -path=pki_root -max-lease-ttl=87600h

vault secrets enable -path=pki_int pki
vault secrets tune  -path=pki_int  -max-lease-ttl=8760h

# 2) Generate the Root internally (if running Root offline, isolate/stop afterwards)
vault write pki_root/root/generate/internal \
  common_name="Example Corp Root CA" \
  ttl=87600h

# 3) Generate the Intermediate CA's CSR
vault write -field=csr pki_int/intermediate/generate/internal \
  common_name="Example Corp Intermediate CA" > pki_int.csr

# 4) Sign the Intermediate with the Root and import the bundle
vault write -field=certificate pki_root/root/sign-intermediate \
  csr=@pki_int.csr format=pem_bundle ttl=43800h > pki_int.pem
vault write pki_int/intermediate/set-signed certificate=@pki_int.pem

# 5) Configure published URLs (external reachability for CA chain / CRL)
vault write pki_int/config/urls \
  issuing_certificates="https://vault.example.com/v1/pki_int/ca" \
  crl_distribution_points="https://vault.example.com/v1/pki_int/crl"

# 6) Create a role (issuance policy)
vault write pki_int/roles/web \
  allowed_domains="example.com" \
  allow_subdomains=true \
  allow_bare_domains=true \
  max_ttl="168h" \
  key_type="rsa" key_bits=2048 \
  require_cn=false

# 7) Issue (with key bundled)
vault write pki_int/issue/web \
  common_name="api.example.com" \
  alt_names="api-1.example.com" \
  ip_sans="10.0.0.10" \
  uri_sans="spiffe://cluster/ns/prod/sa/api" \
  ttl="24h"

# 8) CRL auto-rebuild (parameter names/details vary by version — verify before rollout)
vault write pki_int/config/crl auto_rebuild=true expiry="72h"

Role Design and Issuance Parameters (High-Yield Exam Topics)

A role is the minimum unit that constrains "which names, with which keys/extensions, and up to what max TTL can be issued." SAN-based operation is the norm today, so it's safer to set require_cn=false and avoid CN dependence.

The ttl parameter is capped by both the role's max_ttl and the engine's max-lease-ttl. Exceeding either one fails. Specify KeyUsage / ExtKeyUsage explicitly for the intended purpose (e.g., server authentication, client authentication).

• Combine allowed_domains and allow_subdomains to define the allowed FQDN scope
• Control SAN types with allowed_uri_sans and allowed_ip_sans
• key_type=rsa|ec; pick key_bits for RSA or named_curve for EC
• Match key_usage and ext_key_usage to the intended use (server_auth, client_auth, etc.)
• Choose between sign/<role> (CSR signing) and issue/<role> (Vault generates the key)

Role definition and CSR signing example

# Role allowing both server authentication and client authentication
vault write pki_int/roles/app \
  allowed_domains="svc.cluster.local,example.internal" \
  allow_subdomains=true \
  require_cn=false \
  max_ttl="240h" \
  key_type="ec" \
  key_bits=256 \
  key_usage="DigitalSignature,KeyEncipherment" \
  ext_key_usage="ServerAuth,ClientAuth" \
  allowed_uri_sans="spiffe://cluster/*" \
  allowed_ip_sans="10.0.0.0/8"

# Sign a CSR (private key stays with the application)
openssl req -new -newkey rsa:2048 -nodes -keyout server.key -subj "/CN=api.svc.cluster.local" -reqexts SAN \
  -config <(printf "[req]\ndistinguished_name=req\n[SAN]\nsubjectAltName=DNS:api.svc.cluster.local,URI:spiffe://cluster/ns/prod/sa/api") \
  -out server.csr

vault write pki_int/sign/app [email protected] ttl="24h"

Issuance, Revocation, and CRL/OCSP Operations

Revoke by serial_number. Enable CRL auto-rebuild and periodically verify that clients can fetch it via the distribution URL. When issuance volume is high, clean up stale entries with tidy (keeping a sufficient safety buffer).

OCSP availability and delivery vary by version, so check support before adopting it. CRL-only validation can work too; choose based on your response-latency requirements.

• Revoke: vault write pki_int/revoke serial_number=...
• CRL auto-rebuild (auto_rebuild) and URL publication (config/urls)
• Use tidy's safety_buffer to protect near-future revocation and expiry boundaries
• Monitor CRL size and distribution latency during high-volume issuance
• Track signing operations via the audit device (audit logs)

Operational command examples (revoke, CRL, tidy)

# Revoke (serial is commonly in colon-separated form)
vault write pki_int/revoke serial_number="15:3a:9f:..."

# Current CRL (distributed over HTTP; CLI example for reference)
curl -s https://vault.example.com/v1/pki_int/crl > crl.pem

# Tidy (sweep old/revoked certificates). Run during maintenance windows in production
vault write pki_int/tidy \
  safety_buffer="72h" \
  tidy_cert_store=true \
  tidy_revoked_certs=true

Security & Availability (Policies, TTL Boundaries, HA)

Protect issuance APIs with least privilege. Grant policies scoped to a specific role's issue/sign only, and separate the authority to change CAs or role definitions into a different role. Always enable audit logging so issuance and revocation requests are traceable.

TTL boundaries form three layers: the engine (mount) max-lease-ttl, the role max_ttl, and the request ttl. If you can't meet the expected TTL, identify which layer is constraining it. Vault's own HA / replication design directly determines the availability of the PKI engine.

• Policies expose only the issue/sign endpoints (least privilege)
• Separate role-definition changes into an admin-only policy
• Enable and protect audit logs (tamper-evidence)
• mount.max-lease-ttl ≥ role.max_ttl ≥ issuance ttl
• Isolate impact by separating PKI mounts

Policy example (allow issuance only for a specific role)

# pki-issue.hcl
path "pki_int/issue/web" {
  capabilities = ["create", "update"]
}
path "pki_int/sign/web" {
  capabilities = ["create", "update"]
}
# Management capabilities (role creation/changes, CA updates) belong to a separate admin-only policy

# Tune the mount's max TTL to match your operations
vault secrets tune -path=pki_int -max-lease-ttl=168h

Troubleshooting and Common Pitfalls

TTL-exceeded errors almost always come down to role.max_ttl or mount.max-lease-ttl. Check the role definition and mount config first. If SANs are rejected, review the role's allowed_*_sans for sufficient coverage.

If the CRL grows large, revisit expiry and rebuild intervals against your issuance/revocation cadence and bake tidy into the operational plan. Chain inconsistencies (missing intermediate certificate) usually mean config/urls issuing_certificates isn't publishing correctly.

• Error: requested ttl is greater than the maximum allowed → check role.max_ttl and mount.max-lease-ttl
• SAN rejection → recheck allowed_uri_sans / allowed_ip_sans / allowed_domains
• Chain inconsistency → verify the correct chain can be fetched from the issuing_certificates URL
• CRL fetch failure → check crl_distribution_points publication and network reachability
• Serial format mistakes → standardize on the colon-separated form

Read-only commands handy for verification

# Inspect the CA chain
vault read pki_int/ca/pem

# Details for a specific certificate serial (REST example)
curl -s https://vault.example.com/v1/pki_int/cert/15:3a:9f:... | jq .

# Verify URL configuration
vault read pki_int/config/urls

Check Your Understanding

Frequently Asked Questions