04 — Protocol Features Deep Dive¶

Part of the Domain Connect Knowledge Base

Feature Summary¶

Domain Connect is designed to handle the real-world complexity of DNS configuration. Beyond the basic "create some records" operation, it includes several sophisticated features that address common pain points in DNS management.

Feature	Purpose
Template system	Standardized, pre-approved DNS configuration contracts
Two-flow architecture	Synchronous (one-time, core draft) and asynchronous (ongoing, extension draft)
DNS Provider discovery	Automatic detection of protocol support via `_domainconnect` record
Variable substitution	Dynamic values in templates (IP addresses, verification tokens)
Conflict resolution	Rules for handling existing DNS records
SPF TXT record merging	Combining SPF records from multiple services without conflicts
Ephemeral records	Temporary records (e.g., domain verification) that can be removed without breaking the template
URL signature protection	Cryptographic signing of redirect URLs to prevent tampering
Template groups	Staged application of DNS configuration in multiple steps
Scope minimization	Limiting changes to exactly what the service needs
Extensibility	Unknown elements ignored, `crit` for must-understand, `vnd.` prefix for vendor extensions

1. Template System¶

Templates are JSON documents that serve as the formal contract between a Service Provider and a DNS Provider. A template fully describes:

What records to create (record type, hostname, value, TTL)
What variables are needed (dynamic values supplied at runtime)
How to handle conflicts (what to do if records already exist)
Identification (provider ID, service ID — used in URLs and OAuth scope)
Display metadata (provider name, service name, logo URL, description)

Templates are versioned. The version field is an integer incremented with each update, providing a simple coordination mechanism between providers.

Template scope minimization is a design principle: templates SHOULD request only the minimum set of DNS records and variables needed for the service to function. This limits the blast radius if anything goes wrong and makes the user consent screen more understandable.

2. Two-Flow Architecture¶

Synchronous Flow¶

When: One-time service setup where the user is present
How: HTTP redirect with template ID + variables in the URL → user authenticates → consents → DNS updated → redirect back
Best for: Website builders, email setup, basic service integrations
User experience: Single session, typically completes in 30 seconds

Asynchronous Flow (OAuth)¶

Specified in the extension IETF draft-ietf-dconn-domainconnect-async-00 (asynchronous flow extension) (Jun 2026); removed from the core draft in -02.

When: Multi-step setup, or ongoing DNS management needed
How: OAuth 2.0 authorization grant → access token issued → SP can make API calls over time
Best for: Complex setups (e.g., first verify ownership, then configure MX), dynamic DNS, services that update their infrastructure
User experience: User approves once; subsequent DNS changes happen in the background

A DNS Provider MAY implement only the synchronous flow. The synchronous flow is RECOMMENDED as it covers the vast majority of use cases. Service Providers may use either flow, or both.

3. DNS Provider Discovery¶

The _domainconnect DNS record is the entry point for the entire protocol. When a user enters their domain at a Service Provider:

SP looks up _domainconnect.<domain> as a TXT record
The value of the TXT record contains the URL fragment pointing to the DNS Provider's API
SP fetches the full "settings" JSON document from that endpoint
Settings document contains:
urlSyncUX: endpoint for the synchronous flow
urlAsyncUX: endpoint for the asynchronous OAuth flow (defined in the async extension)
urlAPI: endpoint for the REST API (template query; also the asynchronous API)
providerName: human-readable DNS Provider name
providerDisplayName: display name for UI
nameServers: optional list of the zone's name servers
SP then checks whether its specific template is supported by calling GET {urlAPI}/v2/domainTemplates/providers/{providerId}/services/{serviceId}

If at any step the protocol fails (no _domainconnect record, settings unavailable, template not found), the Service Provider falls back gracefully to manual instructions.

4. Variable Substitution¶

Templates frequently need dynamic values — values that differ per-user or per-deployment:

The IP address of the service's server
A unique verification token for domain ownership checks
A CNAME target specific to the user's account

These are expressed as named variables in the template using %VARIABLENAME% notation:

{
  "type": "A",
  "host": "@",
  "pointsTo": "%IP%",
  "ttl": "600"
}

The Service Provider passes variable values in the redirect URL:

?domain=example.com&IP=198.51.100.1&RANDOMTEXT=abc123

Two notation systems are intentionally used to prevent injection attacks:

{variable} (RFC 6570 URI Template syntax) — used for protocol-level URL templates defined in the specification
%VARIABLE% — used for Service Provider-defined template variables and dynamic elements

This distinction ensures that a misconfigured implementation cannot accidentally inject template variables into protocol-level URL components.

Built-in variables: The protocol defines reserved variables like domain and host that cannot be used as template variable names.

5. Conflict Detection and Resolution¶

When a template is applied to a zone, the DNS records it wants to create may conflict with records already in the zone. Domain Connect provides fine-grained control over how these conflicts are handled.

Conflict detection by record type¶

For A and AAAA records:

A conflict exists if an A or AAAA record with the same hostname already exists

For CNAME records:

CNAME records cannot coexist with other records at the same hostname
Domain Connect treats any existing record at the same hostname as a conflict

For MX and SRV records:

A conflict exists if a record of the same type already exists at the same hostname

For NS records:

Conflicts with all records at the same hostname and below it

For TXT records (special handling):

The txtConflictMatchingMode field controls TXT conflict detection:

None — no conflict detection; add the new record regardless
All — any existing TXT record at this hostname is a conflict
Prefix — only TXT records starting with txtConflictMatchingPrefix are conflicts (see SPF merging below)

