Setting Up Certificate Provisioning¶
This guide covers the configuration steps required before requesting certificates, and walks through each request pathway in detail. For background on how provisioning works, see Certificate Provisioning — Introduction.
Prerequisites¶
Register Domains¶
The platform requires that every domain name in the Common Name (CN) and Subject Alternative Names (SANs) of a certificate request matches a domain that is both registered and enabled in your account. Non-domain names (hostnames, IP addresses, URIs, emails, MAC addresses, phone numbers) are not matched against domains; see Non-Domain Names.
- Navigate to Admin → Domains.
- Add each domain your certificates will cover. Registering an apex domain (for example,
example.com) covers the domain and all its subdomains. - Ensure the domain is set to active (enabled). Disabled domains are not accepted in certificate requests.
If no active domain exists, the Continue button on the Request New Certificate page is disabled until at least one domain is active. Certificate requests for unregistered or disabled domains are rejected.
Validate Public Domains¶
A public domain (one not marked as private, internal only, when it was added) must prove that you control it in DNS before it can be used with a publicly trusted certificate authority. Until it is validated, requests that name it are rejected for ACME, Let's Encrypt, DigiCert and GlobalSign certificate authorities. Zaita Local PKI and Microsoft ADCS certificate authorities are private, so they do not require validation. Private domains never need it.
- Open the domain under Admin → Domains. The Domain Validation card shows the status (Validated or Not Validated) and the record to create.
- Create the TXT record with your DNS provider:
| Field | Value |
|---|---|
| Type | TXT |
| Hostname | _zaita-domain-verification.<domain> |
| Value | zaita-domain-verification=<token shown on the page> |
- Select Validate Now. The platform looks up the record in the background and marks the domain Validated when the value matches exactly.
DNS changes can take a few minutes to propagate. If validation fails, wait and select Validate Now again. Every check is recorded in the audit log (domain.validate_success or domain.validate_failed).
Regenerate Token issues a new token and clears the domain's Validated status, so a token that may have leaked stops counting as proof. Update the TXT record and validate again afterwards.
Note: Validation applies to every domain that is not private, including domains registered before this feature was introduced. Those domains start out as Not Validated.
Configure a Certificate Provider¶
Zaita Local PKI Certificate Authorities¶
To issue from your own PKI you need a root certificate, at least one active intermediate certificate under it, and a Zaita Local PKI certificate authority bound to that root:
- Create the root and intermediate under Local PKI. See Setting Up Your PKI.
- Navigate to Integrations → Certificate Authorities, select Add, choose Zaita Local PKI, and select the root.
A Local PKI certificate authority only signs with intermediates issued by its root that are enabled, in active status and within their validity period. The first Local PKI certificate authority you add becomes the tenant default.
External Certificate Authorities (DigiCert, GlobalSign, ACME)¶
External CA integrations are managed under Integrations → Certificate Authorities (or via the Service API at /api/v1/service/certificate-providers). Each provider must be set to active before it can be selected in a certificate request.
On an integration's page, Test Connection checks the saved configuration (not unsaved edits) against the CA, and the result pops up as a notification in the browser. The result is also recorded in the audit log as ca_integration.test_connection.success or ca_integration.test_connection.failed.
| Provider type | Required configuration |
|---|---|
digicert |
api_key, organization_id |
globalsign |
api_key, api_secret, mtls_cert, mtls_key, region, account_id |
acme |
directory_url, account_email (optionally eab_kid and eab_hmac_key for ACME EAB) |
Note:
typeis immutable after a provider is created. To change the type, delete the provider and create a new one.
Sensitive fields (API keys, secrets, mTLS private keys, HMAC keys) are accepted on create and update but are masked to null in all read responses to prevent credential leakage.
Microsoft ADCS¶
A Microsoft ADCS (Kerberos) integration issues certificates from an on-premises Active Directory Certificate Services CA. A Bridge in your network handles the requests by enrolling through the CA's Certificate Enrollment Web Service (CES) with Kerberos. The same integration is used for ADCS certificate discovery.
- Navigate to Integrations → Certificate Authorities and select Add.
- Choose Microsoft ADCS (Kerberos) and enter a name.
- Choose Simple (the default) or Advanced mode for the configuration.
Simple mode asks only for:
| Field | Example |
|---|---|
| Associated Bridge | bridge-dc1 |
| CA Hostname | ca01.corp.local |
CA Common Name (as shown by certutil -CA) |
corp-CA01 |
| Service Account UPN | [email protected] |
| Service Account Password | — |
On save, the platform derives the remaining required settings:
| Setting | Derived from | Example |
|---|---|---|
| Kerberos Realm | The domain part of the UPN, uppercased (or the CA hostname without its first label, if the UPN has no @) |
CORP.LOCAL |
| KDC / Domain Controller Address | The realm, lowercased, so DNS picks a domain controller | corp.local |
| CES Enrollment URL | https://<CA Hostname>/<CA Common Name>_CES_Kerberos/service.svc/CES |
https://ca01.corp.local/corp-CA01_CES_Kerberos/service.svc/CES |
Optional settings are left at their defaults in Simple mode. If a realm cannot be derived, the save fails with an error on Service Account UPN. Switch to Advanced in that case.
Advanced mode shows every field. Use it when your CES endpoint is not at the default path, you want a specific domain controller, or you need the optional settings:
| Field | Description |
|---|---|
| Allowed Templates | Comma-separated template names that can be requested. Leave empty to allow all templates. |
| LDAP Discovery Address | Host for LDAPS (port 636) certificate discovery. Defaults to the KDC address. |
| Skip ADCS TLS Verification | Turns off certificate validation for all of the Bridge's connections to ADCS: CES enrollment, LDAPS discovery against the domain controller, and WinRM over HTTPS to the CA. Traffic stays encrypted. Enable it only when the CA or domain controller presents a certificate the Bridge cannot validate, as is common in lab environments. Where possible, set LDAP Discovery Address to the domain controller's hostname instead. |
| WinRM Username / WinRM Password | Optional. When set, discovery also enumerates the CA database over WinRM, which finds certificates not published to Active Directory. Leave empty for LDAP-only discovery. The password defaults to the service account password. |
| WinRM Port | 5986 (HTTPS) is recommended. 5985 (plain HTTP) only works when the CA allows unencrypted WinRM (AllowUnencrypted=true). |
Switching from Simple to Advanced fills in the derived values so you can review and adjust them. Values typed in Advanced mode are discarded if you switch back to Simple before saving. The mode toggle only appears when adding an integration. The integration's page always shows every field.
To check the configuration, select Test via Bridge on the integration's page. The Bridge probes the CA's CES endpoint over HTTPS, and the result pops up as a browser notification when the Bridge reports back.
Requesting a Certificate — Automated Pathway¶
The automated pathway generates the key pair on your behalf and submits it to the chosen certificate authority.
- Navigate to CLM → Certificates.
- Select Request New Certificate.
- Select Automated and continue.
Step 0 — Authority & Names¶
Certificate Provider
Select the certificate authority first. The tenant's default Local PKI certificate authority is preselected.
| Selection | Additional fields |
|---|---|
| Zaita Local PKI certificate authority | Select a Signing Certificate. Only active intermediates under that certificate authority's root are listed; if there is only one, it is selected for you. |
| External CA (DigiCert, GlobalSign) | Select a Certificate Product from the dropdown (populated from the CA's API). |
| Microsoft ADCS | Select a certificate template. |
| ACME / Let's Encrypt | No product selection is needed. |
Names
| Field | Description |
|---|---|
| Common Name | The primary name for the certificate (for example, app.example.com, web01 or spiffe://zaita.local/ns/prod/sa/api). Optional when at least one SAN is entered. |
| Subject Alternative Names | Additional names to include. Domain names must match a registered domain. |
Either a Common Name or at least one SAN is required. When set, the CN is automatically included as a SAN in the generated certificate for X.509 compatibility. With a blank CN, the certificate subject has no CN.
Domain names must belong to a registered domain you are permitted to use. Non-domain names require Allow non-domain certificate issuance on your account, and a certificate authority that can issue them (Local PKI or ADCS). See Non-Domain Names.
The platform evaluates applicable policies at this step, including policies scoped to the selected certificate authority. If a hard-fail policy violation is found, you cannot advance until the names or certificate authority are adjusted or the policy violation is resolved.
Step 1 — Subject Information¶
| Field | Description |
|---|---|
| Organisation (O) | Legal name of the issuing organisation (optional). |
| Organisational Unit (OU) | Department or team (optional). |
| Country (C) | Two-letter ISO 3166-1 country code (optional). |
| State (ST) | State or province (optional). |
| Locality (L) | City or locality (optional). |
Fields enforced by policy are displayed as read-only. Policy enforcement runs again when you advance from this step.
Step 2 — Cryptographic Options¶
Cryptographic settings
| Field | Options | Default |
|---|---|---|
| Algorithm | rsa-2048, rsa-3072, rsa-4096, ec-256, ec-384, ec-521 |
rsa-2048 |
| Digest | sha256, sha384, sha512 |
sha256 |
| Validity (days) | 1–3650 | 365 |
| Key Usage | Digital Signature, Non-Repudiation, Key Encipherment, Data Encipherment, Key Agreement | Digital Signature + Key Encipherment |
| Extended Key Usage | serverAuth, clientAuth, codeSigning, emailProtection, timeStamping | serverAuth |
Algorithm and digest fields may be locked by policy.
Step 3 — Review and Submit¶
Review the full request summary before submitting. The summary shows the selected provider, signing certificate or product, all subject fields, and cryptographic options.
Select Submit to dispatch the request. You are redirected to the Order status page for this request, where you can monitor progress in real time. Once complete, the certificate appears in CLM → Certificates with source: managed, and the order page provides a direct link to view or download it.
Requesting a Certificate — CSR Upload Pathway¶
The CSR upload pathway signs a certificate using a CSR you generate externally. This is used when you generate the key pair outside the platform — for example, on an HSM.
Note: CSR upload only supports Local PKI certificate authorities.
- Navigate to CLM → Certificates.
- Select Request New Certificate.
- Select CSR Upload and continue.
Step 0 — Upload CSR¶
Paste your CSR in PEM format (beginning with -----BEGIN CERTIFICATE REQUEST-----) into the text area and select Parse.
The platform parses the CSR and extracts: - Common Name and Subject Alternative Names - Organisation, OU, Country, State, Locality - Key algorithm and size
Domain validation and policy evaluation run immediately on parse. If the CN or SANs do not match registered domains, the CSR is rejected. If a hard-fail policy violation is found, the CSR is accepted for viewing but you cannot advance.
Step 1 — Review and Configure¶
Verify the extracted subject information. Select:
| Field | Description |
|---|---|
| Certificate Authority | The Local PKI certificate authority to issue through. The tenant default is preselected. |
| Signing Certificate | An active intermediate certificate under that certificate authority's root. |
| Validity (days) | The validity period for the issued certificate (1–3650 days, default 90). |
| Digest | The digest algorithm for signing (sha256, sha384, sha512). |
Digest and validity may be locked or capped by policy.
Policy enforcement on CSR uploads differs from the automated pathway: since the CSR cannot be modified,
enforce_valuesrules that require subject field values the CSR does not have will generate a policy violation rather than auto-populating the field.
Step 2 — Submit¶
Review the CSR details and configuration, then submit. Processing follows the same asynchronous path as automated requests. You are redirected to the Order status page after submission.
Monitoring Certificate Orders¶
After submitting a certificate request, you are redirected to the Order page for that request. The page updates automatically every few seconds and shows the current status.
| Status | Description |
|---|---|
pending |
Request submitted, waiting to be picked up |
processing |
Certificate generation is actively in progress |
complete |
Certificate issued successfully; a link to view or download it is shown |
failed |
Generation failed; the error message and details are displayed on the page |
To view all past and in-progress orders, navigate to CLM → Certificates → Orders. You can filter by status or order type, and search by common name. Completed orders link directly to the issued certificate.
Processing time varies by provider. Local PKI requests typically complete in seconds. External CA requests (DigiCert, GlobalSign, ACME) depend on the CA's API response time and any validation steps required.
Next Steps¶
- Managing Provisioned Certificates — view, download, and revoke issued certificates.
- Best Practices for Certificate Provisioning — domain hygiene, provider selection, and policy configuration.