autosign

Tooling to make puppet autosigning easy, secure, and extensible

Introduction

This tool provides a CLI for performing puppet policy-based autosigning using JWT tokens. Read more at https://danieldreier.github.io/autosign.

Quick Start: How to Generate Tokens

1. Install Gem on Puppet Master

gem install autosign

2. Generate default configuration

autosign config setup

3. Generate your first autosign token on the puppet master

autosign generate foo.example.com

The output will look something like

Autosign token for: foo.example.com, valid until: 2015-07-16 16:25:50 -0700
To use the token, put the following in ${puppet_confdir}/csr_attributes.yaml prior to running puppet agent for the first time:

custom_attributes:
  challengePassword: "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzUxMiJ9.eyJkYXRhIjoie1wiY2VydG5hbWVcIjpcImZvby5leGFtcGxlLmNvbVwiLFwicmVxdWVzdGVyXCI6XCJEYW5pZWxzLU1hY0Jvb2stUHJvLTIubG9jYWxcIixcInJldXNhYmxlXCI6ZmFsc2UsXCJ2YWxpZGZvclwiOjcyMDAsXCJ1dWlkXCI6XCJkM2YyNzI0OC1jZDFmLTRhZmItYjI0MC02ZjBjMDU4NWJiZDNcIn0iLCJleHAiOiIxNDM3MDg5MTUwIn0.lC-EzWaV2dL81aLL7P-9mGwNbiOQDJWcoYjuSHVOqmaLtc7Wis5OZvHFOLln2Fn9qv98oSTnZsIkjmFpbI5dvA"

The resulting output can be copied to /etc/puppet/csr_attributes.yaml on an agent machine prior to running puppet for the first time to add the token to the CSR as the challengePassword OID. (just copy-paste from one terminal to another to copy the text)

Quick Start: Puppet Master Configuration

Run through the previous quick start steps to get the gem installed, then configure puppet to use the autosign-validator executable as the policy autosign command:

1. Prerequisities

Note that these settings will be slightly different if you're running Puppet Enterprise, because you'll need to use the pe-puppet user instead of puppet.

mkdir /var/autosign
chown puppet:puppet /var/autosign
chmod 750 /var/autosign
touch /var/log/autosign.log
chown puppet:puppet /var/log/autosign.log

2. Configure master

puppet config set autosign $(which autosign-validator) --section master

Your master is now configured to autosign using the autosign gem.

3. Using Legacy Autosign Scripts

If you already had an autosign script you want to continue using, add a setting to your autosign.conf like:

multiplexer:
  external_policy_executable: "/path/to/autosign/executable"

The master will validate the certificate if either the token validator or the external validator succeeds.

If the autosign script was just validating simple strings, you can use the password_list validator instead. For example, to configure the master to sign any CSR that includes the challenge passwords of "hunter2" or "CPE1704TKS" you would add:

password_list:
  password: "hunter2"
  password: "CPE1704TKS"

Note that this is a relatively insecure way to do certificate autosigning. Using one-time tokens via the autosign generate command is more secure. This functionality is provided to grandfather in existing use cases to ease the transition.

Validation order

By default the validation runs the following validators in order:

1. jwt_token
2. password_list
3. multiplexer

The first validator to succeed wins and short circuits the validaiton process.

You can completely customize the list and how they are ordered via the configuration file. Or even remove some entirely.

---
general:
  loglevel: debug
  logfile: "/var/log/autosign.log"
  validation_order: 
    - jwt_token
    - multiplexer
    - password_list
jwt_token:
  secret: J7/WjmkC/CJp2K0/8+sktzSgCqQ=
  validity: '7200'
  journalfile: "/root/var/autosign/autosign.journal"

The validation_order config is an ordered array and since the validators will only match the first validation to succeed the validation script should occur as fast as you want.

Additionally, if you omit any validator that validator will not be used during the validation process. This might be important if you wanted to only use special validators or remove unwanted validator execution.

Please note, the name of the validator which is speficed by the NAME constant in the validator code must match the list you specify otherwise it will not be part of the validation process.

NOTE To use this feature you must have deep_merge 1.2.1+ installed which is now a requirement of this gem.

Troubleshooting

If you're having problems, try the following:

• Set loglevel: "debug" in /etc/autosign.conf
• Check the journalfile, in /var/autosign/autosign.journal by default, to see if the one-time token's UUID has already been recorded. It's just YAML, so you can either delete it or remove the offending entry if you actually want to re-use a token.
• you can manually trigger the autosigning script with something like cat the_csr.csr | autosign-validator certname.example.com
• If you run the puppet master foregrounded, you'll see quite a bit of autosign script output if autosign loglevel is set to debug.

Starting with the 1.0.0 release the autosign gem requires ruby 2.4. If you can't upgrade just yet you can continue to use the older 0.1.4 release.

Further Reading

• https://danieldreier.github.io/autosign has background on why this exists.
• Automatically generated code documentation in YARDOC format is available on rubydoc.info.
• Look at the puppet-autosign puppet module to automate setup of this tool, and for a puppet function to generate tokens inside of Puppet, for example when provisioning systems in AWS.