Document pp_cli_auth: how the CA CLI is authorized, and fix stale CA endpoint statements

[miharp]

Summary

A recent Slack thread had two maintainers unsure why puppetserver ca list works on a fresh primary without any auth.conf changes. The answer is that puppetserver ca setup (and ca import) stamp the primary's own certificate with the pp_cli_auth extension, and the shipped auth.conf grants that extension access to every CA admin endpoint. None of this is in the docs, and a few related pages carry stale statements from before that mechanism existed.

Source of truth:

• openvoxserver-ca gem, lib/puppetserver/ca/local_certificate_authority.rb: CLI_AUTH_EXT_OID = "1.3.6.1.4.1.34380.1.3.39"; add_authorized_extensions adds it unconditionally when signing the server cert, and create_server_cert is called from both action/setup.rb and action/import.rb. puppetserver ca generate --ca-client goes through the same signing path for other hosts.
• openvox-server ezbake/config/conf.d/auth.conf: pp_cli_auth: "true" is the allow condition for certificate_status, certificate_statuses, certificate_revocation_list (PUT), clean, sign, sign/all, and since OpenVox 9 the file_bucket_file GET.
• openvox lib/puppet/ssl/oids.rb registers pp_cli_auth alongside pp_owner and pp_auth_auto_renew.

Gaps

1. Registered OIDs table is missing three OIDs

docs/_openvox_8x/_registered_oids.md and docs/_openvox_9x/_registered_oids.md (included by ssl_attributes_extensions.markdown and config_file_csr_attributes.markdown) list the ppRegCertExt range only up to pp_hostname and the ppAuthCertExt range only as pp_authorization and pp_auth_role. The OpenVox source also registers:

Numeric ID	Short name	Descriptive name
1.3.6.1.4.1.34380.1.1.26	pp_owner	Puppet Node Owner
1.3.6.1.4.1.34380.1.3.2	pp_auth_auto_renew	Auto-Renew Certificate Attribute
1.3.6.1.4.1.34380.1.3.39	pp_cli_auth	Puppetserver CA CLI Authorization

Someone who sees 1.3.6.1.4.1.34380.1.3.39 in openssl x509 -text output today cannot look it up in our docs.

2. Certificate status endpoint page says the endpoint is disabled by default

docs/_openvox-server_8x/ca-api/v1/http_certificate_status.md and the 9.x copy say under "Supported HTTP Methods":

This endpoint is disabled in the default configuration.

That predates the pp_cli_auth rules. In the shipped auth.conf the endpoint is enabled for any client certificate carrying pp_cli_auth: "true", which the primary's own cert does. The page should say that instead and point at the auth.conf page.

3. Nothing explains how the CA CLI is authorized

docs/_openvox-server_8x/subcommands.markdown (and 9.x) describes the puppetserver ca subcommands but never says:

• that the primary's certificate is generated with pp_cli_auth by ca setup / ca import, which is why the CLI works out of the box, and why regenerating that cert by other means (for example a plain agent CSR signed by the CA) silently breaks the CLI;
• that puppetserver ca generate --certname <host> --ca-client is the supported way to give another host the same privilege, and that the resulting cert is a broad CA admin credential (list, sign, revoke, clean, CRL update, and filebucket read on 9.x) and should not be handed out casually;
• that --ca-client exists at all. grep -ri ca-client docs/ returns nothing.

A short "CA CLI authorization" section on the subcommands page would cover all three. The auth.conf page (config_file_auth.markdown) could also use the cert-status rule as its worked example of extensions matching, since that is the one every install ships.

4. Bulk sign page names the wrong config file

docs/_openvox-server_8x/ca-api/v1/http_certificate_sign.md (and 9.x) says twice that access "is controlled by OpenVox Server's ca.conf authorization configuration". The rules live in auth.conf; ca.conf only holds the deprecated certificate-status whitelist settings.

Proposed fix

One PR touching both the 8.x and 9.x copies of the pages above: extend the OIDs include, correct the status and sign pages, and add the CA CLI authorization section to the subcommands page with a cross-link from the auth.conf page.

Assisted by Claude.