Domain Connect Protocol - DNS provisioning between Services and DNS Providers

The following use cases illustrate the wide range of applications where Domain Connect simplifies and automates DNS configuration, from basic service onboarding to complex, dynamic DNS management scenarios.¶

While Domain Connect offers significant advantages in automating DNS configuration, it's important to recognize scenarios where it might not be the ideal solution:¶

Templates are core to Domain Connect, as they fully describe a service owned by a Service Provider and contain all of the information necessary to enable and operate/maintain the service in the form of a set of records.¶

The individual records in a template MAY be assigned to a group identified by a "groupId". This allows for the application of templates in different stages. For example, an email provider might first set a TXT record to verify the domain, and later set an MX record to configure email delivery. While done separately, both changes are fundamentally part of the same service.¶

Templates MAY also contain variable portions, as often values of data in DNS change based on the implementation and/or user of the service (e.g. the IP address of a service, a user id, etc.).¶

The template is defined by the Service Provider and manually onboarded with the DNS Provider. This is an out-of-band process between the Service Provider and the DNS Provider and not covered by this specification.¶

DNS Providers are trusted parties by virtue of their existing full access to the DNS zone. DNS Providers enforce user authorization checks before enacting any DNS zone changes, and present proposed changes to the user in a human-readable form.¶

Service Providers are not assumed to be trusted by default. A malicious actor may attempt to exploit user trust by impersonating a legitimate Service Provider. Trust between DNS Providers and Service Providers is therefore established out-of-band - typically through an onboarding process involving contractual agreements or template acceptance policies - during which the DNS Provider verifies the legitimacy of the Service Provider and its templates.¶

Templates define and restrict the permitted scope of DNS modifications. By fixing the records that a Service Provider may affect, templates ensure that no changes beyond the approved scope can be applied.¶

To attach a domain name to a service provided by a Service Provider, the user would first enter their domain name.¶

Instead of relying on examination of the nameservers and mapping these to DNS Providers, DNS Provider discovery is handled through simple records in DNS and an API. The Service Provider queries for a specific record in the zone that returns a REST endpoint to initiate the protocol. When this endpoint is called, a Domain Connect compliant DNS Provider returns information about that domain and how to configure it using Domain Connect.¶

To apply the changes to DNS, this document defines a synchronous web flow. The DNS Provider presents a consent UX to the user and applies the template within the same interaction session.¶

[DC-SPEC] also defines an asynchronous flow based on OAuth. Other flows may be defined in the future. Therefore, although it is RECOMMENDED to cover the synchronous flow, implementers MAY decide not to do so and only implement other flows not defined in this document. The signaling offered by DNS Provider discovery allows for that.¶

This flow is tailored for the Service Provider that requires a user-attended, one-time change to DNS configuration. In this flow, the user is present throughout: they authenticate with the DNS Provider and explicitly consent to the changes within a single interaction session.¶

The term "synchronous" refers to this user-interaction model - not to immediate DNS propagation. The DNS Provider commits to applying the template upon user consent, but the changes MAY be queued internally and propagation to authoritative servers MAY take additional time. Service Providers MUST NOT assume that DNS records are resolvable immediately after the flow completes; see Section 8.4.¶

Steps:¶

