Public CAs and domain validation¶
PKIFactor orders publicly trusted certificates from DigiCert (CertCentral, and DigiCert ONE / Trust Lifecycle Manager), Sectigo, and any CA that offers ACME. A public CA issues only after domain control validation (DCV): proof that the requester controls each name in the certificate. PKIFactor can perform that proof itself through your DNS provider.
How servers, connectors and templates fit together is explained on Certificate authorities; this page covers what is specific to public CAs.
Before you start¶
Public CAs are included with every license, like every other feature. System > Settings > Features (Administration workspace) shows the state of each module; the Public CAs line counts the public CA connectors in use.
| Type | CA | Server authentication | Validation per order |
|---|---|---|---|
DIGICERT |
DigiCert CertCentral (API v2) | API_KEY |
Yes (DCV) |
DIGICERT_ONE |
DigiCert ONE / Trust Lifecycle Manager | DIGICERT_ONE_API (API key) or DIGICERT_ONE_MTLS (client certificate) |
No: domains are pre-validated in the business unit |
SECTIGO |
Sectigo, reseller API (secure.trust-provider.com) |
PUBLIC_CA_API |
Yes (DCV) |
SECTIGO_SCM |
Sectigo Certificate Manager, API v2 (OAuth2) | PUBLIC_CA_API |
Yes (DCV) |
PUBLIC_ACME |
Let's Encrypt, Google Trust Services, Sectigo ACME, ZeroSSL, or any ACME directory | None (the ACME account is created by PKIFactor) | Yes (DNS-01) |
How an order proceeds¶
For DigiCert CertCentral and Sectigo, a request creates an order at the CA. The certificate takes the status Pending DCV until the CA has validated the domains; a background collector then polls the CA (every 20 seconds to 5 minutes) and stores the certificate as soon as it is issued, without anyone having to come back. On the certificate page, Check & Collect forces a check. When DigiCert already holds a valid validation for the domains, it can issue at once.
The private key of a certificate generated by PKIFactor is kept encrypted while the order is pending.
DigiCert CertCentral¶
Tested
DV certificates with automatic per-order DCV over DNS (record placed and removed by PKIFactor through the DNS provider), from request to issued certificate. Not tested end to end: OV and EV, which are blocked by DigiCert's organization validation; the reuse of an existing domain validation (see Reusing a DigiCert validation).
Server: method API_KEY, with a CertCentral API key (sent as X-DC-DEVKEY).
Connector: type DIGICERT, Validation Type DV, OV or EV. OV and EV require the DigiCert Organization ID of an organization already validated by DigiCert; without it the connector refuses to start ("DigiCert OV mode requires digicert_org_id").
Profile: Product Type (the products of your CertCentral account, read from the API) and the DCV Method:
| DCV method | Record or action |
|---|---|
DNS CNAME (dns-cname-token) |
_dnsauth.<base domain> CNAME <token>.dcv.digicert.com |
DNS TXT (dns-txt-token) |
_dnsauth.<base domain> TXT <token> |
HTTP (http-token) |
A file to place on the web server |
Email (email) |
A message to the domain's administrative addresses |
The host is always _dnsauth.<base domain>: the token goes in the CNAME target or the TXT value, never in the host name.
Reusing a DigiCert validation¶
An option exists to skip the per-order record when DigiCert confirms that the domains already have a reusable validation (useful for OV and EV). It is dormant: off by default, enabled per profile only through the profile's provider_metadata (dcv_reuse_persistent), with no setting in the interface, and not validated against DigiCert. When enabled and DigiCert does not issue within the allowed delay, PKIFactor falls back to the normal per-order validation, so an order never stays stuck.
DigiCert ONE / Trust Lifecycle Manager¶
A different platform from CertCentral: certificates are issued according to a TLM profile (which holds validity, usages and allowed names) and a seat, with domains pre-validated in the business unit. There is no DCV per order. Issuance is usually immediate; when the platform answers with a request identifier, the collector picks the certificate up.
Server, two choices:
| Method | Address used | Credential |
|---|---|---|
DIGICERT_ONE_API |
https://one.digicert.com |
API key (x-api-key) |
DIGICERT_ONE_MTLS |
https://clientauth.one.digicert.com |
Client certificate as a PKCS#12 file encoded in base64, and its password if it has one |
(The credential field labels are in French in this version.)
Connector: type DIGICERT_ONE, Default TLM profile (used when the PKIFactor profile does not set one) and Default seat (optional). Without a seat, the certificate's common name is used.
Sectigo¶
Two connectors exist, for two generations of the Sectigo API.
Sectigo reseller API (SECTIGO)¶
The connector uses the oldest Sectigo API generation, the reseller trust provider interface, where domain validation relies on a hash of the CSR.
Server: method PUBLIC_CA_API, Login Name and Login Password of the API account.
Connector: type SECTIGO, Validation Type; OV and EV need a Prevalidation Order Number (an organization pre-validation done in the Sectigo portal).
Profile: Product ID (from your Sectigo contract; Sectigo offers no product list API, the form suggests known IDs and accepts any) and DCV Method: CNAME (CNAME_CSR_HASH), HTTP file (HTTP_CSR_HASH) or email (EMAIL).
This API generation cannot drive organization validation nor reuse a domain validation: that needs the SCM v2 API below.
Sectigo Certificate Manager v2 (SECTIGO_SCM)¶
A separate connector for the current SCM API (admin.<instance>.sectigo.com, OAuth2 client credentials), which adds organization validation for OV and EV and the v2 DCV with reusable validations.
Server: method PUBLIC_CA_API; put the OAuth2 client_id in Login Name and the client_secret in Login Password. Connector: SCM instance (enterprise, hard or eu), Organization ID, CA Backend ID (required for OV and EV), optionally Certificate profile (certType).
Not validated against Sectigo
This connector has been checked only against Sectigo's published API specification and automated tests with simulated answers. It has not been run against a real SCM account.
Public ACME CAs (PUBLIC_ACME)¶
PKIFactor can act as an ACME client of a public CA on behalf of its users: the user makes an ordinary request on a profile, PKIFactor holds the ACME account, proves domain control, collects and renews the certificate.
Connector: type PUBLIC_ACME. No server to choose (a placeholder server External ACME is attached automatically).
| Field | Value |
|---|---|
| Certificate authority (ACME) | Let's Encrypt staging (default) or production, Sectigo Public ACME (DV), Sectigo demo, Google Trust Services (DV), ZeroSSL (DV), or a custom directory URL (with Verify the CA's TLS, on by default) |
| Key ID (kid), HMAC key (base64url) | External account binding, required by Sectigo, Google and ZeroSSL (never by Let's Encrypt). Optional when creating the connector, required at the first issuance |
The ACME account key is generated automatically and stored encrypted. Validation uses DNS-01 only, so the profile must have a DNS provider: without one, issuance is refused ("PUBLIC_ACME requires a DNS provider on the template (dns-01)"). Each validated domain is recorded under Domain Validations with the expiry the CA returned; a later request for a domain still valid at the CA skips the challenge, and Refresh re-validates a domain without issuing. Renewal is automatic and follows the CA's renewal information (ARI) when the CA publishes it.
Qualify a profile on Let's Encrypt staging before production, because of production rate limits.
Automating DCV with a DNS provider¶
Declare the DNS provider¶
Administration workspace, Infrastructure > DNS Providers > Add DNS Provider, choose the Provider type, fill its fields and the Default TTL (seconds) (60 recommended). Secrets are stored encrypted. After saving, PKIFactor detects the zones the account manages.
| Provider type | Fields |
|---|---|
| OVH | OVH endpoint, Application key, Application secret, Consumer key |
| Azure DNS | Tenant ID, Client ID, Client secret, Subscription ID, Zone mode |
| Cloudflare | API Token |
| Google Cloud DNS | Service Account key (JSON), Project ID |
| Gandi | Personal Access Token (or a legacy API key) |
| Webhook (custom) | Webhook URL, HMAC shared secret, Verify TLS certificate: for any other DNS, through a small service of yours that applies the records |
The list shows each provider's Zones, Status and Last test. Test Connection (on the form) or Test (in the list) checks write access, not only the credentials: for each zone it creates, reads back and deletes a probe TXT record (_pkifactor-clm-verify), and shows which zones accept writes. Sync re-detects the zones. A provider can be global or limited to an organization. Grant the account write access to the zones used for DCV, and nothing else.
Configure the profile¶
In the profile of a public CA, Validation type DV offers an explicit choice under Domain validation:
- Automatic (DCV via DNS provider): PKIFactor places the record at order time, waits for it to be visible, lets the CA check it, then deletes it. The DNS provider is deduced from the domain (the provider whose zones cover the name, longest match); choosing one in DNS provider forces it. If no managed zone covers a domain, the order falls back to manual validation instead of failing.
- Manual: you perform the validation yourself (email, HTTP file, or a CNAME record placed by hand).
For OV and EV, the DCV method is chosen in the CA block of the profile, and automation applies when a DNS-based method is used.
Placement and verification are tracked as a DCV challenge (pending, record_placed, propagating, ca_validating, validated, cleanup_pending, then completed or failed). On a DNSSEC-signed zone, publication can be slow; if propagation exceeds the delay, the challenge fails and the record is cleaned up: submit the request again.
Domain Validations¶
Administration workspace, Operations > Domain Validations lists domain validations per public CA: domain, CA, method, status, expiry, auto-refresh. Add validation registers one: domain (example.com or *.example.com), public CA, Validation method (CNAME (recommended, 13 month validity), HTTP file or Email), DNS provider (optional), Auto-refresh before expiry. Refresh re-validates an entry; Delete removes it. The page needs at least one Sectigo or DigiCert connector ("No public CA configured. Add a Sectigo or DigiCert PKI first.").
What the registry does depends on the CA:
| CA | Effect |
|---|---|
| Public ACME | Filled automatically after each validation; a valid entry lets the next request skip the challenge |
| Sectigo | A refresh handler advances and renews the entry. PKIFactor still places the per-order record at each order, because Sectigo decides on its own whether to reuse a validation |
| DigiCert and others | Tracking only; the validation runs at each order |
Troubleshooting¶
| Symptom | Cause and fix |
|---|---|
| DigiCert: authentication error | Invalid or revoked API key |
| DigiCert: "DigiCert OV mode requires digicert_org_id" | Set the DigiCert Organization ID on the connector, or use DV |
| DigiCert: "CLM template has no DigiCert product type configured" | Choose a Product Type in the profile |
| Certificate stays Pending DCV with a DNS method | No managed zone covers the domain (check DNS Providers, Test Connection, Sync), or the DNS account cannot write in that zone |
| Certificate stays Pending DCV with email or HTTP | The validation e-mail was not approved, or the file is not reachable by the CA |
| OV or EV order never issues | The organization is not validated at the CA (DigiCert organization, Sectigo pre-validation) |
| ACME: first issuance fails at Sectigo, Google or ZeroSSL | External account binding missing: fill Key ID and HMAC key on the connector |
| ACME: "PUBLIC_ACME requires a DNS provider on the template (dns-01)" | Attach a DNS provider to the profile |
| DNS provider test red for a zone | The token lacks write rights on that zone (for OVH, POST, PUT and DELETE on the zone's records) |