Policy-based autosigning

In policy-based autosigning, the CA runs an external policy executable every time it receives a CSR. This executable examines the CSR and tells the CA whether the certificate is approved for autosigning. If the executable approves, the certificate is autosigned; if not, it's left for manual review.

Enabling policy-based autosigning

To enable policy-based autosigning, set autosign = <policy executable file> in the [server] section of the CA Puppet primary server’s puppet.conf.

The policy executable file must be executable by the same user as the Puppet primary server. If not, it is treated as a certname allowlist file.

Custom policy executables

A custom policy executable can be written in any programming language; it just has to be executable in a *nix-like environment. The Puppet primary server passes it the certname of the request (as a command line argument) and the PEM-encoded CSR (on stdin), and expects a 0 (approved) or non-zero (rejected) exit code.

After it has the CSR, a policy executable can extract information from it and decide whether to approve the certificate for autosigning. This is useful when you are provisioning your nodes and are embedding additional information in the CSR.

If you aren’t embedding additional data, the CSR contains only the node’s certname and public key. This can still provide more flexibility and security than autosign.conf, as the executable can do things like query your provisioning system, CMDB, or cloud provider to make sure a node with that name was recently added.

Security implications of policy-based autosigning

Depending on how you manage the information the policy executable is using, policy-based autosigning can be fast and extremely secure.

For example:

If you embed a unique pre-shared key on each node you provision, and provide your policy executable with a database of these keys, your autosigning security is as good as your handling of the keys. As long as it’s impractical for an attacker to acquire a PSK, it's impractical for them to acquire a signed certificate.
If nodes running on a cloud service embed their instance UUIDs in their CSRs, and your executable queries the cloud provider’s API to check that a node's UUID exists in your account, your autosigning security is as good as the security of the cloud provider’s API. If an attacker can impersonate a legit user to the API and get a list of node UUIDs, or if they can create a rogue node in your account, they can acquire a signed certificate.

When designing your CSR data and signing policy, you must think things through carefully. If you can arrange reasonable end-to-end security for secret data on your nodes, you can configure a secure autosigning system.

Policy executable API

The API for policy executables is as follows.

Run environment	The executable runs one time for each incoming CSR. It is executed by the Puppet primary server process and runs as the same user as the Puppet primary server. The Puppet primary server process is blocked until the executable finishes running. We expect policy executables to finish in a timely fashion; if they do not, it’s possible for them to tie up all available Puppet primary server threads and deny service to other agents. If an executable needs to perform network requests or other potentially expensive operations, the author is in charge of implementing any necessary timeouts, possibly bailing and exiting non-zero in the event of failure.
Arguments	The executable must allow a single command line argument. This argument is the Subject CN (certname) of the incoming CSR. No other command line arguments should be provided. The Puppet primary server should never fail to provide this argument.
Stdin	The executable receives the entirety of the incoming CSR on its stdin stream. The CSR is encoded in `pem` format. The stdin stream contains nothing but the complete CSR. The Puppet primary server should never fail to provide the CSR on stdin.
Exit status	The executable must exit with a status of `0` if the certificate should be autosigned; it must exit with a non-zero status if it should not be autosigned. The Puppet primary server treats all non-zero exit statuses as equivalent.
Stdout and stderr	Anything the executable emits on stdout or stderr is copied to the Puppet Server log output at the `debug` log level. Puppet otherwise ignores the executable’s output; only the exit code is considered significant.