Puppet Server CA commands

CA subcommands

If you have yet to review the actions for the puppetserver ca command, visit Subcommands. Some actions have additional options. Run puppetserver ca help for details.

The puppetserver-ca CLI tool is shipped as a gem alongside Puppet Server. You can update the gem between releases for bug fixes and improvements. To update the gem, run:

/opt/puppetlabs/puppet/bin/gem install -i /opt/puppetlabs/puppet/lib/ruby/vendor_gems puppetserver-ca

API authentication

Access to the certificate_status API endpoint is tightly restricted for security purposes because the endpoint lets you sign or revoke certificates. To access the certificate_status and certificate_statuses endpoints, you must add a special extension to each endpoint's allowlist in the auth.conf entries. If other CSRs request this extension, Puppet Server refuses to sign them because the extension is reserved (even if allow-authorization-extensions is set to true).

If you need a certificate with this extension, you can generate it offline by doing the following:

1. Stop Puppet Server.
   Note:

   • Although this particular use of the generate command requires you to stop puppetserver service, all other uses of this command require the service to be running.
   • If the tool cannot determine the status of the server, but you know the server is offline, you can use the --force option to run the command without checking server status.
2. Run puppetserver ca generate --ca-client --certname <name>

API authentication is required for regenerating the primary server's certificate. For details on certificate regeneration, visit Regenerating certificates in a Puppet deployment.

Upgrading

To use the Puppet CA commands, you must update Puppet Server's auth.conf to include a rule that allows the primary server's certname to access the certificate_status and certicate_statuses endpoints.

The following example displays how to allow the CA commands to access the certificate_status endpoint:

{
  match-request: {
 path: "/puppet-ca/v1/certificate_status"  
     type: path        
     method: [get, put, delete]    
   }    
   allow: primaryserver.example.com  
   sort-order: 500    
   name: "puppetlabs cert status"
},

For more information about upgrading your auth.conf file, visit auth.conf.

Signing certificates with subject alternative names or auth extensions

Puppet Server's CA API can sign certificates with subject alternative names (SANs) or auth extensions. These options are disabled by default for security purposes. To enable these options, in the certificate-authority section of Puppet Server's configuration (usually located in ca.conf), set allow-subject-alt-names or allow-authorization-extensions to true. After configuration, you can use puppetserver ca sign --certname <name> to sign certificates with these additions.