Domain Connect Protocol - DNS provisioning between Services and DNS Providers

User trust in the DNS Provider is an essential factor. DNS Provider is a trusted party by the fact that DNS Provider has full technical access to the DNS zone already. Users depend on their DNS Providers to accurately reflect DNS record modifications initiated through Domain Connect. Consequently, DNS Providers are expected implement authorization checks to validate user permissions prior to enacting any DNS zone changes. Furthermore, DNS Providers are responsible for translating template specifications into a human-readable format, enabling users to readily comprehend the nature and impact of proposed DNS record changes.¶

Users would typically place trust in Service Providers to act responsibly and only make DNS modifications that are within the scope defined by the approved template, however it shall be observed that a malicious actor may try to exploit this trust by acting as a benign Service Provider or building a fake one, therefore by default Service Provider shall not be assumed to be a trusted party in the protocol considerations.¶

A foundational element to close this gap is the establishment of trust between DNS Providers and Service Providers. DNS Providers verify the legitimacy and security of templates provided by Service Providers as well as they are able to verify textual information included in the template and provided to the user, such as provider name or service name. This trust is typically established through an onboarding process which may involve contractual agreements or appropriate template acceptance policies.¶

Templates are central to the trust model, defining the permitted scope of DNS zone modifications and restricting Service Provider actions, preventing unauthorized changes beyond the template's specified parameters. The template defines the types of DNS records within the zone and together with a distinct domain name and optionally sub-domain with user consent it defines clearly the part of the zone that the Service Provider is authorized to modify via the template application. Service Providers create templates which are then onboarded by DNS Providers, either adhering to a published template definition or based on bilateral agreements. The DNS Provider has very explicit knowledge and control of the settings being changed to enable a service.¶

Some templates can be called by multiple companies, or be used for different purposes.¶

For example, most services are sold and provided by the same company. However, some Service Providers have a reseller channel. This allows the service to be provided by the Service Provider, but sold through third parties. It is often this third party reseller that configures DNS.¶

While each reseller could enable Domain Connect, this is inefficient for the DNS Providers. Enabling a single template that is shared by multiple resellers would be more optimal.¶

As another example, some templates may be used for different purposes by the same company.¶

To facilitate these use cases, the ability to pass in additional context for the display of the providerName and serviceName is enabled. This is only allowed when the template enables the capability through the sharedProviderName and/or sharedServiceName flags.¶

Note: The shared flag used to be used for this purpose, but has been deprecated.¶

The exact message presented to the user is up to the DNS Provider. However it is recommended that these fields be used to augment the display of the serviceName and providerName from the template, not replace it.¶

Note: When a Service Provider has a large reseller channel, it is highly recommended that the Service Provider creates an API for their resellers to ease the implementation of Domain Connect. There are elements of convenience in doing this around Domain Discovery and URL Formatting. But this would be required if the template required signatures.¶

Using the OAuth flow is a more advanced use case needed by Service Providers that have more complex configurations that may require multiple steps and/or are asynchronous from the user's interaction.¶

Details of an OAuth implementation are beyond the scope of this specification. Instead, an overview of how OAuth is used by Domain Connect is given here.¶

Not all DNS Providers will support the asyncronous flow. As such it is recommended that Service Providers relying on an OAuth implementation also implement a synchronous implementation.¶

Service Providers wishing to use the OAuth flow MUST register as an OAuth client with each DNS Provider. This is typically a manual process, however other solutions like OAuth Dynamic Client Registration [RFC7591] MAY be offered by DNS Provider as well.¶

To register, the Service Provider would provide (in addition to their template) any configuration necessary for the DNS Providers OAuth implementation. This includes valid URLs and Domains for redirects upon success or errors of OAuth flow, token validity, presence and validity of refresh tokens etc.¶

Note: The validity of redirects are very important in any OAuth implementation. Most OAuth vulnerabilities are a combination of an open redirect and/or a compromised secret.¶

The DNS Provider SHOULD give the Service Provider a client id and a secret which will be used when requesting tokens. For simplicity the client id MAY be the same as the providerId, however it is up to the agreement between the parties involved. Any other form of client authentication within OAuth framework MAY be agreed between the parties.¶

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

To initiate the OAuth flow the Service Provider first links to the DNS Provider to gain consent.¶

