Domain Connect Protocol - DNS provisioning between Services and DNS Providers

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

Returning a status of 200 without a body indicates the template is supported. The DNS provider may decide to disclose the version of the template in a JSON object with field version (see: version field (Section 8.2) or the full JSON object of deployed template.¶

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

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

There are circumstances where the Service Provider may wish to verify that the template was successfully applied. Without Domain Donnect, this typically involved the Service Provider querying DNS to see if the changes to DNS had been made.¶

This same technique works with Domain Connect, and if necessary can be triggered either manually on the Service Provider site or automatically upon page/window activation in the browser when the browser window for the DNS Provider is closed.¶

When the redirect_uri is used and an error is not present in the URI, the Service Provider can not assume the changes were applied to DNS. While true in most circumstances, users can tamper with or alter the return url in the browser. As such it is recommend that enablement of a service be based on verification of changes to DNS.¶

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 a manual process.¶

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

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

In return, the DNS provider will give the Service Provider a client id and a secret which will be used when requesting tokens. For simplicity the client id should be the same as the providerId.¶

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. Today this includes variables in hosts, and variables in the data portion for certain TXT records. As conflict resolution evolves, this list may grow.¶

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

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 root domain. For example:¶

Upon successful authorization/verification/consent from the user, the DNS Provider will direct the end user's browser to the redirect URI. The authorization code will 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 in the query string parameters for the request for the OAuth consent flow that must be included unless otherwise indicated¶

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

The following table describes the POST parameters that must be included in the request for the access token unless otherwise indicated. The parameters should 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 will 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 root domain or to any sub-domain of the root 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.¶

The primary function of the API is to apply a template to a customer 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 customer 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 will 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. This should 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.¶

This API allows the removal of a template from a customer 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 a warning must be returned that the call would have no effect.¶

An example query string might look like:¶

Allowed parameters:¶

The DNS Provider should 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.¶

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

Note: There are some templates that 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.¶

To support this use case, variables are allowed for the host name. But only in this limited circumstance.¶

To allow for the use of the host name or domain name in templates, the values of %host% and %domain% are available. A third value of %fqdn% is also available. This value is the result of combining the host and domain name with the necessary ".".¶

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

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 customer 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 must NOT be included in templates. Instead, we introduce a new pseudo-record type 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 8.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 9.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 should avoid exact match checking content of TXT SPF record, 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 should 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 10.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 should 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 are responsible for ensuring 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.¶