Seamlessly Connecting Domains to Services with Domain Connect 2.0

Domain names are meant to be used. At GoDaddy, we want to empower our customers to build their dreams, and one way we can measure that is by seeing the number of active domains that are out there. Thus, any technology or product that promotes usage is a good thing, as active domains also mean renewals. With so many services available online that need domain names and the Service Providers who offer them (including, for example, Wix and Squarespace for easy website creation or Microsoft’s Office 365 Email offerings) providing an easy way for our customers to attach domain names to services is a huge win.

What’s the Problem?

Often, configuring just the DNS for a domain to be used by these services can get complex, especially for novice users. If I had a dollar for every time I had to explain to a friend or family member what an “A Record” is, and why they need to change it, I’d be flush in ice cream. Simply explaining the reason that a domain needs to be connected is enough to turn a customer off to doing so. Having a simple way for a customer to “connect” a domain name to a service – or even multiple services – without having to worry about the technical aspects is critical. In other words, presenting customers with opportunities to use their domains without exposing them to the confusion of the underlying infrastructure creates a seamless experience and an expectation that things will “just work” every time.

As that expectation becomes mainstream, future developments in the Internet of Things make the implications even more staggering. Imagine if every home cable router came with an easy way to purchase and configure a domain name for the connected home? Or if the current Augmented Reality craze (as seen with Pokémon Go) let you purchase and configure a discoverable domain for your involvement.

Domain Connect 2.0 is a simple way to make the connecting of domains to services as seamless and easy as possible. Through a standardized protocol, implementation at both the Service Provider level as well as the DNS Provider level is consistent and predictable. Further, using templates to accomplish the configuration, DNS providers can ensure that changes have a lesser chance of causing problems or exposing unregulated DNS record manipulation to the outside world. Domain Connect 2.0 is a GoDaddy innovation that has been submitted to the IETF as an open standard, and our implementation, as a DNS Provider is underway.

Domain Connect has been implemented as a simpler synchronous web-based offering already, and the 2.0 version expands the concept with a better authorization strategy as well as an asynchronous REST-ful API. In this blog entry about the new version, the 2.0 is implied. Or, implied val domainConnect: Double = 2.0 as we say in Scala.

So What Are Templates, Anyway?

I called out templates as a benefit, but what are they and why do we use them? Templates solve a critical problem in configuring DNS: unregulated changes to the DNS and a lack of predictability are bad. In the simplest implementation, a protocol for making changes to the DNS could simply say, “tell me what records you want me to create,” and a Service Provider could pass in information that essentially says, “please create an A Record with a host name of ‘www’ and a value of ‘’.” This would work, of course, but could cause some foreseeable problems. What if there were already a host with that name? What if that name was reserved? What if the host name requested was known to cause problems? While these issues still exist in the world of templates, it is easier to know ahead of time that there could be a problem and simply not allow such things in a template. Put another way, templates can have the host names pre-defined and sanitized by both the Service Provider as well as the DNS Provider. In fact, creating a human touch-point in onboarding new templates means that someone can eye-ball them for such problems. Once configured, a template would prevent a Service Provider from making arbitrary changes to DNS, either accidentally or deliberately.

Without templates a Service Provider could request the addition or modification of a DNS record of just about any supported type and restrictions would be difficult, at best. With templates, however, if a DNS provider doesn’t wish to allow a specific (or any) Service Provider to create, say, TXT records, the DNS provider can simply not allow them in any templates. Or they can make per-provider exceptions by simply requiring all templates be reviewed and approved before being made available for use.

Finally, templates allow for predictability. A template suitable to setting records sufficient to point to a web hosting provider could be used consistently across all connecting domains. The chances of a Service Provider slipping in other record changes are reduced to zero since those records simply don’t exist in the “host this domain’s web site” template. Standard templates to accomplish common configurations can even be shared between Service Providers, making DNS Providers’ jobs easier. Overall, everyone gets a predictability and reliability boost.

In other words, templates are never gonna give you up, never gonna let you down, and never gonna run around and desert you. They are never gonna make you cry, never gonna say goodbye and they are never gonna tell a lie and hurt you.

Now that I’ve thoroughly convinced you that templates are awesome, how do we use them? While the internal implementation of templates is left up to the DNS provider, a standard JSON format is specified to make implementation consistent for all providers (and will encourage the sharing I mentioned just now). Indeed, a central repository of templates is noted as an improvement for further versions of the specification. Each template is identified by the provider and given a unique ID comprised of a composite key that identifies the Service Provider and the service being offered. Templates contain information suitable to making DNS changes. This is done through an array of records or actions for the DNS provider to modify or enact. Records note the DNS record type and any values to modify, including the ability to pass in dynamic data (such as an IP address for an A Record). DNS providers can check templates for suitability to purpose or policy before making them available to be used and can work with service providers to refine templates.

