.svg){kind=small}
What are you searching for?
Every user who owns domain control sooner or later has a question about purchasing a domain from a third-party domain hosting service provider. Setting up work with a domain name for mail or web hosting is a difficult task, since it requires knowledge about the DNS (Domain Name System), as well as changing the DNS settings. Today I want to talk about what the Domain Connect Protocol is, what are the benefits of domain connect protocol, how to create connect protocol and how to use it correctly.
My story of using Domain Connect Protocol started when my team was tasked with a feature to make a simple web page builder. When people use web page builders, they sometimes come with their own domains that they want to link to their new website. I had to explore the UX of domain connection among existing web page builders like Wix, Wordpress, Squarespace and Shopify .
A common pattern is that there is
1. A manual approach that is presented in UI as a set of actions for users to perform at their domain registrar panel (add NS records, A records and/or CNAMErecords) and then.
2. For select few domain registrars (e.g Wordpress and Squarespace for GoDaddy and 1&1 IONOS) there is an automated approach where you have to input your domain name and then log in to the registrar and confirm the action (adding NS records, A records and/or CNAME records).
The automated flow UX looks very similar to signing up/signing in with Google or Facebook or Apple ID - that is to an OAuth protocol. This flow is implemented using the Domain Connect protocol.
According to the domain connect protocol documentation, Domain Connect is an industry standard that helps the user to simplify the configuration of DNS significantly, which operates on the side of an independent DNS provider. This protocol makes it possible to make all the settings without a deep understanding of the entire complexity of the DNS. Domain Protocol is a non-commercial open-source project supported by the engineering community of several companies.
In this paragraph, we will look at how to use domain connect protocol. So, this protocol involves two parties - DNS providers and hosting domain service providers. DNS providers run DNS for a domain, and service providers, in turn, provide services and applications attached to domains. Usually, the whole process has 3 main steps.
1. The user is trying to set up a service with a service provider.
2. In turn, the service provider contacts the DNS provider. This appeal can be in the form of an attempt to find out who the registrar/owner of the DNS by means of a DNS request for name servers.
3. The service provider then connects the DNS provider with the domain name server and provides the user with instructions on how to correctly configure the DNS. This tutorial usually includes screenshots, help text, and links to the tools you need.
During this process, the user gets into the main difficulties, as they are faced with a number of things that they do not understand. DNS record types, TTLs, HostNames, etc. are all confusing to many users. In addition, most of the instructions provided by the service provider have long since lost their relevance.
In order to avoid the above difficulties, the Domain Connect protocol was created. The protocol is an interface that is understandable for the average user, thus isolating the user from the DNS setup and its complexities. By implementing a standard interaction between all Service Providers and all DNS Providers it eliminates the necessity for each relationship between a Service Provider and DNS Provider to be customized.
The basic idea and roles are similar to the ones in OAuth protocol. In OAuth authorization server authenticates resource owner and issues tokens that can be later used by client to make authorized requests to resource server to access resource owner '''s resources and make changes to them. [1] In Domain Connect DNS Provider authenticates Customer/User and authorized Service Provider to make changes described in a Service Template.
So the correspondence table looks like this:
| Domain Connect | OAuth |
|---|---|
| DNS Provider | authorization server |
| DNS Provider* | resource server |
| Service Provider | client |
| Customer/User | resource owner |
| Service Template | resource server API** |
* DNS Provider acts as both authorization server and resource server. It authenticates the domain owner and also it manages the domain resource.
** OAuth issued token usually allows clients to access resource servers through API for Domain Connect. In Domain Connect the changes are described in one or more Service Templates that have to be registered by the DNS provider.
The Asynchronous Flow is basically the same as OAuth protocol where DNS Provider authenticates Customer/User and issues tokens that can be later used by Service Provider to make authorized requests to DNS Provider’s API. The API is uniform and defined by a Domain Connect Spec.
While I think that The Asynchronous Flow is cool, I decided to ditch it because
1. We had a simple flow in mind that is easily implemented with The Synchronous Flow.
2. The Spec version 2.2 includes a warning that some DNS Providers might not implement the Asynchronous Flow.
The Getting Started article on the Domain Connect website gives all the details for a successful application, so I'll try to give a step-by-step overview of the process instead. Also I'll provide some details not defined by the spec and not described by the Getting Started tutorial.
First things first, you need to get acquainted with the spec and compose a template (or templates) that will describe an action that you wish to perform with User's DNS Zone.
Common use cases for templates that I noticed while reviewing the Repository include:
1. Creating A records to point User domain or subdomain to Service Provider's IP address.
2. Creating CNAME records to point User subdomain to Service Provider's IP address or Service Provider's domain. Or simply configuring a "www" subdomain that would point to the apex A record.
3. Creating TXT records with unique ids to validate domain ownership.
4. Creating NS records to redirect DNS queries to Service Provider's nameservers.
5. Creating MX records to point to Service Provider's mail servers.
I was only interested in the first three use cases. So I created two templates.
1. The first one would create an A record and a "www" CNAME record. Later pointing to the former. NOTE: You can parametrize the subdomain of the record and specify it at the time of template application through the protocol.
2. The second one would simply create a TXT record with a unique id that is also provided at the time of template application.
Template
The name of a template file should be formatted like this ${providerId}.${serviceId}.json . So for this example the file name is web-app-builder-domain.com.link-domain.json
(I'm adding comments with quotes from spec about the fields to the JSON, but I wanted to mention just in case that comments are not a part of the JSON spec and make a JSON invalid.)
{
"providerId": "web-builder-app.com", // The unique identifier of the Service Provider that created this template. *
"providerName": "Web App Builder App", // The name of the Service Provider suitable for display.
"serviceId": "link-domain", // The name or identifier of the template. *
"serviceName": "Link Domain", // The name of the service suitable for display to the user.
"version": 2,
"logoUrl": "https://web-builder-app.s3.amazonaws.com/assets/images/logo.png",
"description": "Enables a domain to work with Web Builder App",
"variableDescription": "ipaddr - ip address of the Web Builder App server that handles user pages",
"syncRedirectDomain": "dc-redirect.web-builder-app.com",
"syncPubKeyDomain": "web-builder-app.com",
"records": [
{
"type": "A",
"host": "@",
"pointsTo": "%ipaddr%",
"ttl": 600
},
{
"type": "CNAME",
"host": "www",
"pointsTo": "@",
"ttl": 600
}
]
}
* In this context providerId means "Service Provider ID" (a domain of your web app) and serviceId means a "separate service this Service Provider provides". When this template is applied using a URL with this template
${urlSyncUX}/v2/domainTemplates/providers/${providerId}/services/${serviceId}/apply?domain=${userDomain}&ipaddr=${ipAddr}&host=${hostName}
that is instantiated for example like this for GoDaddy and the example template
https://dcc.godaddy.com/manage/v2/domainTemplates/providers/web-builder-app.com/services/link-domain/apply?domain=user-domain.com&ipaddr=${ipAddr}&host=${hostName}
it will create 2 records in the User's DNS Zone: 1. An A record pointing to the ipAddr 2. A CNAME record pointing to the hostName
Now ${hostName}.user-domain.com will resolve to ${ipAddr} through an A record and www.${hostName}.user-domain.com will resolve to ${hostName}.user-domain.com through a CNAME record.
Then you have to create a pull request to the Domain Connect Repository [4] with your template (or templates).
My pull request was quickly reviewed and accepted.
Then you have to contact DNS Providers from this list - https://www.domainconnect.org/dns-providers/.
Out of the 11 DNS Providers that should have their implementation live only 4 responded. One of them told me that we'll have to wait for their release in the future and unfortunately they don't have an ETA. The ones who left were GoDaddy, 1&1 IONOS and Google Domains. Which is still a good list of providers!
They responded with the contract details that the legal department would have to review and sign.
NOTE: In one case there was a surprisingly high template reapplication fee. That is if you wanted to change a template admitted by the DNS Provider, you'll have to pay for this. Which prompted me to review other templates in the Repository to learn about other common use cases.
They have a great reference implementation by this link - which was a very helpful resource for me even though I never coded a web server in Python. The web server by the link is hosted at https://exampleservice.domainconnect.org.
Overview of implementation:
The reference implementation is simple and easy to follow and very useful for clarifying the details!
When our customers presented us with the requirement to automate the DNS record creation flow, my first thought was that this is very likely not possible. My reference was that DNS is a very old technology and it is highly unlikely that the OAuth-like flow is a part of it. But I didn't know much about DNS at the time, so I decided to go with the "I'll have to take a closer look" answer. I'm happy Domain Connect exists. It is a great initiative that will make the Internet a better and more friendly place. Hope that information about the domain connect protocol advantages, the process of creating the domain connect protocol, and the process of using of domain connect protocol was useful for you:)
