Managing ACME Servers¶

This guide covers managing ACME server configurations after initial setup, including modifying settings, monitoring usage, and decommissioning servers.

Viewing ACME Servers¶

Navigate to Admin → ACME Servers to see all ACME server configurations for your tenant. The list displays:

Name — The server's display name
Status — Active or Inactive
Accounts — Number of registered accounts
Orders — Total orders processed
Certificates — Total certificates issued

Select a server to view details and modify settings.

Server Settings¶

General Settings¶

Setting	Description	Can Modify
Name	Display name	Yes
Description	Optional description	Yes
Status	Active or Inactive	Yes
UUID	Unique identifier (part of directory URL)	No

Certificate Settings¶

Setting	Description	Can Modify
Use Domain Default	When enabled, each certificate is signed by the requested domain's default certificate provider (Admin → Domains), falling back to the tenant's default Local PKI certificate authority if the domain has none. When disabled, the server uses the fixed Local PKI Certificate Authority (and optional Intermediate Certificate) or CA Integration below instead.	Yes (affects new certificates only)
Certificate Authority + Intermediate Certificate / CA Integration	The fixed signing provider used when Use Domain Default is off. The intermediate must be under the Local PKI certificate authority's root.	Yes (affects new certificates only)
Default Validity (days)	Default certificate lifetime (1–825)	Yes
Maximum Validity (days)	Maximum certificate lifetime	Yes
Default Algorithm	Key algorithm (e.g., `ec-384`)	Yes
Default Digest	Digest algorithm (e.g., `sha384`)	Yes

Directory Metadata¶

These settings are surfaced in the ACME directory response:

Setting	Description
Terms of Service URL	Link to your certificate policy
Website URL	Link to documentation or support
CAA Identities	Certificate Authority Authorization identities

Activating and Deactivating Servers¶

Deactivating a Server¶

Setting a server to Inactive immediately stops it from processing new requests:

The directory endpoint returns an error
New account registrations are rejected
New orders cannot be created
Existing certificates remain valid until their expiry

To deactivate:

Navigate to the server's detail page
Set Status to Inactive
Save changes

Note: Deactivating a server does not revoke existing certificates or invalidate existing accounts. Clients with valid certificates will continue to operate until renewal time, at which point they will fail if the server remains inactive.

Reactivating a Server¶

Set Status to Active to resume operations. Existing accounts and their domain bindings remain intact.

Changing the Signing Provider¶

Switching Use Domain Default¶

Navigate to the server's detail page
Toggle Use Domain Default:
On — the server starts resolving the signing provider per order from each requested domain's default (Admin → Domains)
Off — choose a Certificate Authority Source (Local PKI or Integration). For Local PKI, select the Certificate Authority and optionally an Intermediate Certificate under its root; for Integration, select the CA Integration
Save changes

Changing the Fixed Provider¶

With Use Domain Default off, you can change which intermediate certificate or CA integration signs new certificates:

Navigate to the server's detail page
Select a new Local PKI Certificate Authority and Intermediate Certificate, or a new CA Integration. Changing the certificate authority clears the intermediate, because only intermediates under the new certificate authority's root are valid
Save changes

Important: Both changes affect only certificates issued after the change. Existing certificates retain their original chain. If you are rotating your PKI, ensure clients trust both the old and new intermediates during the transition period.

Validity Period Settings¶

Default Validity¶

The default certificate lifetime used when: - The ACME client does not specify notBefore or notAfter in the order - The requested validity exceeds the maximum

Maximum Validity¶

The hard limit for certificate lifetime. Orders requesting a longer validity are capped to this value. The maximum allowed by the platform is 825 days (approximately 27 months), aligning with CA/Browser Forum guidelines.

Recommendations¶

Environment	Default Validity	Maximum Validity
Production	90 days	365 days
Development/Testing	30 days	90 days
High-security	30 days	90 days

Shorter validity periods reduce the impact of key compromise and encourage automation.

Rate Limits¶

The ACME server configuration includes optional rate limit settings:

Setting	Description
Orders per account per hour	Maximum new orders an account can create per hour
Certificates per domain per week	Maximum certificates for a single domain per week

Note: Rate limits are configured but not currently enforced. They are reserved for future implementation.

Viewing Orders and Certificates¶

From the server detail page, you can view:

Orders Tab¶

Lists all orders placed against this server:

Order ID — Unique identifier
Account — The requesting account
Status — pending, ready, processing, valid, or invalid
Domains — Requested identifiers
Created — Order timestamp
Expires — Order expiry time