This endpoint is similar to the synchronous flow described above. The DNS Provider MUST authenticate the user, verify the user has control of the DNS Zone for the domain, and ask the user for permission. Instead of permission to make a change to DNS, the permission is now to allow the Service Provider to make the changes on their behalf. Similarly the DNS Provider MAY warn the user that (the eventual) application of a template might change existing records and/or disrupt existing services attached to the domain.¶

While the variables for the applied template would be provided later, the values of some variables may be necessary to determine conflicts. As such, any variables impacting conflicting records SHOULD be provided in the consent flow. This primarly includes variables in hosts, and variables in the data portion for certain TXT records.¶

The protocol allows for the Service Provider to gain consent to apply multiple templates. These templates are specified in the scope parameter. It also allows for the Service Provider to gain consent to apply these templates to the domain or to the domain with multiple sub-domains. These are specified in the domain and host parameter. If conflict detection is implemented by the DNS Provider, they SHOULD account for all permutations, in order to inform the end user of all possible consequences of the authorised change.¶

The scope parameter is a space separated list (as per the OAuth protocol) of the template serviceIds. The host parameter is an OPTIONAL comma separated list of hosts. A blank entry for the host implies the template can be applied to the Zone Apex For example:¶

Upon successful authorization/verification/consent from the user, the DNS Provider MUST direct the end user's browser to the redirect URI. The authorization code MUST be appended to this URI as a query parameter of "code=" as per the OAuth specification.¶

Similar to the synchronous flow, upon error the DNS Provider MAY append an error code as query parameter "error". These errors are also from the OAuth 2.0 [RFC6749] (4.1.2.1. Error Response - "error" parameter). Valid values include: invalid_request, unauthorized_client, access_denied, unsupported_response_type, invalid_scope, server_error, and temporarilly_unavailable. An OPTIONAL error_description suitable for developers may also be returned at the discretion of the DNS Provider. The same considerations as in the synchronous flow apply here.¶

The state value passed into the call MUST be passed back on the query string as state=.¶

The following table describes the values of the URI template for the request for the OAuth consent flow that must be included unless otherwise indicated¶

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

Once authorization has been granted, the Service Provider MUST use the Authorization Code provided to request an Access Token. The OAuth specification recommends that the Authorization Code be a short lived token, and a reasonable recommended setting is ten minutes, however the specific setup would depend on specifics of DNS Provider's implementation. As such this exchange needs to be completed before that time has expired or the process will need to be repeated.¶

This token exchange is typically done via a server to server API call from the Service Provider to the DNS Provider using a POST. When called in this manner a secret is provided along with the Authorization Code.¶

OAuth does allow for retrieving the access token without a secret. This is typically done when the OAuth client is a client application. When onboarding with the DNS Provider this would need to be enabled.¶

When the secret is provided (which is the normal case), care must be taken. A malicious user could create a domain that returns a false _`domainconnect` TXT record, and subsequently a JSON call to their own server for the API end point. By doing so, they could then run Domain Connect on their domain and retrieve the secret.¶

As such the urlAPI used for OAuth by the Service Provider SHOULD be maintained per DNS Provider and not the value retrieved during discovery or other measures have to be implemented to prevent token leakage.¶

The following table describes the POST parameters that MUST be included in the request for the access token unless otherwise indicated. The parameters SHALL be accepted via the query string or the body of the post. This is again particularly important for the client_secret, as passing secrets via a query string is generally frowned upon given that various systems often log URLs.¶

The body of the post is application/json encoded.¶

Upon successful token exchange, the DNS Provider MUST return a response with 4 properties in the body of the response.¶

Once the Service Provider has the access token, they can call the DNS Provider's API to make changes to DNS on the domain by applying and (OPTIONALLY) removing authorized templates. These templates can be applied to the Zone Apex or to any Sub Domain that has been authorized.¶

All calls to this API pass the access token in the Authorization Header of the request to the call to the API. More details can be found in the OAuth specifications, but as an example:¶

While the calls below do not have the same security consideration of passing the secret, it is recommend that the urlAPI be from a stored value vs. the value returned during discovery here as well.¶

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

The primary function of the API is to apply a template to a user domain.¶

While the providerId is implied in the authorization, this is on the path for consistency with the synchronous flows and other APIs. If not matching what was authorized, an error MUST be returned.¶

When applying a template to a domain, it is possible that a conflict may exist with previous settings. While it is recommended that conflicts be detected when the user grants consent, because OAuth is asynchronous it is possible that a new conflict was introduced by the user.¶

