Before Puppet agent nodes can retrieve their configuration catalogs, they require a signed certificate from the local Puppet certificate authority (CA). When using Puppet’s built-in CA instead of an external CA, agents submit a certificate signing request (CSR) to the CA to retrieve a signed certificate after it's available.
By default, these CSRs must be manually signed by an admin user, using
ca command or the Node requests page in the Puppet Enterprise
Alternatively, to speed up the process of bringing new agent nodes into the deployment, you can configure the CA to automatically sign certain CSRs.
By default, the
autosign setting in the
[server] section of the CA’s
puppet.conf file is set
$confdir/autosign.conf. The basic autosigning functionality is enabled upon
Depending on your installation method, there might not be an allowlist at that location after the Puppet Server is running:
Open source Puppet:
autosign.confdoesn’t exist by default.
Monolithic Puppet Enterprise (PE) installations: All required services run on one server, and
autosign.confexists on the primary server, but by default it's empty because the primary server doesn’t need to add other servers to an allowlist.
Split PE installations: Services like PuppetDB can run on different servers, the
autosign.confexists on the CA server and contains an allowlist of other required hosts.
autosign.conf file is empty or doesn’t exist, the allowlist is
effectively empty. The CA Puppet primary server doesn’t autosign
any certificates until the the autosign setting’s path is configured, or until
autosign.conf file is a non-executable allowlist file. This file must
contain correctly formatted content or a custom policy executable that the Puppet user has permission to run.
To explicitly disable autosigning, set
autosign = false in
[server] section of the CA Puppet
puppet.conf. This disables CA autosigning even if the
autosign.conf file or a
custom policy executable exists.
For more information about the
autosign setting in
puppet.conf, see the configuration reference.
Naïve autosigning causes the CA to autosign all CSRs.
To enable naïve autosigning, set
autosign = true in the
[server] section of the CA Puppet primary server’s
Basic autosigning (
In basic autosigning, the CA uses a config file containing an allowlist of certificate names and domain name globs. When a CSR arrives, the requested certificate name is checked against the allowlist file. If the name is present, or covered by one of the domain name globs, the certificate is autosigned. If not, it's left for a manual review.
Enabling basic autosigning
autosign.conf allowlist file’s location
and contents are described in its documentation.
Puppet looks for
autosign.conf at the path configured in the
[autosign setting] within the
[server] section of
puppet.conf. The default path is
$confdir/autosign.conf, and the default
confdir path depends on your operating system. For more
information, see the confdir documentation.
autosign.conf file pointed to by
autosign setting is a file that
the Puppet user can execute, Puppet instead attempts to run it as a custom policy
executable, even if it contains a valid
autosign.conffile exists by default. In Puppet Enterprise, the file exists by default but might be empty. In both cases, the basic autosigning feature is technically enabled by default but doesn’t autosign any certificates because the allowlist is effectively empty.
The CA Puppet primary
server therefore doesn’t autosign any certificates until the
autosign.conf file contains a properly
formatted allowlist or is a custom policy executable that the Puppet user has permission to run, or until
autosign setting is pointed at
an allowlist file with properly formatted content or a custom policy
executable that the Puppet user has
permission to run.
Security implications of basic autosigning
Basic autosigning is insecure because any host can provide any certname when requesting a certificate. Use it only when you fully trust any computer capable of connecting to the Puppet primary server.
With basic autosigning enabled, an attacker who guesses an unused certname allowed
autosign.conf can obtain a signed
agent certificate from the Puppet primary server. The
attacker could then obtain a configuration catalog, which can contain sensitive
information depending on your deployment’s Puppet
code and node classification.
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
<policy executable file> in the
[server] section of the CA Puppet
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
0 (approved) or non-zero (rejected)
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
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.
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
|Stdout and stderr||