1. User Provides Domain Name: The user initiates the process by providing their domain name to the Service Provider.¶
2. Service Provider Initiates DNS Discovery: The Service Provider queries the DNS provider to discover the Domain Connect settings for the given domain.¶
3. DNS Provider Responds with Discovery URL Fragment: The DNS Provider responds with a URL fragment containing information where to query settings of DNS provider for a domain name.¶
4. Service Provider Requests DNS Provider Settings: The Service Provider uses the URL fragment to request the complete Domain Connect settings from the DNS Provider.¶
5. DNS Provider Provides Settings: The DNS Provider provides the settings, including information about API endpoints.¶
6. Service Provider Queries for Supported Template: The Service Provider checks if the DNS Provider supports the specific template required for the service.¶
7. DNS Provider Responds with Template Support Status: The DNS Provider confirms if they support the requested template.¶
8. Service Provider Presents Connection Link: The Service Provider presents a connection link to the user, which leads to the DNS Provider's Domain Connect service.¶
9. User Navigates to DNS Provider: The user navigates the link and user agent is directed to the DNS Provider's website.¶
10. DNS Provider Performs URL Lookup and Signature Key Verification (if required): If the template requires signing, the DNS Provider looks up the URL signature keys in DNS.¶
11. DNS Provider Checks Request URL Signature (if required): The DNS Provider verifies the signature of the request URL.¶
12. Service Provider Requests Authentication: The Service Provider requests authentication from the user.¶
13. User Authenticates: The user authenticates with the DNS Provider.¶
14. DNS Provider Checks Domain Name in Customer's Account: The DNS Provider verifies that the user is authorized to make change to the domain's DNS zone.¶
15. DNS Provider Requests Consent for DNS Changes: The DNS Provider asks the user for consent to apply the changes to the DNS zone.¶
16. User Confirms Consent: The user confirms their consent to the DNS changes.¶
17. DNS Provider Applies Changes to DNS: The DNS Provider applies the changes to the zone.¶
18. DNS Provider Redirects or User Flow Termination: The DNS Provider either redirects the user agent back to the Service Provider or gracefully terminates the user flow.¶
19. Service Provider Queries DNS Records: The Service Provider queries the DNS records to verify that the changes have been applied.¶
20. DNS Server Returns New DNS Records: The DNS Server returns the updated DNS records.¶
21. Service Provider Reports Success: The Service Provider reports to the user that the domain has been successfully connected to the service.¶

A template is defined as a standard JSON data structure containing the following data. Field values MUST be defined unless otherwise indicated.¶

Each template record is an entry that contains a type and several other values depending on the type.¶

Many of these values can contain variables, which are expressed as strings surrounded with "%" or special variable "@" (See: Section 9.1). Variables are replaced with values when the template is applied.¶

Each record MUST contain the following elements unless otherwise specified.¶

The following table lists the fields that MAY be defined for each record type. Other fields MUST NOT be used.¶

The Service Provider MUST publish their public signing key in one or more DNS TXT records at the host formed by prepending the "key" apply parameter value as a label to the "syncPubKeyDomain" template field value.¶

Each TXT record MUST conform to the following grammar:¶

To allow for key rotation or use of multiple keys, the Service Provider MAY publish key records at multiple hosts within "syncPubKeyDomain". The "key" apply parameter identifies which host to query for each request and MUST be included in the signed apply request.¶

To account for DNS record size limits, a public key MAY be split across multiple TXT records at the same host. All fragments MUST be reassembled in ascending numeric order of "p" before use. The values "a" and '"d"' MUST be equal for all such TXT records on the same host.¶

Given the public key (line breaks for brevity):¶

Published at "_dcpubkeyv1.<syncPubKeyDomain>" as (line breaks for brevity):¶

EXAMPLE: Example: public key published as DNS TXT records¶

The Domain Connect endpoints returned in the JSON during discovery are in the form of URLs.¶

The first set of endpoints are for the UX that the Service Provider links to. These are for the synchronous flow where the user can click to grant consent and have changes applied.¶

The second set of endpoints are for the REST API.¶

All endpoints begin with a root URL for the DNS Provider such as:¶

They MAY also include any path segment at the discretion of the DNS Provider. For example:¶

The root URLs for the UX endpoints and the API endpoints are returned in the JSON payload during DNS Provider discovery.¶

Normative URI template of the template query end-point per [RFC6570]:¶

This URL is be used by the Service Provider to determine if the DNS Provider supports a specific template.¶

The following table describes the parameters of the URI template:¶

