Skip to content
Tutorials Center
My learning

Topics

Lesson 13 of 36 ยท Secrets Engines

The PKI Secrets Engine

Use Vault as an internal certificate authority: root and intermediate CAs, roles, issuing short-lived certificates, revocation and CRLs, with runnable policy checks.

Every TLS service needs a certificate, and manually issued year-long certificates are a famous source of outages. The PKI secrets engine turns Vault into a certificate authority (CA). Applications ask for a certificate and receive one signed on demand, often valid for hours or days, so renewal becomes routine and revocation rarely matters.

This lesson covers the PKI hierarchy, how to set up an intermediate CA, roles that restrict what can be issued, and the issue/revoke flow. The CLI parts are read-only; runnable models check role rules and certificate lifetimes.

Vault is not available here and cannot sign real certificates on this site. The Python examples model role validation and lifetime arithmetic; they do not produce certificates.

The hierarchy

Best practice is a root CA that is kept offline (or in a separate, locked-down Vault), which signs one or more intermediate CAs. The intermediate, hosted in Vault's PKI engine, issues the actual leaf certificates. If the intermediate is compromised you revoke it and issue a new one, without replacing trust in the root everywhere.

flowchart TB
    Root["Root CA<br/>offline, 10 years"] --> Int["Intermediate CA<br/>pki_int/, 1 year"]
    Int --> L1["web.example.internal<br/>24 hours"]
    Int --> L2["api.example.internal<br/>24 hours"]

Clients trust the root; Vault's intermediate signs short-lived leaf certificates.

Setting up (sketch)

Enable two mounts with different maximum lifetimes, generate the CA material, and sign the intermediate with the root:

Terminal
vault secrets enable -path=pki pki
vault secrets tune -max-lease-ttl=87600h pki
vault write -field=certificate pki/root/generate/internal \
    common_name="Example Root CA" ttl=87600h > root_ca.crt

vault secrets enable -path=pki_int pki
vault secrets tune -max-lease-ttl=8760h pki_int
vault write -format=json pki_int/intermediate/generate/internal \
    common_name="Example Intermediate CA" | jq -r '.data.csr' > int.csr
vault write -format=json pki/root/sign-intermediate [email protected] ttl=8760h \
    | jq -r '.data.certificate' > int.pem
vault write pki_int/intermediate/set-signed [email protected]

The exact endpoints and parameters evolve between versions (newer versions manage issuers explicitly under pki/issuers), so follow the tutorial for your version. Also set the URLs that will be embedded in certificates so clients can find the issuing CA and revocation list:

Terminal
vault write pki_int/config/urls \
    issuing_certificates="https://vault.example.internal:8200/v1/pki_int/ca" \
    crl_distribution_points="https://vault.example.internal:8200/v1/pki_int/crl"

Roles

A role limits what a requester may get: which domains, whether subdomains or wildcards are allowed, maximum TTL, key type and size, and usages.

Terminal
vault write pki_int/roles/internal-web \
    allowed_domains="example.internal" \
    allow_subdomains=true \
    max_ttl=72h

Then a client with permission on pki_int/issue/internal-web requests a certificate:

Terminal
vault write pki_int/issue/internal-web common_name="web.example.internal" ttl=24h

The response contains the certificate, the private key (shown once, Vault does not keep it for issue), the issuing CA and a serial number with a lease. To sign a CSR so the private key never leaves the client, use pki_int/sign/<role> instead.

A role validator you can run

This model applies the typical role checks to requested names and TTLs.

Python Validate a certificate request against a role

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Short lifetimes and renewal

With 24-hour certificates, clients must renew automatically (for example with Vault Agent templates, or cert-manager on Kubernetes). A common rule is to renew when two thirds of the lifetime has passed.

Python When to renew a short-lived certificate

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

The buffer decides how long an outage of Vault can last before certificates expire: with 24 hours and renewal at two thirds, you have eight hours.

Revocation

You can revoke a certificate by serial number:

Terminal
vault write pki_int/revoke serial_number="39:dd:2e:..."

Revoked serials appear on the Certificate Revocation List (CRL) at the configured URL, and newer versions also support OCSP. Many teams rely on very short lifetimes instead, since clients often ignore revocation lists anyway. Setting no_store=true on a role stops Vault from storing every issued certificate, which matters at high volume, at the cost of being unable to list or revoke by serial.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Why use an intermediate CA in Vault instead of the root directly?

    Keeping the root offline limits damage; clients keep trusting the root while you replace the intermediate.
  2. 2. What does a PKI role do?

    Roles constrain issuance: domains, subdomains, wildcards, TTLs and usages.
  3. 3. When using pki/issue, where is the private key?

    issue generates the key pair and returns the key once. Use sign with a CSR to keep keys on the client.
  4. 4. What is the main benefit of 24-hour certificates?

    The cost is automation, so renewal must be automatic.

Summary

  • The PKI engine makes Vault an internal CA: keep the root offline and issue from an intermediate.
  • Roles restrict domains, TTLs and key settings; clients request certificates at issue/<role> or sign/<role>.
  • Short lifetimes with automatic renewal replace painful revocation.
  • Configure issuing and CRL URLs; revoke by serial when you must.
  • Syntax varies by version, so follow the documentation for yours.

Next: The SSH Secrets Engine