Certificates Tab¶

Lists all certificates issued by this server:

Serial Number
Common Name
Subject Alternative Names
Validity Period
Algorithm
Status — Valid, Expired, or Revoked

Audit Logging¶

All ACME operations are logged to the platform's audit log:

Event	Description
`acme.account_created`	New account registration
`acme.order_created`	New certificate order
`acme.order_finalized`	CSR submitted for signing
`acme.certificate_issued`	Certificate successfully issued
`acme.authorization_failed`	Domain authorization denied

Navigate to Admin → Audit Log and filter by event type to review ACME activity.

Deleting an ACME Server¶

An ACME server configuration can only be deleted if it has no associated accounts. To delete:

Deactivate the server
Delete all accounts (or wait for them to naturally expire if applicable)
Navigate to the server detail page
Select Delete

Warning: Deleting a server removes all configuration. The UUID is not reused. Any ACME clients configured to use this server's directory URL will fail.

Multiple ACME Servers¶

You can create multiple ACME server configurations for different purposes:

Use Case	Configuration
Environment separation	Separate servers for dev, staging, production
Different validity policies	Shorter validity for external certificates, longer for internal
Different PKI hierarchies	Different intermediate certificates for different purposes
Organisational separation	Different servers for different business units

Each server has an independent URL namespace, account space, and configuration.

Directory Endpoint¶

The directory URL is the entry point for ACME clients:

https://your-region.zaita.com/acme/{server-uuid}/directory

A GET or POST request to this URL returns:

{
  "newNonce": "https://.../acme/{uuid}/new-nonce",
  "newAccount": "https://.../acme/{uuid}/new-account",
  "newOrder": "https://.../acme/{uuid}/new-order",
  "revokeCert": "https://.../acme/{uuid}/revoke-cert",
  "keyChange": "https://.../acme/{uuid}/key-change",
  "meta": {
    "termsOfService": "https://example.com/tos",
    "website": "https://example.com",
    "caaIdentities": ["example.com"],
    "externalAccountRequired": true
  }
}

Next Steps¶

Managing Accounts — Create and configure ACME accounts
Best Practices — Security and operational recommendations

WIF Challenge Mode¶

If your administrator has enabled the WIF feature for the installation, the server form offers Require WIF Challenge in place of External Account Binding. In this mode:

The server's Accounts page is replaced by Challenges. Each challenge names a trusted Issuer (from the server's issuer list), an exact Subject (the token sub claim) and the domains that workload may obtain certificates for.
Clients register an ACME account without credentials and prove their identity per authorization by answering a wif-01 challenge with a token from the identity provider (see the ACME WIF draft, draft-rasmussen-acme-wif).
Tokens must have a remaining lifetime no greater than Max Token Lifetime, and each token can be used once.
The mode cannot be changed while the server has accounts or challenges.

Troubleshooting WIF Challenges¶

When a wif-01 challenge fails, the ACME client only receives a generic error (for example, Not permitted for this identifier), so your policy is never disclosed to it. The full reason is recorded in your tenant's audit log as acme.wif_challenge_failed. The entry includes the reason, plus the token's issuer and subject and the matched challenge when one was found.

`reason`	Meaning
`issuer_not_accepted`	The token's `iss` is not in the server's issuer list
`missing_kid` / `unknown_kid`	The token has no `kid`, or the `kid` is not in the issuer's published keys
`signature_or_time_invalid`	The signature, `exp`, `nbf` or `iat` check failed
`missing_exp` / `lifetime_exceeded`	The token has no `exp`, or its remaining lifetime is above Max Token Lifetime
`audience_mismatch`	The token's `aud` does not contain the expected audience (recorded as `token_aud`)
`replayed`	The token has already been used
`subject_missing`	The token has no `sub`
`no_matching_challenge`	No challenge exists for this exact issuer and subject
`challenge_disabled`	The matching challenge is disabled
`identifier_not_allowed`	The requested domain is not one of the challenge's domains (recorded as `allowed_fqdns`)

With GitHub Actions, no_matching_challenge usually means the token's sub differs from the challenge's Subject. The format depends on the job. A job with environment: prod gets repo:<owner>/<repo>:environment:prod, and a pull request run gets repo:<owner>/<repo>:pull_request. An organisation or repository with a custom OIDC subject template gets that template instead. Copy the subject value from the audit entry into the challenge.