Skip to content
Tutorials Center
My learning

Topics

Lesson 7 of 38 ยท Architecture and Setup

Certificates and Node Authentication

Learn how Puppet's built-in certificate authority authenticates nodes: CSR, signing with puppetserver ca, autosign policies, revoking and cleaning certificates.

Puppet agents and servers authenticate each other with TLS certificates. The Puppet Server runs its own certificate authority (CA). A new agent proves who it is by getting its certificate signed, and from then on every request is encrypted and authenticated. Knowing this flow solves most "my new agent will not connect" problems.

The signing flow

sequenceDiagram
    participant A as New agent
    participant CA as Puppet Server (CA)
    A->>A: Generate private key
    A->>CA: Submit certificate signing request (CSR)
    Note over CA: CSR waits as "pending"
    CA->>CA: Admin runs: puppetserver ca sign
    A->>CA: Next run: download signed certificate
    A->>CA: HTTPS with mutual TLS: request catalog

The agent's private key never leaves the agent; only the CSR travels.

  1. On first run the agent creates a key pair and a CSR for its certname (by default the machine's fully qualified domain name).
  2. It sends the CSR to the CA and waits.
  3. An administrator (or an automatic policy) signs the CSR.
  4. On the next run the agent fetches its signed certificate and is trusted.

All files are under /etc/puppetlabs/puppet/ssl on each machine (agent side) and /etc/puppetlabs/puppetserver/ca on the server (CA side).

Working with the CA: puppetserver ca

Since Puppet 6 the CA is managed with the puppetserver ca command, run on the server as root:

Terminal
sudo /opt/puppetlabs/bin/puppetserver ca list
sudo /opt/puppetlabs/bin/puppetserver ca sign --certname web1.example.test
sudo /opt/puppetlabs/bin/puppetserver ca list --all

list shows pending requests; list --all also shows signed and revoked certificates. Before signing, check the request is yours. Anyone who can reach port 8140 can submit a CSR with any name, and signing grants that machine a catalog, which may contain secrets. For a certname you do not recognise, run puppetserver ca list and compare fingerprints with the agent's (puppet ssl show_certificate, or the CSR fingerprint printed in the agent's output) before you sign.

Rebuilding a node

If you rebuild web1 and it requests a certificate again, the CA refuses: a certificate for that name already exists. Remove the old one first:

Terminal
sudo /opt/puppetlabs/bin/puppetserver ca clean --certname web1.example.test

clean revokes and deletes the old certificate so the new CSR can be signed. To only revoke without deleting, use revoke. Revoked certificates are written to the CA's CRL (certificate revocation list), which servers check.

On the rebuilt agent, if it still holds an old key, delete its SSL directory (/etc/puppetlabs/puppet/ssl) so it generates a fresh one.

Autosigning

Signing hundreds of VMs by hand is not practical, so the CA supports autosign. Options, from safest to least safe:

Method How Risk
Manual Admin runs ca sign Safe, slow
Policy executable A script that approves or rejects a CSR, set with autosign = /path/script Safe if the script checks a secret
Challenge password Put a pre-shared secret in the CSR (custom_attributes / challengePassword) Reasonable for cloud builds
Name pattern file (autosign.conf) Lines such as *.internal.example.test Anyone able to pick a matching name gets signed
autosign = true Sign everything Never use outside a throw-away lab

A policy executable receives the certname as an argument and the CSR on standard input; exit code 0 means sign, anything else means refuse. The stand-in below models that decision.

Python Stand-in: an autosign policy

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.

In real Puppet the shared secret would travel in the agent's csr_attributes.yaml and the policy script would read the CSR from standard input.

What a certificate contains

A certificate binds a certname to a public key and is signed by the CA. The certname is also the node's identity everywhere else in Puppet: in site.pp node blocks, in Hiera hierarchies (trusted.certname) and in reports. The special trusted facts ($trusted['certname'], and extensions from the CSR) come from the signed certificate, so a node cannot lie about them. By contrast, ordinary facts are reported by the agent and can be forged by a compromised node. Use $trusted data for security decisions.

Python Stand-in: trusted versus reported facts

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.

Certificate expiry and the CA

Agent certificates are valid for years by default, and the CA certificate for 15 years. Back up the CA directory: losing it means every agent must be re-enrolled. Treat the CA private key like any other critical secret, and plan the CA's renewal before it expires. When the server's hostname changes, add a DNS alternative name (dns_alt_names) before its certificate is created, because it cannot be added afterwards without regenerating.

Troubleshooting

  • "Certificate request ... has not been signed": list and sign the request.
  • "The certificate for this host is already on the CA" (after rebuild): puppetserver ca clean, remove the agent's ssl directory, retry.
  • "certificate verify failed" with date errors: fix clocks.
  • "Server hostname does not match": the name the agent uses is not in the server certificate's names.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Which command signs a pending certificate request?

    puppetserver ca sign run on the server signs a CSR.
  2. 2. A rebuilt node is refused because a certificate for its name exists. What do you do?

    Clean the old certificate so a new request can be signed.
  3. 3. Which autosign method is described as safe only in a throw-away lab?

    autosign = true signs every request from anyone who can reach the server.
  4. 4. Why use $trusted data for security decisions?

    Regular facts are self-reported; trusted facts come from the CA-signed certificate.

Summary

  • Each node has a TLS certificate signed by the server's CA; the agent submits a CSR on first run.
  • Manage requests with puppetserver ca list, sign, clean, revoke.
  • Prefer a policy executable or challenge password over blanket autosigning.
  • $trusted facts come from the certificate and can be trusted; ordinary facts cannot.
  • Back up the CA directory.

Next: The Agent Run Lifecycle