Returning a status of 200 without a body indicates the template is supported. The DNS Provider MAY disclose the version of the template in a JSON object with field "version" (see: version field (Section 6.1) or the full JSON object of deployed template.¶

Returning a status of 404 indicates the template is not supported.¶

After the synchronous flow completes, the Service Provider SHOULD verify that the expected DNS records are present in the zone by querying the authoritative DNS server for the domain.¶

DNS verification MUST be treated as the authoritative signal of success. A "redirect_uri" callback received without an "error" parameter does not constitute proof that the template was applied. Users can modify redirect URIs in the user agent, so a successful-looking redirect MUST NOT be relied upon as confirmation of DNS changes. Similarly, a "redirect_uri" callback received with an "error" parameter does not constitute proof that the template was NOT applied; the DNS Provider MAY have applied the template before the error condition arose.¶

Receipt of a protocol-level completion signal MAY be used as a trigger to initiate DNS verification. However, the Service Provider MUST account for DNS propagation delay and MUST implement a retry mechanism with appropriate intervals until the expected records are observed or a timeout is reached.¶

To minimize delays caused by DNS resolver caching, it is RECOMMENDED that the Service Provider query a DNS resolver configured with low TTL overrides, or query the authoritative name servers directly.¶

After variable substitution, each template record's "host" or "name" field value is combined with the "domain" and "host" apply parameters to produce the final DNS owner name for the resource record.¶

The challenge with SPF RFC 7208 [RFC7208] records and Domain Connect is that an individual service might recommend an SPF record. If only one service were active, this would be accurate. But with several services together only the DNS Provider is able to determine the valid shape of a SPF TXT record.¶

One solution to this problem is to merge all related records. At the highest level, this means taking everything between the "v=spf1" and the "all" from each of the records and merging them together, terminating with hard-coded modifier on "all" at the end. For an SPF record to fulfill it's purpose of protection against malicious email delivery, it is RECOMMENDED to use a fixed modifier "~" advising lower rating of the messages from other sources not specified in SPF, however DNS Provider MAY set this modifier at their own discretion and according to the current best practice.¶

The other would be to write intermediate records, and reference these locally.¶

There are advantages and disadvantages to both approaches. SPF records have a limit of 10 DNS lookups and record length is limited to 255 characters. So depending on the embedded records both approaches might have advantages.¶

The implementation would be left to the DNS Provider, but to facilitate this SPF records SHOULD NOT be included in templates. Instead, a new pseudo-record type is introduced in the template called "SPFM". This has the following attribute:¶

"spfRules":

Determines the desired rules, basically everything but leading "v=spf1" and trailing "all" rule - see: SPF Rules (Section 6.2)¶

When a template is added or removed with an "SPFM" record in the template, some code would need to take the aggregate value of all "SPFM" records in all templates applied as well as existing SPF TXT record on the host and recalculate the resulting SPF TXT record. In case several sources specify the same rule with a different policy DNS Provider SHOULD apply the least restrictive one as a result. "soft failure" SHOULD be preferred over "hard failure", "neutral" SHOULD be preferred over "soft failure".¶

DNS Provider SHOULD also allow the end user to modify the SPF record after merging.¶

Due to merging step in between, the resulting SPF TXT records are considered non-essential. That means the user may decide to override the final calculated value or remove the whole SPF record. This action MUST NOT lead to removal of any related templates in conflict detection and template integrity routines if implemented by the DNS Provider.¶

If the existing TXT record makes the merging operation not possible, the DNS Provider MUST handle this situation the same way as a conflict and either let the end-user resolve it in the UX.¶

Service Providers MUST NOT check content of TXT SPF record for an exact match, as it might be strongly influenced by the DNS Provider merging strategy and user actions.¶

See Appendix A.6.¶

DNS Providers MAY choose to maintain state inside records in DNS indicating the templates writing the records.¶

A DNS Provider that maintains this state may be able to provide an improved experience for users, telling them the services enabled. They also may be able to have more advanced handling of conflicts and assure integrity of applied template instances.¶

A template instance is identified by the pair "domain" and "host" where the template has been applied. Therefore, the same template MUST be able to be applied more than once to the same DNS zone identified by "domain", as long as the value of "host" parameter differs. Application of the same template with same "host" MAY be handled as an update by DNS provider, or just trigger a regular conflict detection and resolution routine by DNS Provider - removal of the previous instance and apply of the new instance.¶

Manual changes made by the user at the DNS Provider MAY also trigger conflict detection against applied templates in order to maintain integrity.¶

The following steps give an overview of the template application process. Each step is described in detail in the sections below.¶

1. Verify template applicability - For synchronous flow requests, the DNS Provider MUST verify that the template's "syncBlock" field is not "true". If it is, the DNS Provider MUST NOT process the request and MUST return an error.¶
2. Verify zone ownership - The DNS Provider MUST verify that the target zone identified by "domain" is present in the user's account and that the user is authorized to make changes to it.¶
3. Filter records to apply - select records applicable for further processing based on "groupId" property of the template and "groupId" apply parameter (see Section 10.3).¶

4. Resolve variables - All variable expressions in active template records are substituted with the values provided by the caller, producing a concrete set of DNS resource records (RRs) to be applied (see Section 9.2).¶

   1. abort if rendered RRs are not possible to be applied to the target zone¶

5. Perform conflict detection - The DNS Provider checks the resolved RR set against the existing zone content according to the conflict detection rules (see Section 10.4).¶

   1. Identify individual zone records that conflict with the resolved RR set.¶
   2. (only DNS Providers tracking template state): Check each resolved RR against essential records of previously applied templates. Identify which previously applied templates own conflicting records and would be removed in their entirety (see Section 10.4.1.2).¶
   3. (only DNS Providers tracking template state): Mark instances of the same template applied on the same "host" for removal unless "multiInstance" is set for the template (see Section 10.4.1.1).¶
6. Pre-calculate conflict resolution - Determine the full set of records and, where applicable, template instances that would be removed upon application (see Section 10.5).¶

7. Obtain user authorization - The DNS Provider MUST present the intended changes and the pre-calculated conflict consequences to the user and obtain explicit authorization before proceeding (see Section 10.6).¶

   1. abort if authorization not granted¶

8. Apply changes - After authorization is granted, or at later point in Asynchronous flow:¶

   1. Remove all records pre-calculated for removal from the zone.¶
   2. Write the resolved RR set to the zone in totality.¶
   3. (only DNS Providers tracking template state): Record the new template instance for the "domain" and "host" pair and remove the state of any template instances that were resolved for removal.¶

Before variable substitution and any further processing, the DNS Provider MUST determine the active record set - the subset of template records that are subject to processing - by applying the following rules to each record in the template:¶

1. A record with no "groupId" field is always active, regardless of whether a "groupId" parameter was supplied in the apply request.¶
2. A record with a "groupId" field is active if and only if its "groupId" value appears in the list supplied as the "groupId" apply parameter. Matching is case-sensitive and exact.¶
3. If no "groupId" parameter is supplied in the apply request, all records are active irrespective of whether they carry a "groupId".¶

Only active records MUST be subject to variable substitution, conflict detection, and zone write operations. Inactive records MUST be excluded from all template processing steps and MUST NOT be written to the zone.¶

If the "groupId" parameter is supplied but no record in the template carries a "groupId" that matches any of the specified identifiers (i.e., the active record set consists solely of ungrouped records or is empty), the DNS Provider MUST return an error and MUST NOT make any changes to the zone.¶

Conflict detection is performed by the DNS Provider prior to template application. The rules below ensure predictable conflict resolution between DNS Providers. Each rule applies to records on the same host, unless otherwise specified.¶

Note: DNS Provider MUST also check applicability of all generated records to the target DNS zone in its own system. For example it is very common for DNS provider not to allow CNAME records to be at the zone apex.¶

A DNS Provider not maintaining applied template state, applying a template whose records conflict with any existing record in the zone MUST remove all those conflicting records.¶

When a DNS Provider maintains applied template state, applying a template whose records conflict with records written by a previously applied template MUST cause the conflicting prior template to be removed in its entirety, unless a conflicting record is explicitly marked as non essential and eligible for removal. As an example: if template T1 wrote records A and B, and template T2 is applied with records B and C, record B conflicts, and T1 is removed together with all its records before T2 is applied.¶

It is ultimately left to the DNS Provider to determine the amount of disclosure and/or conflict detection.¶

The DNS Provider MUST inform the user of the service that is about to be enabled when requesting authorization. If the user wishes to review the specifics, the DNS Provider SHOULD make the individual DNS records being set available, in order to allow informed decision before changes are applied.¶

If conflicts are detected - at either the template or record level - the DNS Provider SHOULD present these to the user before authorization is granted. For template instances this means identifying services that would be disabled; for records this means identifying records that would be deleted or overwritten.¶

The DNS Provider MUST allow the user to override a detected conflict and proceed with the template application, or to abort the process.¶

When presenting the authorization request to the user, the DNS Provider SHOULD display the template's "providerName" and "serviceName" fields. When a caller supplies "providerName" or "serviceName" request parameters (permitted only when the template's "sharedProviderName" or "sharedServiceName" flags are set, respectively), the DNS Provider SHOULD use those values to augment the displayed name. It is RECOMMENDED however to also display the original "providerName" and "serviceName" defined in the template.¶

