Skip to content

Delegated DNS-01 in the Windows Agent

The Windows Agent uses CertIntel Delegated DNS-01 for its native ACME workflows. The service publishes and removes the challenge value, verifies authoritative DNS propagation, and then lets the configured certificate authority validate it. There is no separate DNS hook or scheduled ACME client to configure.

Add a delegation to a workflow

  1. In CertIntel, open Manage → Delegated DNS-01 and create a delegation for the base domain to validate. Copy the username and one-time secret.
  2. In the agent, open Workflows → New certificate and continue to the DNS step. Enter the delegation username and secret for each base domain.
  3. Select Verify credentials. The agent authenticates the credential and retrieves the exact CNAME destination that belongs to it.
  4. Publish the displayed CNAME at your authoritative DNS provider, then continue after the agent verifies it.

For example:

_acme-challenge.shop.example.com.  CNAME  <assigned-name>.acme.certin.tel.

Use the exact name and destination shown by CertIntel. Some DNS providers want a trailing dot; Cloudflare records must be DNS only, not proxied. See Delegated DNS-01 in the dashboard for record creation, rotation and revocation.

The secret is sent only to the local service, stored in its protected secret store, and never displayed again. A custom API base is available under the advanced options for private or non-default CertIntel deployments.

Apex and wildcard names

shop.example.com and *.shop.example.com use the same _acme-challenge.shop.example.com delegation. Configure that base domain once. The agent preserves both active TXT values when the CA requests the apex and wildcard authorizations together.

Test or replace a credential

Open Manage workflow → DNS delegations to test the current mapping or use Add / replace delegation to supply a different username and secret. The agent checks that the credential's assigned CNAME destination matches the configured domain before saving it.

For advanced provisioning, after a delegation mapping already exists in the agent configuration, an elevated prompt can replace only its protected secret:

certintel-agent secret set dns DELEGATION-ID

The command prompts without echo. Use --stdin for automation. The current agent does not expose general-purpose dns01 create or dns01 delete hook commands; DNS challenge operations belong to its persisted workflow/order state.

What happens during issuance

Before publishing a challenge, the service:

  • authenticates the scoped delegation credential;
  • confirms the public _acme-challenge CNAME points to the assigned target; and
  • merges its value without evicting another active value.

The agent then checks the TXT response directly at authoritative nameservers. It uses fresh wire queries rather than the operating-system DNS cache. Public resolvers help discover the authority; if public or authoritative DNS is unreachable, the agent can fall back to the machine's configured DNS servers. Those local servers may still return cached data.

Checks run every ten seconds, for at most 30 attempts and five minutes. A TXT API write alone is not treated as success: the expected value must be visible in DNS before the CA is asked to validate it. On failure, the saved order, key and CSR remain available for a safe retry. Challenge values owned by the agent are removed when the authorization is terminal, including recovery after a restart.

Current ownership limit

Use a delegation from one issuing agent host at a time. The service safely serializes workflows on one host, but the Delegated DNS-01 API does not yet offer a conditional update that lets multiple machines coordinate the same two-value set without a race.

Troubleshooting

Symptom What to check
Credential verification fails Confirm the username and secret belong to the same delegation and the API base is correct. Rotate the secret in CertIntel if it is no longer available.
CNAME verification times out Copy the exact record name and destination again, disable DNS proxying, and wait for the authoritative zone to publish the change.
TXT propagation fails after publication Check delegation health and authoritative DNS. The error and responsible nameserver appear in Activity, without exposing the challenge value.
Delegation already holds two values Another authorization or host is using it. Do not delete an unknown value; let the existing operation finish, then retry.
A retry appears to resume old work This is expected. The agent retains the order, CSR and key after a propagation failure so retrying does not create an unnecessary new order.