While it is up to the DNS Provider to determine what constitutes a conflict (see section on Conflicts below), when one is detected calling this API MUST return an error. This error SHOULD enumerate the conflicting records in a format described below.¶

Because the user often isn't present at the time of this error, it is up the Service Provider to determine how to handle this condition. Some providers may decide to notify the user. Others may decide to apply their template anyway using the "force" parameter. This parameter will bypass error checks for conflicts, and after the call the service will be in its desired state.¶

Calls to apply a template via OAuth require the following parameters posted to the above URL unless otherwise indicated. The DNS Provider MUST accept parameters in query string or body of this post.¶

The body is application/json encoded.¶

An example call is below. In this example, it is contemplated that there are two variables in this template, "IP" and "RANDOMTEXT" which both require values. These variables are passed as name/value pairs.¶

The API MUST validate the access token, and that the domain belongs to the user and is represented by the token being presented. Any errors with variables, conflicting templates, or problems with the state of the domain are returned; otherwise the template is applied.¶

Results of this call can include information indicating success or an error. Errors MUST be 400 status codes, with the following codes defined.¶

When a 409 is returned, the body of the response SHOULD contain details of the conflicting records. If present this MUST be JSON containing the error code, a message suitable for developers, and an array of tuples containing the conflicting records type, host, and data element.¶

As an example:¶

In this example, the Service Provider tried to apply a new hosting template. The domain had an existing service applied for hosting.¶

This call reverts the application of a specific template from a domain.¶

Implementation of this call is OPTIONAL. If not supported a 501 MUST be returned.¶

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

This API allows the removal of a template from a user domain/host using an OAuth request.¶

The provider and service name in the URL MUST match the values provided during authorization.¶

This call MUST validate that the template exists and has been applied to the domain by the Service Provider, or an error response with code 410 SHOULD be returned that the call would have no effect.¶

An example URL might look like:¶

Allowed parameters:¶

The DNS Provider MUST be able to accept these on the query string or in the body of the POST with application/json encoding.¶

Response codes Success, Authorization, and Errors are identical to above with the addition of the 501 code.¶

Like all OAuth flows, the user may revoke the access at any time using UX at the DNS Provider site. As such the Service Provider needs to be aware that their access to the API may be denied.¶

Variable expressions are the parameterized parts of a Domain Connect Template. Each expression contains one variable specifier (which can be either a named variable or a special variable "@") that is replaced with a value during template application.¶

There are three Built-In variables:¶

For example, with the query string "domain=example.com=", %fqdn% in a template would be "example.com", and with "domain=example.com=sub1", %fqdn% in a template would be "sub1.example.com".¶

The @ variable has special meaning, and can be used in the host/name field or in the pointsTo/data field in isolation.¶

For the host/name field it is a shortcut for the value "%fqdn%.". The trailing dot here is equal to the DNS master file notation [RFC1035], which indicates the value is absolute. Without the trailing ".", the value in this field is relative to the [host.]example.com value.¶

For the pointsTo/data field it is a shortcut for for the "%fqdn%". The pointsTo and data files are always absolute for these fields.¶

While templates do allow for variables in a host or name field values, these SHOULD be used very sparingly.¶

As an example, consider setting up hosting for a site. But instead of applying the template to a domain/host, the name of the host is placed as a variable in the template.¶

Such a template might contain an A record of the form:¶

This template could be applied on a domain like example.com with the var set to "sub", "sub1", "sub2", etc.¶

Application of this template would be at the domain level for "example.com". This causes problems for application/re-application of the template, conflict detection, and template removal.¶

Since this template would be applied to the domain only, DNS Providers that maintain template state would remove previous instances of the template before re-application. This means applying this template with var=sub would result in the A record for sub.example.com to be set to the value 192.0.2.2. Later, applying the template on "example.com" with the var=sub2 should remove the old template before setting the new one. sub.example.com would be removed, and sub2.example.com would be set to the value 192.0.2.2.¶

Furthermore, determining conflicts would be impossible when the user is granting consent for asynchronous operations (OAuth). This is because the host would be indeterminate.¶

To solve this problem, templates MUST be considered as scoped to a domain and a host value. For synchronous operations, the host value is specified in the url. For asynchronous operations, permissions are granted for specific host values, whose value is later specified when applying the template.¶

