Below is information to get started as a Service Provider or a DNS Provider. If you need more help, contact us via the contact form or on the Slack channel. The community is more than willing to help.
Oh, and don’t forget to give us your logo so we can list it on this website.
To start as a service provider you’ll need to define and publish your template.
Synchronous vs. Asynchronous
As a protocol, domain connect has a synchronous flow and an asynchronous flow using oAuth. It is highly recommended that people new to Domain Connect start with the synchronous flow. It is easier to implement and understand, and since a very limited number of DNS Providers support the asynchronous flow you’ll get more coverage.
Define and Publish Template
The first step is to define and publish your template. The best approach is to copy and edit one of the existing templates at https://github.com/domain-connect/templates. Pick a service similar to yours.
The records in your template should be as static as possible. This keeps your template more secure.
The name of your template should match your providerId/serviceId. For example, if the company “acme.com” was defining a service for “hosting”, their template would be called acme.com.hosting.json.
To publish your template, you’ll want to fork the templates repository and submit a Pull Request through github.com. The Domain Connect community will review your template and make recommendations. More details about the workflow can be found here.
Some common feedback:
- Misnamed templates
- Variables too broad in scope (i.e. possible to be misused to set any arbitrary record and conflict with other template). Too broad scope example:
@ TXT "%verification%". Better usage:
@ TXT "foo-verification=%verification%".
- Variables as a host name. These are highly discouraged unless explicitly needed
- Not using digital signatures (or
warnPhishing) on “insecure templates”
- not specifying
syncRedirectDomainwhen intended to use
redirect_uriparameter in the synchronous flow
- not specifying
syncBlockfor a template only intended for asynchronous flow
- not specifying
hostRequiredon the templates not applicable to domain APEX (with
- specifying a
TXTrecord with SPF content (i.e.
"v=spf1 ...") instead of using
Signing (and Testing) Templates
Speaking of digital signatures, this is one of the trickier parts of creating a valid template. For security purposes, it is highly recommended that synchronously applied templates with certain variables be digitally signed by the service provider. To facilitate the testing of digital signatures on a template, there are tools at https://exampleservice.domainconnect.org/sig to test and verify signatures.
Onboard with DNS Providers
Once your template is defined and published on github, you’ll need to onboard your template with the different DNS Providers. At the moment, this is done by contacting them. Contact information can be found on the DNS Provider page. Some DNS Providers may require contractual terms and further template review before publishing your template.
Implement the Protocol
After your template is live with one of the DNS Providers, you’ll need to implement Domain Connect into your flow. Fortunately there is an example of this at https://exampleservice.domainconnect.org/simple. This website implements a Service Provider
exampleservice.domainconnect.org with two templates (
template2). Template 1 does not require signatures, template 2 requires them.
The full source code for this website is available at https://github.com/domain-connect/exampleservice.
There are also some ready to use libraries available as Open Source:
- Python – https://github.com/Domain-Connect/domainconnect_python
- PHP – https://github.com/gaalferov/ext-domain-connect
To get started as a DNS Provider, you’ll need to implement the various end points of the Domain Connect protocol. This includes the methods for discovery, signing the user in and gaining consent, and applying templates.
Synchronous vs. Asynchronous
It is recommended that a DNS Provider new to the protocol start with the synchronous flow, potentially adding asynchronous oAuth at a later time.
DNS Providers need to support the discovery protocol. This means responding to the
_domainconnect TXT records in the relevant zones, implementing the API to return the JSON structure with the endpoints for the DNS Provider, and supporting the API to query if templates are supported. These are all unauthenticated endpoints or APIs.
The user will ultimately link to the DNS Provider UX. This UX will need to sign the user in, verify domain ownership, display any conflicting DNS data, and gain consent from the user.
At this point if part of an asynchronous flow, the oauth response would be generated. For the synchronous flow the DNS changes would be applied directly.
Applying the changes to the zone file is a bit complex. Variables need to be resolved, conflicts detected, records added, records deleted, and even some records merged.
To aid with this a library is provided on https://github.com/domain-connect/DomainConnectApplyZone. This library will take the contents of a zone file, a template, and variable values and return the set of changes required to the underlying zone.
The DNS Provider needs to format the data properly before calling this library, and process the changes based on the output, but the tricky work is handled for the DNS Provider.
To test a DNS Provider implementation it is recommended that the DNS Provider onboard
With a compliant implementation synchronous application of these two templates should work with no modifications. If the DNS Provider wishes to test their asynchronous implementation, please contact us via the contact form or ask in the Slack channel and we’ll on board the example service as a an oAuth partner.
Onboard Service Providers
Once your implementation is done you may want to onboard as many Service Providers as possible. Some of them will work out of the box after you onboard their template, some others would need to be contacted to enable your provider or to onboard an oAuth client. At the moment, this is done by contacting them. Contact information can be found on the Service Provider page.