And as I mentioned, by making this a standard, we allow Service Providers to re-use templates across multiple DNS providers. Similarly, DNS providers can make a template suitable to a particular purpose available to multiple service providers, saving time and effort.


When a customer wishes to connect a domain, the service provider needs to know who the DNS provider is. To do this, Domain Connect specifies a TXT record be added to the DNS for a domain that specifies a URL that can be called for discovery. The service provider queries the domain for this TXT record (called “DOMAIN_CONNECT”) which, if present, indicates that the domain is served by a DNS provider that supports the Domain Connect protocol. Given the URL, a service provider can call a API endpoint for protocol discovery:

GET v2/{domain}/settings

This will return a JSON structure that contains settings for Domain Connect on the domain name specified, including the provider name and URLs to the two main methods of using Domain Connect. Rather than bloat the DNS with this record, we implement our DNS to inject it in all applicable requests, which also allows for rapid change if necessary without modifying a massive number of DNS zones.

Two Ways to Get It Done – Way the First, the Synchronous Web-Based Flow

Domain Connect provides two ways to get the job of connecting a domain done. The first is via a one-time synchronous web-based HTTP call. This flow is for service providers who want a one-time change to the DNS, and is very similar to how our first version of Domain Connect works. A user identifies the domain they wish to connect and the service provider determines the DNS provider through the discovery process. Once ensuring that the DNS provider supports Domain Connect, as demonstrated previously, the service provider simply calls a known URL and passes in the information necessary to configure a domain to their specification.


So a typical call might look like:

This call indicates that the Service Provider wishes to connect the domain to the service using the template identified by the composite key of the provider ( and the service owned by them (hosting).  In this example, there are two variables in this template, “www” and “m” which both require values (each requires an IP address).  These variables are passed as name/value pairs in the query.

Once on the website of the DNS provider, the customer is asked to authenticate and give permission for the DNS changes to be applied. These changes to the DNS are then done via templates, which ensure that the DNS records to be applied are both already known as well as properly constrained. Once the changes are made or any errors handled, the customer is optionally redirected back to the service provider’s site, providing confirmation that all went well (or an indication of an error is passed).


Way the Second – The Asynchronous API Flow

The second connection method (and new in Version 2) is an OAuth-based flow combined with a RESTful API. This is intended for service providers who want to make DNS changes asynchronously or with use cases that require multiple steps. This flow begins like the synchronous flow in terms of authenticating the customer, but instead of actually applying any DNS changes, the calling service provider is given an access token allowing them to call API functions to apply or remove a DNS change template (or even multiple templates).

This permission gives the service provider the right to apply (or remove) specific templates for a specific domain owned by a specific customer. The service provider may retain this token to apply or remove the template at any time during the token’s lifetime (or until the customer revokes permission, of course).

Service providers who want to use this flow register as an OAuth client with the DNS provider by both giving the templates that will be used as well as callback URLs that specify where customers are redirected after OAuth authorizations are done. Customers are authenticated much like the web-based flow and after giving permission to apply a template to a domain an OAuth authorization token is issued. This token can be used to request or renew a specific access token to perform API calls. The access token is passed in the Authorization Header of API requests.

The API is very simple, and contains endpoints to apply a template, remove a template, or revoke access.

Applying a template is done to a single domain and the domain is part of the authorization. While the provider ID and service ID are also implied in the authorization, these are on the path for consistency with the synchronous flows. If not matching what is in the authorization, an error is returned. The API endpoint should look familiar:

Since this is an API call, HTTP response codes are used to indicate success or error.

Reverting a template is a similar API call, but under the hood there is a bit more going on, in that the DNS provider has to ensure that the template had been previous applied (you can’t revert what you’ve not actually done!) and that doing so won’t break anything else. The specification leaves such implementation details to the individual DNS providers.

Interesting Alternatives

Another possible flow has the initiation of the connection coming from a DNS provider, such as suggesting to a customer that they might want to connect their domain to a partner service provider. In this case it’s entirely possible that the whole process be done at the DNS provider’s site and the service provider either need not be called or perhaps could be called just to notify them of the connection. Some DNS providers are, in essence, also Service Providers as well, and Domain Connect can be used 100% internally, making things much easier for customers to have a consistent experience.

In cases where a template would have dynamic elements, the flow could still be initiated by the DNS provider but then handed off to the service provider to inject the appropriate variables and the flow continue as usual.

Future Developments

While this is a 2.0 version, it is really the first iteration of this specification that connects all the dots for templated connection of domains between service providers and DNS providers. During its development there were many ideas put forth for future development. Once adopted by industry, Domain Connect has the promise to make the configuration of domains much easier for customers, driving innovation and adoption.

Come Innovate With Us

GoDaddy’s Domain Connect 2.0 is a new innovation and we are looking for awesome engineers to help us build out more cool features for our customers. If you are interested, come join us at GoDaddy Careers.