When the template's "warnPhishing" field is "true", the DNS Provider SHOULD display additional warnings prompting the user to verify the source of the request before proceeding, and SHOULD provide a more verbose description of the changes about to be applied.¶

In the Synchronous Flow, after authorization is granted, the DNS Provider applies the template to the DNS zone.¶

In the Asynchronous Flow this happens in later point in time. In this case conflict resolution MUST be calculated again for the actual state of the zone and parameters provided with the apply request.¶

The DNS Provider MUST remove all conflicting templates and records from the target zone.¶

The DNS Provider MUST apply all records of the template in totality as one atomic operation.¶

Examples of template processing are in Appendix A.¶

Templates that accept variable parameters introduce a phishing risk. The more static the values in a template record, the more secure the template. When variable values cannot be avoided, a bad actor could craft an apply URL substituting a malicious value - for example, a hijacked IP address - and send it to users as a seemingly legitimate reconfiguration request. The user would be presented with a DNS Provider consent screen that appears valid, but would result in DNS being pointed at infrastructure under the attacker's control.¶

Not all templates are susceptible; the risk is proportional to how much of a record's content is controlled by variables. Three mitigations are available to template authors and Service Providers: digitally signing apply requests (see the Section <<Section 8.3.2.1,format=title>>), using an alternative flow not prone to this risk and disabling the synchronous flow via "syncBlock", and setting the "warnPhishing" flag to prompt the DNS Provider to display additional warnings to the user.¶

