README.md
# autosign
[](https://travis-ci.org/danieldreier/autosign) [](https://codeclimate.com/github/danieldreier/autosign) [](https://gemnasium.com/danieldreier/autosign) [](http://rubydoc.info/github/danieldreier/autosign) [](http://inch-ci.org/github/danieldreier/autosign) [](https://coveralls.io/github/danieldreier/autosign?branch=master) [](http://badge.fury.io/rb/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
```shell
gem install autosign
```
##### 2. Generate default configuration
```shell
autosign config setup
```
##### 3. Generate your first autosign token on the puppet master
```shell
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`.
```shell
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
```shell
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:
```yaml
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:
```ini
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](https://danieldreier.github.io/autosign) has background on why this exists.
- Automatically generated code documentation in YARDOC format is [available on rubydoc.info](http://rubydoc.info/github/danieldreier/autosign).
- Look at the [puppet-autosign](https://travis-ci.org/danieldreier/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.