Essential flag¶

Each record in a template has an essential attribute:

Always (default) — the record must stay as applied for the lifetime of the template; if it is later removed or changed (by the user or another template), the whole template is removed
OnApply — the record is written when the template is applied, but may later be changed or removed without affecting the template

This allows templates to contain records the user is expected to change later (e.g., a DMARC policy). It only has an effect at DNS Providers that track applied template state.

A record identical to one already in the zone is not a conflict.

Force flag¶

In the asynchronous flow (async extension), the Service Provider can include a force=1 parameter to apply a template despite conflicts. The synchronous flow has no such parameter: the user resolves conflicts on the consent screen.

6. SPF TXT Record Merging¶

The problem: Multiple services may need to add their own SPF (Sender Policy Framework) entries to a domain's TXT records. SPF requires exactly one TXT record containing all authorized senders. A naive implementation would create multiple SPF records, which is invalid and breaks email delivery.

Domain Connect's solution: The SPFM pseudo-record type handles SPF merging automatically.

A template can specify an SPFM record:

{
  "type": "SPFM",
  "host": "@",
  "spfRules": "include:spf.protection.outlook.com"
}

When applying this record, the DNS Provider:

Checks if an SPF record already exists at the hostname
If yes, merges the new include: mechanism into the existing SPF record
If no, creates a new SPF TXT record

This means a domain can have both Microsoft 365 and Google Workspace configured for email security without breaking either service's SPF requirement.

Example:

Before: v=spf1 include:_spf.google.com ~all
After:  v=spf1 include:_spf.google.com include:spf.protection.outlook.com ~all

7. Ephemeral Records¶

Some service configurations require temporary DNS records — typically for domain ownership verification. A service might need to place a TXT record to prove you control the domain, then delete it once verification is complete.

Domain Connect supports ephemeral records through the essential: "OnApply" flag combined with template state tracking: the record is written when the template is applied, and can later be removed by the user or the service without the DNS Provider treating it as a conflict and removing the whole template. The protocol does not remove such records automatically.

8. URL Signature Protection¶

To prevent a malicious actor from crafting a fraudulent redirect URL that tricks a user into configuring DNS for a different service, Domain Connect supports cryptographic URL signing.

How it works:

The Service Provider generates a signature over the redirect URL using a private key
The Service Provider publishes the corresponding public key in DNS at {key}.{syncPubKeyDomain} (e.g. _dcpubkeyv1.domainconnect.example.com)
The redirect URL includes the signature and a key identifier
The DNS Provider fetches the public key from DNS and verifies the signature before processing the request

What this prevents: A bad actor cannot modify the URL parameters (e.g., change the IP address to redirect the domain to their server) without invalidating the signature.

Template-level control: A template that sets syncPubKeyDomain requires signed requests. This allows low-risk templates to work without signing while high-risk templates (those that affect where web traffic goes) can require it. For unsigned requests the DNS Provider shows an additional phishing warning — since -03 this is the default and replaces the deprecated warnPhishing template flag.

Public key DNS record format (p = fragment index, a = algorithm, d = key data; long keys are split over several records):

_dcpubkeyv1.exampleservice.domainconnect.org. IN TXT "p=1,a=RS256,d=<base64-encoded-public-key>"

9. Template Groups¶

A service may need to apply DNS configuration in multiple stages. For example:

First, create a TXT record to prove domain ownership
After verification, create MX and CNAME records to configure the actual service

Template groups (groupId) enable this. Records in a template can be assigned to named groups. When applying the template, the Service Provider can specify which groups to apply:

GET /apply?domain=example.com&groupId=verification  → applies only verification records
GET /apply?domain=example.com&groupId=service        → applies only service records

Both groups are part of the same template (same service), so they share conflict resolution rules and appear as a single service in the DNS Provider's tracking.

10. Template State Tracking¶

DNS Providers are expected to track which templates have been applied to which domains. This enables:

Conflict detection across multiple services: If Service A already set a CNAME at www.example.com, Service B's attempt to set a different CNAME at the same label can be detected and handled appropriately
Revert capability: When a user disconnects a service, the DNS Provider knows exactly which records were added by that service and can remove only those records
Multi-instance support: Some records can have multiple instances (e.g., multiple DKIM TXT records for different email providers); template state tracks which instance belongs to which service

11. Versioning and Extensibility¶

Added in -04, so the protocol can evolve without breaking existing deployments:

Ignore unknown: implementations ignore template properties, record fields, settings properties and apply parameters they do not recognize.
Must understand: a crit list names elements that must not be ignored; an implementation that does not understand one of them refuses the template or request.
Name spaces: unprefixed names are reserved for the standard (coordinated through IANA registries), vnd. is for vendor-specific extensions, and dc. for future standard apply parameters.
Versions: the HTTP interface is versioned by the /v2 path, the template format by the optional templateSpecVersion property (currently 1).

Supported DNS Record Types¶

Domain Connect supports all standard DNS record types that may be needed for service integrations:

Record type	Common use
A	IPv4 address — website hosting
AAAA	IPv6 address — website hosting
CNAME	Alias — subdomain redirects, CDN
MX	Mail exchange — email delivery
TXT	Text — SPF, DKIM, domain verification
SRV	Service locator — VoIP, messaging
NS	Nameserver delegation (support optional)
SPFM	Computed type — SPF merging (Domain Connect specific)
CAA and other IANA types	Generic types; record data in presentation format (support optional)
TYPE{n}	Unknown types per RFC 3597 — future-proofing

Previous: 03 — How It Works | Next: 05 — Use Cases