Intermediate CA

Puppet Server supports both a simple CA architecture, with a self-signed root cert that is also used as the CA signing cert; and an intermediate CA architecture, with a self-signed root that issues an intermediate CA cert used for signing incoming certificate requests. The intermediate CA architecture is preferred, because it is more secure and makes regenerating certs easier. To generate a default intermediate CA for Puppet Server, run the puppetserver ca setup command before starting your server for the first time.

The following diagram shows the configuration of Puppet's basic certificate infrastructure.

A diagram showing Puppet's basic certificate infrastructure

If you have an external certificate authority, you can create a cert chain from it, and use the puppetserver ca import subcommand to install the chain on your server. Puppet agents starting with Puppet 6 handle an intermediate CA setup out of the box. No need to copy files around by hand or configure CRL checking. Like setup, import needs to be run before starting your server for the first time.

Note: The PE installer uses the puppetserver ca setup command to create a root cert and an intermediate signing cert for Puppet Server. This means that in PE, the default CA is always an intermediate CA as of PE 2019.0.

Note: If for some reason you cannot use an intermediate CA, in Puppet Server 6 starting the server will generate a non-intermediate CA the same as it always did before the introduction of these commands. However, we don't recommend this, as using an intermediate CA provides more security and easier paths for CA regeneration. It is also the default in PE, and some recommended workflows may rely on it.

Where to set CA configuration

All CA configuration takes place in Puppet’s config file. See the Puppet Configuration Reference for details.

Set up Puppet as an intermediate CA with an external root

Puppet Server needs to present the full certificate chain to clients so the client can authenticate the server. You construct the certificate chain by concatenating the CA certificates, starting with the new intermediate CA certificate and descending to the root CA certificate.

The following diagram shows the configuration of Puppet's certificate infrastructure with an external root.

A diagram showing Puppet's certificate infrastructure with an external root

To set up Puppet as an intermediate CA with an external root:

Collect the PEM-encoded certificates and CRLs for your organization's chain of trust, including the root certificate, any intermediate certificates, and the signing certificate. (The signing certificate might be the root or intermediate certificate.)
Create a private RSA key, with no passphrase, for the Puppet CA.
Create a PEM-encoded Puppet CA certificate.
1. Create a CSR for the Puppet CA.
2. Generate the Puppet CA certificate by signing the CSR using your external CA.
  
  Ensure the CA constraint is set to true and the keyIdentifier is composed of the 160-bit SHA-1 hash of the value of the bit string subjectPublicKeyfield. See RFC 5280 section 4.2.1.2 for details.

Concatenate all of the certificates into a PEM-encoded certificate bundle, starting with the Puppet CA cert and ending with your root certificate.

Concatenate all of the CRLs into a PEM-encoded CRL chain, starting with any optional intermediate CA CRLs and ending with your root certificate CRL.

Use the puppetserver ca import command to trigger the rest of the CA setup:

puppetserver ca import --cert-bundle ca-bundle.pem --crl-chain crls.pem --private-key puppet_ca_key.pem

optional. Validate that the CA is working by running puppet agent -t and verifying your intermediate CA with OpenSSL.

openssl x509 -in /etc/puppetlabs/puppet/ssl/ca/signed/<HOSTNAME>.crt 
-text -noout
Certificate:
   Data:
       Version: 3 (0x2)
       Serial Number: 1 (0x1)
   Signature Algorithm: sha256WithRSAEncryption
       Issuer: CN=intermediate-ca

Note: If your organization's CRLs require frequent updating, you can use the certificate_revocation_list endpoint to insert updated copies of your CRLs into the trust chain. The CA updates the matching CRLs saved on disk if the submitted ones have a higher CRL number than their counterparts. In addition, set Puppet’s crl_refresh_interval on all of your agents to ensure that they download the updated CRLs.