Some templates might want to utilize CNAME or TXT records with host values containing some form of user identification for validation of domain ownership, and these are often passed in variables. In those cases usage of variables in host field value can be applied without risk of issues mentioned above. In all other cases it is RECOMMENDED not to define variables in the host field.¶

As discussed, with variables consideration is necessary to prevent certain styles of phishing attacks.¶

The more static the value in the template record, the more secure the template. When static values are not possible, a carefully crafted link could hijack DNS settings.¶

Mitigations to this are discussed above.¶

Example template:¶

Template applied with domain=example.com and host parameter missing or empty:¶

alternatively¶

Template applied with domain=example.com and host=bar:¶

alternatively¶

SPF stands for Sender Policy Framework specified in [RFC7208]. It is a record that specifies a list of authorized host names and/or IP addresses from which mail can originate from for a given domain name.¶

It manifests itself as a TXT record. The format of which starts with v=spf1 followed by a list of "rules" of what to include/exclude. If a rule passes, the mail is allowed. If it fails, it moves to the next rule. Typical record might appear as:¶

This is an SPF record with two rules. The first rule indicates that the rules for SPF record _policy.exampleprovider.example be included in this record. The second rule is a catch all (all). The default modifier for a rule is pass (+). Other modifiers are hard failure (-), soft failure (~) and neutral (?).¶

Note: A failure in SPF doesn't mean delivery won't happen, however depending on the policies of the receiving system, messages classified with hard failure or soft failure may not be delivered or marked as spam.¶

The use of "all" at the end is pretty common, although some providers mark it as ~ (soft fail) or ? (neutral). The reality is that a good SPF record is tuned based on what services are attached to a domain. Not just one individual service.¶

If only one email sending service were active, the SPF record recommended by the provider is sufficient. But mail from a domain can often come from several different services.¶

A very typical use case might be end user mail and an email newsletter service. Let's look at the SPF records recommended for individual services.¶

Mailer1: v=spf1 include:spf.mailer1.example -all Newsletter1: v=spf1 include:_spf.newsletter.example ~all¶

All of these examples use the include syntax. This is fairly common. The use of all at the end is common, although is often inconsistent with the modifier.¶

If a user installed Mailer1 and Newsletter1, their combined SPF record ought to be something like:¶

We combined the two rules, and in this case picked the least restrictive all modifier.¶

The challenge with SPF 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, Domain Connect advises a fixed modifier "~" advising lower rating of the messages from other sources not specified in SPF. This setup offers a reasonable level of protection of mail delivery, on the other side does not reject the message in case forwarding facility is in place.¶

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 9.3)¶

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 (see: Section 10.5). 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 (both in Synchronous and Asynchronous flow) or return the conflict as an error in the Asynchronous flow unless the force=true parameter is used, effectively removing the existing record.¶

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.¶

Some DNS Providers MAY decide not to support the SPFM record. The following alternative solution would allow general interoperability of the templates for those providers: onboard the templates with SPFM record in variable-compatible form using a regular TXT record with content "v=spf1 %spfRules% ~all", using property essential=OnApply set to avoid removal of the whole template by a conflict.¶

The Public Template Repository is an open accessible location where Service Providers MAY publish their Service Templates in the format specified in this specification. DNS Providers MAY support all of the published templates, just a subset or none of them according to own onboarding policies (see also: Section 11.1).¶

The template format is intended largely for documentation and communication between the DNS Providers and Service Providers, and there are no codified endpoints for creation or modification of these objects. Instead, Domain Connect references a template by ID.¶

As such, DNS Providers may or may not use templates in this format in their internal implementations. By defining a standard template format, it is believed it will make it easier for Service Providers to share their configuration across DNS Providers.¶

The repository of the templates is maintained under https://github.com/Domain-Connect/templates.¶

The file names in this repository MUST be all lower case, including the providerId and serviceId. As a result, while the providerId and serviceId can be mixed case, all `providerIds and serviceIds in this repository MUST be unique when lower case.¶

Templates MUST be named according the following pattern: {providerId}.{serviceId}.json¶

Implementers are responsible for data integrity and MUST use the record type field to validate that variable input meets the criteria for each different data type.¶

Hard-coded host names are the responsibility of the DNS Provider to protect. That is, DNS Providers MUST ensure that host names do not interfere with known values (such as m. or www. or mail.) or internal names that provide critical functionality that is outside the scope of this specification.¶