Puppet Server has a puppetserver ca
command that performs certificate authority (CA) tasks like signing and revoking certificates. Most of its actions are performed by making HTTP requests to Puppet Server’s CA API, specifically the certificate_status
endpoint. You must have Puppet Server running in order to sign or revoke certs.
CA subcommands
The following actions are available as subcommands for the puppetserver ca
command:
clean
: Revoke certificates and remove related files from the CA.generate
: Create a certificate signed by the CA.import
: Import the CA’s key, certificates, and certificate revocation lists (CRLs).list
: List all certificate requests.revoke
: Revoke a certificate.setup
: Generate a root and intermediate signing CA for Puppet Server.sign
: Sign a certificate.
puppetserver ca <action> [options]
--certname
flag. For example: puppetserver ca sign --certname cert.example.com
The target is a comma separated list of names that act on multiple certificates at one time. You can supply a custom configuration file with the --config
option. Some actions have additional options. Run puppetserver ca help
for details./opt/puppetlabs/puppet/bin/gem install -i /opt/puppetlabs/puppet/lib/ruby/vendor_gems puppetserver-ca
API authentication
For security, access to the certificate_status
API endpoint that is issued to sign and revoke certificates is tightly restricted. In Puppet 6, the master’s certificate is generated with a special extension which is whitelisted in the auth.conf
entries for the certificate_status
and certificate_statuses
endpoint. This extension is reserved, and Puppet Server refuses to sign other CSRs requesting it, even with allow-authorization-extensions
set to true
. If you need a certificate with this extension, you can generate it offline by stopping Puppet Server and running puppetserver ca generate --ca-client --certname
<name>
. API authentication is required for regenerating the master cert. For details on cert regeneration, see Regenerating certificates in a Puppet deployment.
Upgrading
The Puppet CA commands are available in Puppet 5, but to use them, you must update Puppet Server’s auth.conf
to include a rule allowing the master’s certname to access the certificate_status
and certificate_statuses
endpoints. If you’re upgrading from Puppet 5 to Puppet 6 and you are not regenerating your CA, you must whitelist the master’s certname. See Puppet Server configuration files: auth.conf for details on how to use auth.conf
.
certificate_status
endpoint:{
match-request: {
path: "/puppet-ca/v1/certificate_status"
type: path
method: [get, put, delete]
}
allow: master.example.com
sort-order: 500
name: "puppetlabs cert status"
},
Signing certificates with subject alternative names or auth extensions
With the removal of puppet cert sign
, Puppet Server’s CA API can sign certificates with subject alternative names (SANs) or auth extensions, which was previously disallowed. This option is disabled by default for security reasons, but you can turn it on by setting allow-subject-alt-names
or allow-authorization-extensions
to true
in the certificate-authority
section of Puppet Server’s config (usually located in ca.conf
). After these have been configured, you can use puppetserver ca sign --certname <name>
to sign certificates with these additions.