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.

Service Provider

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.

For the details of the template please refer to the Section 5.2 and Section 5.3 of the Specification.

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 syncRedirectDomain when intended to use redirect_uri parameter in the synchronous flow
  • not specifying syncBlock for a template only intended for asynchronous flow
  • not specifying hostRequired on the templates not applicable to domain APEX (with CNAME on @ host)
  • specifying a TXT record with SPF content (i.e. "v=spf1 ...") instead of using SPFM record type

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 (template1 and 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:

DNS Provider

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.

Discovery

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.

Sign-in/Consent

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 Changes

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.

Testing

To test a DNS Provider implementation it is recommended that the DNS Provider onboard exampleservice.domainconnect.org.template1.json and exampleservice.domainconnect.org.template2.json.

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.