Puppet Autosign

Tooling to make puppet autosigning easy, secure, and extensible

View the Project on GitHub danieldreier/autosign

Still in development

This tool is under active development. I do not recommend production use until this notice is removed.

Puppet Autosign Tool

This gem makes it easier to use Puppet's policy-based autosigning for client certificates.

Getting Started

To use autosign for basic JWT token-based certificate autosigning, you will need to:

  1. Install and configure the gem on your Puppet CA (probably your master)
  2. Configure your puppet master to point the autosign setting in the [master] section of your puppet.conf to the autosign-validator executable.
  3. Create a /var/autosign folder, ensuring that the user puppet runs as (typically puppet or pe-puppet has write access to it.
  4. Run autosign config setup to generate a default configuration file in /etc/autosign.conf. A random password is generated and added by default.

These commands will probably look something like the following, but note that these were written in a hurry without much testing.

gem install autosign
autosign config setup
mkdir /var/autosign
chown puppet /var/autosign
puppet config set --section master autosign /usr/local/bin/autosign-validator

Next, generate your first token. Generating a token looks something like the following

$ autosign generate foo.example.com
Autosign token for: foo.example.com
Valid until: 2015-07-12 22:30:23 -0700



Puppet requires that agent SSL certificates be signed by the master's certificate authority. This can be performed manually using the puppet cert sign command on the master or using the Puppet Enterprise web console, automatically in an insecure way using naive autosigning, or automatically and (potentially) more securely using policy-based autosigning.

Policy-based autosigning calls an external executable and passes it the certificate signing request to STDIN and the agent's certificate name as the sole parameter. No default policy autosign executable is provided, so people write their own. Many are available publicly:

Each of these are written as one-off scripts, solving a specific need.

Many existing autosign scripts are based on validating one or more static strings (e.g. passwords, API keys, etc). If an attacker can obtain that string, they can issue valid requests to the Puppet Master, potentially allowing them to impersonate secure infrastructure and escalate privileges. People frequently forget to delete the csr_attributes.yaml after generating a CSR, and as with any plain-text password the tendency is for the keys to be widely distributed.

This tool can generate time limited, one-time tokens that are only valid for a specific host, so that obtaining the token after provisioning is not useful to an attacker.


This gem provides functionality in three areas. A JWT-based token system for securely issuing autosign tokens, a pluggable architecture for creating new autosign validation tools, and a CLI for managing autosign tokens.

Planned Functionality

This gem intends to (but does not yet) provide:

Security Model for JWT Tokens

The goal of the JWT tokens is to place time, reusability, and commonName constraints on tokens. There are several expected use models:

Per-host tokens for automated provisioning

During automated provisioning, a new token can be generated for each provisioned host. They will only be usable once, and will expire after a time period (2 hours by default).

Time-limited delegation of signing ability

You can generate a wildcard token that is only valid for hours or days, then share it with another person who needs to provision systems. Use of the token will be logged, so if you generate individual tokens for different users it's possible to audit who authorized which certificates to be signed. After the time period expires, they will no longer be able to authorize more hosts, but the previously-authorized hosts continue to work.

Authors and Contributors

@danieldreier is the primary author and maintainer of this gem. I would greatly appreciate additional contributions.

Support or Contact

Having trouble with Pages? Check out our documentation or contact support and we’ll help you sort it out.