Per [RFC8552], please add the following entry to the "Underscored and Globally Scoped DNS Node Names" registry:¶

IANA is requested to create a new registry named "Domain Connect Settings Properties" under a new registry group "Domain Connect Protocol".¶

Registration policy: Specification Needed (see [RFC8126]).¶

Each entry in the registry MUST include:¶

The following properties from this specification constitute the initial contents of the registry:¶

EXAMPLE: Full template example¶

Consider a template for setting a single host record. The records section of the template would have a single record of type "A" and could have a value of:¶

EXAMPLE: Single static host record example¶

This would have no variable substitution and the application of this template to a domain would simply set the host name "www" to the IP address "192.0.2.1"¶

In the case of a template for setting a single host record from a variable, the template would have a single record of type "A" and could have a value of:¶

EXAMPLE: Single variable host record for A example¶

A query string with a key/value pair of¶

would cause the application of this template to a domain to set the host name for the apex A record to the IP address "198.51.100.2" with a TTL of 600¶

This example shows how to include a set of unspecified record types on an example of CAA records:¶

EXAMPLE: Unspecified record type CAA example¶

This would have no variable substitution and the application of this template to a domain would add 2 CAA records.¶

Consider a DNS Zone before a template application:¶

Now application of the following template:¶

The following DNS Zone would be generated after the template is applied.¶

A following list of conflicts would be detected in this case:¶

After changes applied the zone would be updated to the following state. Note existing A and AAAA records removed due to the conflicts as well as SPF TXT record content merged with the existing entry.¶

Consider a DNS Zone before a template application:¶

Now application of the following template of Mail service:¶

Expected result in the DNS Zone¶

In the next step application of the following template of Newsletter service:¶

Expected result in the DNS Zone. Note merged SPF entry.¶