idnits 2.17.1 draft-carney-regext-domainconnect-03.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- == There are 2 instances of lines with non-RFC2606-compliant FQDNs in the document. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year -- The document date (January 18, 2018) is 2284 days in the past. Is this intentional? Checking references for intended status: Informational ---------------------------------------------------------------------------- No issues found here. Summary: 0 errors (**), 0 flaws (~~), 2 warnings (==), 1 comment (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Registration Protocols Extensions A. Blinn 3 Internet-Draft R. Carney 4 Intended status: Informational GoDaddy Inc. 5 Expires: July 22, 2018 January 18, 2018 7 Domain Connect API - Communications between DNS Provider and Services 8 draft-carney-regext-domainconnect-03 10 Abstract 12 This document provides information related to the Domain Connect API 13 that was built to support communications between DNS Providers and 14 Service Providers (hosting, social, email, hardware, etc.). 16 Status of This Memo 18 This Internet-Draft is submitted in full conformance with the 19 provisions of BCP 78 and BCP 79. 21 Internet-Drafts are working documents of the Internet Engineering 22 Task Force (IETF). Note that other groups may also distribute 23 working documents as Internet-Drafts. The list of current Internet- 24 Drafts is at https://datatracker.ietf.org/drafts/current/. 26 Internet-Drafts are draft documents valid for a maximum of six months 27 and may be updated, replaced, or obsoleted by other documents at any 28 time. It is inappropriate to use Internet-Drafts as reference 29 material or to cite them other than as "work in progress." 31 This Internet-Draft will expire on July 22, 2018. 33 Copyright Notice 35 Copyright (c) 2018 IETF Trust and the persons identified as the 36 document authors. All rights reserved. 38 This document is subject to BCP 78 and the IETF Trust's Legal 39 Provisions Relating to IETF Documents 40 (https://trustee.ietf.org/license-info) in effect on the date of 41 publication of this document. Please review these documents 42 carefully, as they describe your rights and restrictions with respect 43 to this document. Code Components extracted from this document must 44 include Simplified BSD License text as described in Section 4.e of 45 the Trust Legal Provisions and are provided without warranty as 46 described in the Simplified BSD License. 48 Table of Contents 50 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2 51 2. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 3 52 3. Definitions . . . . . . . . . . . . . . . . . . . . . . . . . 3 53 4. The API . . . . . . . . . . . . . . . . . . . . . . . . . . . 4 54 4.1. The Synchronous Flow . . . . . . . . . . . . . . . . . . 5 55 4.2. The Asynchorous Flow . . . . . . . . . . . . . . . . . . 6 56 4.3. DNS Provider Initiated Flows . . . . . . . . . . . . . . 6 57 4.4. DNS Provider Discovery . . . . . . . . . . . . . . . . . 7 58 4.5. Domain Connect Details . . . . . . . . . . . . . . . . . 8 59 4.5.1. Synchronous Flow . . . . . . . . . . . . . . . . . . 9 60 4.5.1.1. Query Supported Template . . . . . . . . . . . . 9 61 4.5.1.2. Apply Template . . . . . . . . . . . . . . . . . 9 62 4.5.1.3. Security Considerations . . . . . . . . . . . . . 10 63 4.5.2. Asynchronous Flow: OAuth . . . . . . . . . . . . . . 12 64 4.5.2.1. Getting an Authorization Code . . . . . . . . . . 12 65 4.5.2.2. Requesting an Access Token . . . . . . . . . . . 13 66 4.5.2.3. Making Requests with Access Tokens . . . . . . . 14 67 4.5.2.4. Apply Template to Domain . . . . . . . . . . . . 15 68 4.5.2.5. Revert Template . . . . . . . . . . . . . . . . . 16 69 4.5.2.6. Revoke Access . . . . . . . . . . . . . . . . . . 17 70 4.6. Domain Connect Objects and Templates . . . . . . . . . . 17 71 4.7. Operational and Implementation Considerations . . . . . . 19 72 5. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 23 73 5.1. XML Namespace . . . . . . . . . . . . . . . . . . . . . . 23 74 6. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 23 75 7. Change History . . . . . . . . . . . . . . . . . . . . . . . 23 76 7.1. Change from 02 to 03 . . . . . . . . . . . . . . . . . . 23 77 7.2. Change from 01 to 02 . . . . . . . . . . . . . . . . . . 23 78 7.3. Change from 00 to 01 . . . . . . . . . . . . . . . . . . 23 79 8. Normative References . . . . . . . . . . . . . . . . . . . . 23 80 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 24 82 1. Introduction 84 Configuring a service at a Service Provider to work with a domain has 85 historically been a complex task that is difficult for users. 87 Typically, a customer would try to configure their service by 88 entering their domain name with the Service Provider. The Service 89 Provider then used a number of techniques with mixed reliability to 90 discover the DNS Provider. This might include DNS queries for 91 nameservers, queries to whois, and mapping tables to determine the 92 registrar or the company providing DNS. 94 Once the Service Provider discovered the DNS Provider, they typically 95 gave the customer instructions for proper configuration of DNS. This 96 might include help text, screen shots, or even links to the 97 appropriate tools. 99 Discovery of the DNS Provider in this manner is unreliable, and 100 providing instructions to users would present a number of 101 technologies (DNS record types, TTLs, Hostnames, etc.) and processes 102 they didn't understand. These instructions authored by the Service 103 Provider often quickly become out of date, further confusing the 104 issue for users. 106 The goal of this specificatoin is to create a system where Service 107 Providers can easily enable their applications/services to work with 108 the domain names of their customers. This includes both discovery of 109 the DNS Provider and subsequent modification of DNS. 111 2. Terminology 113 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 114 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 115 document are to be interpreted as described in RFC 2119 [RFC2119]. 117 XML is case sensitive. Unless stated otherwise, XML specifications 118 and examples provided in this document MUST be interpreted in the 119 character case presented in order to develop a conforming 120 implementation. 122 3. Definitions 124 The following definitions are used in this document: 126 o Service Providers - refers to entities that provide products and 127 services attached to domain names. Examples include web hosting 128 providers (such as Wix or SquareSpace), email Service Providers 129 (such as Microsoft or Google) and potentially even hardware 130 manufacturers with DNS-enabled devices including home routers or 131 automation controls (such as Linksys, Nest, and Philips). 132 o DNS Providers - refers to entities that provide DNS services such 133 as registrars (e.g. GoDaddy, 1and1) or standalone DNS services 134 (e.g. CloudFlare). 135 o Customer/User - refers to the end-user of these services. 136 o Templates/Service Templates - refers to a file that describes a 137 set of changes to DNS and domain functionality to enable a 138 specific service. 139 o Root Domain refers to a registered domain (e.g. example.com or 140 example.co.uk) or a delegated zone in DNS. 141 o Sub Domain refers to a sub-domain of a root domain (e.g. 142 sub.example.com or sub.example.co.uk). 144 4. The API 146 The system will be implemented using simple web based interactions 147 and standard authentication protocols. The creation and modification 148 of DNS settings will be done through the application of templates 149 instead of direct manipulation of individual DNS records. 151 Templates are core to this proposal as they describe a service owned 152 by a Service Provider, and contain all of the information necessary 153 to to enable and operate/maintain a service. 155 The individual records may be identified by a group identifier. This 156 allows for the application of templates in different stages. For 157 example, an email provider might first set a TXT record to verify the 158 domain, and later set an MX record to configure email delivery. 159 While done separately, both changes are fundamentally part of the 160 same service. 162 It is important that templates be constrained to an individual 163 service, as later removal of a template would remove all associated 164 records. 166 Templates can also contain variable portions, as often values of data 167 in the template change based on the implementation and/or user of the 168 Service Provider (e.g. the IP address of a service, a customer id, 169 etc). 171 Configuration and onboarding of templates between the DNS Provider 172 and the Service Provider is seen as a manual process. The template 173 is defined by the Service Provider and given to the DNS Provider. 174 Future versions of this specification may allow for an independent 175 repository of templates. For now, the templates are all published at 176 http://domainconnect.org. 178 By basing the protocol on templates instead of DNS Records, several 179 advantages are achieved. The DNS Provider has very explicit 180 knowledge and control on the settings being changed to enable a 181 service. The system is also more secure as templates are tightly 182 controlled and contained. 184 To attach a domain name to a service provided by a Service Provider, 185 the customer would first enter their domain name. 187 Instead of relying on examination of the nameservers and mapping 188 these to DNS Providers, DNS Provider discovery would be handled 189 through simple records in DNS and an API. The Service Provider can 190 query for a specific record in the zone to determine a REST endpoint 191 to initiate the protocol. A Domain Connect compliant DNS Provider 192 would return information about that domain and how to configure it 193 using Domain Connect. 195 For the application of the changes to DNS, there are two use cases. 196 The first is a synchronous web flow, and the second is an 197 asynchronous flow using OAuth and an API. 199 It should be noted that a DNS Provider may choose to only implement 200 one of the flows. As a matter of practice many Service Providers are 201 based on the synchronous flow, with only a handful of them based on 202 the asynchronous OAuth flow. So, many DNS providers may opt to only 203 implement the synchronous flow. 205 It should also be noted that individual services may work with the 206 synchronous flow only, the asynchronous flow only, or with both. 208 4.1. The Synchronous Flow 210 This flow is tailored for the Service Provider that requires a one- 211 time synchronous change to DNS. 213 The user would first enter their domain name at the Service Provider 214 website. 216 After the Service Provider determines the DNS Provider, the Service 217 Provider might display a link to the user indicating that they can 218 "Connect their Domain" to the service. 220 After clicking the link, the user is directed to a browser window on 221 the DNS Provider's site. This is typically in another tab or in a 222 new browser window, but can also be in place navigation with a return 223 url. This link would pass the domain name being modified, the 224 service provider and template being enabled, and any additional 225 parameters needed to configure the service. 227 Once at the DNS Provider site, the user would be asked to 228 authenticate if necessary. 230 After authenticating at the DNS Provider, the DNS Provider would 231 verify the domain name is owned by the user. The DNS Provider would 232 also verify other parameters passed in are valid and would prompt the 233 user to give consent for making the change to DNS. The DNS Provider 234 could also warn the user of services that would be disabled by 235 applying this change to DNS. 237 Assuming the user grants this consent, the DNS changes would be 238 applied. Upon successful application of the DNS changes, the popup 239 window or tab would be closed. If in place the user would be 240 redirected back to the service provider. 242 4.2. The Asynchorous Flow 244 The asynchronous OAuth flow is tailored for the Service Provider that 245 wishes to make changes to DNS asynchronously with respect to the user 246 interaction, or wishes to make multiple or additional changes to DNS 247 over time. 249 The OAuth based authentication and authorization flow begins 250 similarly to the web based synchronous flow. The Service Provider 251 determines the DNS Provider and links to the consent dialog at the 252 DNS Provider where the user signs in, the ownership of the domain is 253 verified, and the consent is granted. 255 However, instead of applying the DNS changes on user consent, OAuth 256 access is granted to the Service Provider. An OAuth access code is 257 generated and handed back to the Service Provider. The Service 258 Provider then requests an access (bearer) token. 260 The permission granted in the OAuth token is a right for the Service 261 Provider to apply a template to the specific domain owned by a 262 specific user. 264 The Service Provider would later call an API that applies this 265 template to the domain, including any necessary parameters along with 266 the access token(s). As in all OAuth flows, access can be revoked by 267 the user at any time. This would be done on the DNS Provider's user 268 experience. 270 If the OAuth flow is used, once a Service Provider has an OAuth token 271 the Domain Connect API becomes available for use. The Domain Connect 272 API is a simple REST service. 274 This REST service allows the application or removal of the changes in 275 the template on a domain name. The domain name, user, and template 276 must be authorized through the OAuth token and corresponding access 277 token. 279 Additional parameters are expected to be passed as name/value pairs 280 on the query string of each API call. 282 4.3. DNS Provider Initiated Flows 284 A DNS Provider may with to expose interesting services that the user 285 could attach to their domain. An example would be suggesting to a 286 user that they might want to connect their domain to a partner 287 Service Provider. 289 If the template for the service is static, it is possible to simply 290 apply the template. 292 However, often the template has some dynamic elements. For this 293 scenario, the DNS Provider need simply call a URL at the Service 294 Provider. The Service Provider can then sign the user in, collect 295 any necessary information, and call the normal web-based flows 296 described above. 298 4.4. DNS Provider Discovery 300 In order to facilitate discovery of the DNS Provider from a domain 301 name, a domain will contain a record in DNS. 303 This record will be a simple TXT record containing a URL used as a 304 prefix for calling a discovery API. This record will be named 305 domainconnect. 307 An example of this record might contain: 309 domainconnect.godaddy.com 311 As a practical matter of implementation, the DNS Provider need not 312 contain a copy of this data in each and every zone. Instead, the DNS 313 Provider needs simply to respond to the DNS query for the 314 domainconnect TXT record with the appropriate data. 316 How this is implemented is up to the DNS Provider. 318 For example, the DNS Provider may not store the data inside a TXT 319 record for the domain, opting instead to put a CNAME in the zone and 320 have the TXT record in the target of the CNAME. 322 Once the URL prefix is discovered, it can be used by the Service 323 Provider to determine the additional settings for using Domain 324 Connect on this domain at the DNS Provider. This is done by calling 325 a REST API. 327 GET 328 https://{domainconnect}/v2/{domain}/settings 330 This will return a JSON structure containing the settings to use for 331 Domain Connect on the domain name (passed in on the path) at the DNS 332 Provider. This JSON structure will contain the following fields: 334 o providerName: The name of the DNS Provider suitable for display on 335 the Service Provider UX. 336 o urlSyncUX: The URL Prefix for linking to the UX elements of Domain 337 Connect for the synchronous flow at the DNS Provider. 338 o urlAsyncUX: The URL Prefix for linking to the UX elements of 339 Domain Connect for the asynchronous flow at the DNS Provider 340 o urlAPI: This is the URL Prefix for the REST API. 341 o width: This is the width of the popup window for granting consent 342 when navigated in a popup. Default value is 750px. 343 o height: This is the height of the popup window for granting 344 consent when navigated in a popup. Default value is 750px. 346 As an example, the JSON returned by this call might contain. 348 { 349 "providerName": "GoDaddy", 350 "urlSyncUX": "https://domainconnect.godaddy.com", 351 "urlAsyncUX": "https://domainconnect.godaddy.com", 352 "urlAPI" : "https://api.domainconnect.godaddy.com", 353 "width" : 750, 354 "height" : 750 355 } 357 If the DNS Provider is not implementing the synchronous flow, the 358 urlSyncUX is not required. Similarly, if the DNS Provider is not 359 implementing the asynchronous flow the urlAsyncUX is not required. 361 4.5. Domain Connect Details 363 Domain Connect contains endpoints in the form of URLs. 365 The first set of endpoints are for the UX that the Service Provider 366 links to. These are for the UX which includes the web-based flow 367 where the user clicks on the link, and the OAuth flow where the user 368 clicks on the link for consent. 370 The second set of endpoints are for the API, largely for the 371 asynchronous OAuth flow via REST. 373 All endpoints begin with a root URL for the DNS Provider such as 374 https://connect.dnsprovider.com/ 376 They may also include any prefix at the discretion of the DNS 377 Provider, for example, https://connect.dnsprovider.com/api/ 379 The root URLs for the UX endpoints and the API endpoints are returned 380 in the JSON payload during DNS Provider discovery. 382 4.5.1. Synchronous Flow 384 4.5.1.1. Query Supported Template 386 GET 387 {urlAPI}/v2/domainTemplates/ 388 providers/{providerId}/services/{serviceId} 390 This URL can be used by the Service Provider to determine if the DNS 391 Provider supports a specific template through the synchronous flow. 393 Returning a status of 200 without a body indicates the template is 394 supported. Returning a status of 404 indicates the template is not 395 supported. 397 4.5.1.2. Apply Template 399 GET 400 {urlAPI}/v2/domainTemplates/ 401 providers/{providerId}/services/{serviceId}/apply?[properties] 403 This is the URL used to apply a template to a domain. It is called 404 from the Service Provider to start the Domain Connect Protocol. 406 This URL should be called in a new browser tab or in a popup browser 407 window. The DNS Provider would sign the user in, verify domain 408 ownership, and ask for confirmation of application of the template. 410 It is also likely that the DNS Provider would warn the user of 411 existing settings that would change and/or services that would be 412 disrupted as part of applying this template. The fidelity of this 413 warning is left to the DNS Provider. 415 Upon completion of the application of the template the DNS Provider 416 would close this tab or window. 418 Parameters/properties passed to this URL include: 420 o domain: This parameter contains the domain name being configured. 421 o name/value pairs: Any variable fields consumed by this template. 422 The name portion of this API call corresponds to the variable(s) 423 specified in the template and the value corresponds to the value 424 that should be used when applying the template. 425 o groupId: This OPTIONAL parameter specifies the group of changes 426 from the template to apply. If no group is specified, all changes 427 are applied. Multiple groups can be specified in comma delimited 428 format. 430 o sig: An optional signature of the query string. See Security 431 Considerations section. 433 An example query string is below: 435 GET 436 https://webconnect.dnsprovider.com/v2/domainTemplates/providers/co 437 olprovider.com/services/hosting/ 438 apply?www=192.168.42.42&m=192.168.42.43&domain=example.com 440 This call indicates that the Service Provider wishes to connect the 441 domain example.com to the service using the template identified by 442 the composite key of the provider (coolprovider.com) and the service 443 owned by them (hosting). In this example, there are two variables in 444 this template, "www" and "m" which both require values (in this case 445 each requires an IP address). These variables are passed as name/ 446 value pairs. 448 4.5.1.3. Security Considerations 450 By applying a template with parameters, there is a security 451 consideration that must be taken into account 453 Consider an email template where the IP address of the MX record is a 454 passed in variable. A bad actor could generate a URL with a bad IP. 455 If an end user is convinced to click on this URL (say in a phishing 456 email), they would land on the DNS Provider site to confirm the 457 change. To the user, this would appear to be a valid request to 458 configure the domain. Yet the IP would be hijacking the service. 460 Not all templates have this problem. But when they do, there are two 461 options. 463 One option would be to not enable the synchronous flow and use 464 asynchronous OAuth. But as will be seen below, OAuth has both a 465 higher implementation burden and requires onboarding between each 466 Service and DNS Provider. 468 As another option, digitally signing the query string will be 469 enabled. The signature will be appended as an additional query 470 string parameter, properly URL encoded and of the form: 472 sig=NLOQQm6ikGC2FlFvFZqIFNCZqlaC4B%2FQDwS6iCwIElMWhXMgRnRE17zhLtdLFie 473 WkyqKa4I%2FOoFaAgd%2FAl%2ByzDd3sM2X1JVF5ELjTlj84jZ4KOEIdnbgkEeO%2FTkY 474 RrPkwcmcHMwc4RuX%2Fqio8vKYxJaKLKeVGpUNSKo7zkq3XIRgyxoLSRKxmlSTHFAz4Lv 475 YXPWo6SHDoVcRvElWj18Um13sSXuX4KhtOLym2yImHpboEi4m2Ziigc%2BNHZE0VvHUR7 476 wZgDaB01z8hFm5ATF%2B8swjandMRf2Lr4Syv4qTxMNT61r62EWFkt5t9nhxMgss6z4pf 477 DVFZ3vYwSJDGuRpEQ%3D%3D 478 The Service Provider can generate this signature using a private key. 479 The DNS Provider can then verify the signature using the public key. 481 key=_dcpubkeyv1 483 This example indicates that the public key can be found by doing a 484 DNS query for a TXT record called _dcpubkeyv1. 486 Since the public key may be greater than 255 characters, multiple TXT 487 records may exist for the DNS TXT query. For a public key of: 489 MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEA1dCqv7JEzUOfbhWKB9mTRsv3O 490 9Vzy1Tz3UQlIDGpnVrTPBJDQTXUhxUMREEOBKo+rOjHZqfYnSmlkgu1dnBEO8bsELQL8G 491 jS4zsjdA53gRk2SDxuzcB4fK+NCDfnRHut5nG0S3U4cq4DuGrMDFVBwxH1duTsqDNgIOO 492 fNTsFcWSVXoSSTqCCMGbj8Vt51umDhWQAj06lf50qP2/ 493 jMNs2G+KTlk3dBHx3wtqYLvdcop1Tk5xBD64BPJ9uwm8KlDNHe+8O+cC9j04Ji8B2K0/ 494 PzAj90xnb8XJy/ 495 EM124hpT9lMgpHKBUvdeurJYweC6oP41gsTf5LrpjnyIy9j5FHPCQIDAQAB 497 There would be several TXT records. The records would be of the 498 form: 500 p=1,a=RS256,d=MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEA1dCqv7JE 501 zUOfbhWKB9mTRsv3O9Vzy1Tz3UQlIDGpnVrTPBJDQTXUhxUMREEOBKo+rOjHZqfYnS 502 mlkgu1dn 503 p=2,a=RS256,d=BEO8bsELQL8GjS4zsjdA53gRk2SDxuzcB4fK+NCDfnRHut5nG0S3 504 U4cq4DuGrMDFVBwxH1duTsqDNgIOOfNTsFcWSVXoSSTqCCMGbj8Vt51umDhWQAj06l 505 f5 506 p=3,a=RS256,d=NCDfnRHut5nG0S3U4cq4DuGrMDFVBwxH1duTsqDNgIOOfNTsFcWS 507 VXoSSTqCCMGbj8Vt51umDhWQAj06lf50qP2/ 508 jMNs2G+KTlk3dBHx3wtqYLvdcop1Tk5xBD64BPJ9 509 p=4,a=RS256,d=uwm8KlDNHe+8O+cC9j04Ji8B2K0/PzAj90xnb8XJy/ 510 EM124hpT9lMgpHKBUvdeurJYweC6oP41gsTf5LrpjnyIy9j5FHPCQIDAQAB 512 Here the public key is broken into four records in DNS, and the data 513 also indicates that the signing algorithm is an RSA Signature with 514 SHA-256. 516 It should be noted that the above data was generated for a query 517 string: 519 a=1&b=2&ip=10.10.10.10&domain=foobar.com 521 Support for signing the query string and verification is optional. 522 Not all services require this level of security, and not all DNS 523 Providers will support this signing for the synchronous flow. 525 There are circumstances where the Service Provider may wish to verify 526 that the template was successfully applied. Without domain connect, 527 this typically involved the Service Provider querying DNS to see if 528 the settings had been applied. 530 This same technique works with Domain Connect, and if necessary can 531 be triggered either manually on the Service Provider site or 532 automatically upon page/window activation in the browser. 534 Automatic notification via callback URLs were considered in earlier 535 drafts, and subsequently dropped due to their lack of reliability and 536 difficulty in getting a consistent implementation across DNS 537 Providers. 539 4.5.2. Asynchronous Flow: OAuth 541 Using the OAuth flow is a more advanced use case, needed by Service 542 Providers that have more complex configurations that may require 543 multiple steps and/or are asynchronous from the user's interaction. 545 Details of an OAuth implementation are beyond the scope of this 546 specification. Instead, an overview of how OAuth fits with Domain 547 Connect is given here. 549 Service providers wishing to use the OAuth flow must register as an 550 OAuth client with the DNS Provider. This is envisioned as a manual 551 process. 553 To register, the Service Provider would provide (in addition to their 554 template) one or more callback URLs that specify where the customer 555 will be redirected after the provider authorization. In return, the 556 DNS Provider will give the Service Provider a client id and secret 557 which will be used when requesting tokens as part of the OAuth 558 process flow. 560 4.5.2.1. Getting an Authorization Code 562 GET 563 {urlAsyncUX}/v2/domainTemplates/ 564 providers/{providerId}/services/{serviceId} 566 To initiate the OAuth flow the Service Provider would link to the DNS 567 Provider to gain consent. 569 This endpoint is similar to the synchronous flow described above, and 570 will handle authenticating the user, verification of domain 571 ownership, and asking for the user's permission to allow the Service 572 Provider to make the specified changes to the domain. Similarly, the 573 DNS Provider will often want to warn the user that (eventual) 574 application of this template might change existing records and/or 575 disrupt existing services attached to the domain. 577 While the variables for the applied template would be provided later, 578 the values of some variables are often necessary in the consent flow 579 to determine conflicts. As such, any variables impacting conflicting 580 records needs to be provided in the consent flow. Today this 581 includes variables in hosts, and variables in the data portion for 582 certain TXT records. As conflict resolution evolves, this list may 583 grow. 585 Upon successful authorization, verification, and consent, the DNS 586 Provider will direct the end user's browser to the redirect URI 587 provided in the request, appending the authorization code as a query 588 parameter of "code". 590 Upon error, the DNS Provider will direct the end user's browser to 591 the redirect URI provided in the request, appending the error code as 592 a query parameter "error". 594 The following describes the values to be included in the query string 595 parameters for the request for the OAuth consent flow. 597 o domain: This parameter contains the domain name being configured. 598 o client_id: This is the client id that was provided by the DNS 599 Provider, to the Service Provider during registration. 600 o redirect_uri: The location to direct the client's browser to upon 601 successful authorization, or upon error. 602 o response_type: OPTIONAL. If included should be the string 'code' 603 to indicate an authorization code is being requested. 604 o scope: This is the name of the template that is being requested. 605 o state: OPTIONAL but recommended. This is a random, unique string 606 passed along to prevent CSRF. It will be returned as a parameter 607 when redirecting to the redirect_url described above. 608 o name/value pairs: Required for fields that impact the conflict 609 detection. This includes variables used in hosts and data in TXT 610 records. 612 4.5.2.2. Requesting an Access Token 614 POST {urlAPI}/v2/OAuth/access_token 616 Once authorization has been granted the Service Provider must use the 617 Authorization Code provided to request an Access Token. The OAuth 618 specification recommends that the Authorization Token be a short 619 lived token, and a reasonable recommended setting is ten minutes. As 620 such this exchange needs to be completed before that time has expired 621 or the process will need to be repeated. 623 This token exchange is done via a server to server API call from the 624 Service Provider to the DNS Provider. 626 The Access Token granted will also have a longer lifespan, but also 627 can expire. To get a new access token, the Refresh Token is used. 629 The following describes the POST parameters to be included in the 630 request. 632 o code: The authorization code that was provided in the previous 633 step when the customer accepted the authorization request, or the 634 refresh_token for a subsequent access token. 635 o redirect_uri: OPTIONAL. If included, needs to be the same 636 redirect uri provided in the previous step, simple for 637 verification. 638 o grant_type: The type of code in the request. Usually the string 639 'authorization_code' or 'refresh_token'. 640 o client_id: This is the client id that was provided by the DNS 641 Provider, to the Service Provider during registration. 642 o client_secret: The secret provided to the Service Provider during 643 registration. 645 Upon successful token exchange, the DNS Provider will return a 646 response with 4 properties in the body of the response. 648 o access_token: The access token to be used when making API 649 requests. 650 o token_type: Always the string "bearer". 651 o expires_in: The number of seconds until the access_token expires. 652 o refresh_token: The token that can be used to request new access 653 tokens when this one has expired. 655 4.5.2.3. Making Requests with Access Tokens 657 Once the Service Provider has the access token, they can call the DNS 658 Provider's API to make change to DNS on behalf of the user. 660 All calls to this API pass the access token in the Authorization 661 Header of the request to the call to the API. More details can be 662 found in the OAuth specifications, but as an example: 664 GET /resource/1 HTTP/1.1 665 Host: example.com 666 Authorization: Bearer mF_9.B5f-4.1JqM 668 4.5.2.4. Apply Template to Domain 670 POST 671 {urlAPI}/v2/domainTemplates/ 672 providers/{providerId}/services/{serviceId}/apply?[properties] 674 The primary function of the API is to apply a template to a customer 675 domain. 677 While the providerId and serviceId are also implied in the 678 authorization, these are on the path for consistency with the 679 synchronous flows. If not matching what is in the authorization, an 680 error would be returned. 682 When applying a template to a domain, it is possible that a conflict 683 may exist with previous settings. While it is recommended that 684 conflicts be detected when the user grants consent, because OAuth is 685 asynchronous it is possible that a new conflict was introduced by the 686 user. 688 While it is up to the DNS Provider to determine what constitutes a 689 conflict (see section on Conflicts below), when one is detected an 690 error will be returned by default. This error will enumerate the 691 conflicting records in a format described below. 693 Because the user isn't present at the time of this error, it is up 694 the Service Provider to determine how to handle this error. Some 695 providers may decide to notify the user. Others may decide to apply 696 their template anyway using the "force" parameter. This parameter 697 will bypass error checks for conflicts, and after the call the 698 service will be in its desired state. 700 Calls to apply a template via OAuth require the following parameters: 702 o domain: This contains the domain name being configured. It must 703 match the domain in the authorization token. 704 o name/value pairs: Any variable fields consumed by this template. 705 The name portion of this API call corresponds to the variable(s) 706 specified in the record and the value corresponds to the value 707 that should be used when applying the template as per the 708 implementation notes. 709 o groupId: This OPTIONAL parameter specifies the group of changes in 710 the template to apply. If omitted, all changes are applied. This 711 can also be a comma separated list of groupIds. 712 o force: This OPTIONAL parameter specifies that the template should 713 be applied independently of any conflicts that may exist on the 714 domain. This can be a value of 0 or 1. 716 An example call is below. In this example, it is contemplated that 717 there are two variables in this template, "www" and "m" which both 718 require values (in this case each requires an IP address). These 719 variables are passed as name/value pairs. 721 POST 722 https://connect.dnsprovider.com/v2/domainTemplates/providers/coolp 723 rovider.com/services/hosting/ 724 apply?www=192.168.42.42&m=192.168.42.43&force=1 726 The API must validate the access token for the Service Provider and 727 that the domain belongs to the customer and is represented by the 728 token being presented. With these checks passing, the template may 729 be applied to the domain after verifying that doing so would not 730 cause an error condition, either because of problems with required 731 variables or the current state of the domain itself (for example, 732 already having a conflicting template applied). 734 Results of this call can include information indicating success, or 735 an error. Errors will be 400 status codes, with the following codes 736 defined. 738 o Success (20*): A response of an http status code of 204 indicates 739 that call was successful and the template applied. Note that any 740 200 level code should be considered a success. 741 o Unauthorized (401): A response of a 401 indicates that caller is 742 not authorized to make this call. This can be because the token 743 was revoked, or other access issues. 744 o Error (404,422): This indicates something wrong with the request 745 itself, such as bad parameters. 746 o Failed (409): This indicates that the call was good, and the 747 caller authorized, but the change could not be applied due to a 748 conflicting template or a domain state that prevents updates. 749 Errors due to conflicts will only be returned when force is not 750 equal to 1. 752 When a 409 is returned, the body of the response will contain details 753 of the error. This will be JSON containing the error code, a message 754 suitable for developers, and an array of tuples containing the 755 conflicting records type, host, and data element. 757 4.5.2.5. Revert Template 759 POST 760 {urlAPI}/v2/domainTemplates/ 761 providers/{providerId}/services/{serviceId}/revert?domain={domain} 763 This API allows the removal of a template from a customer domain 764 using an OAuth request. 766 The provider and service name in the authorizatoin must match the 767 values in the URL. So must the domain name on the query string. 769 This call must validate that the template requested exists and has 770 been applied to the domain by the Service Provider or a warning must 771 be returned that the call would have no effect. This call must 772 validate that there is a valid authorization token for the domain 773 passed in or an error condition must be reported. 775 An example query string might look like: 777 POST 778 https://connect.dnsprovider.com/v2/domainTemplates/providers/coolp 779 rovider.com/services/hosting/revert?domain=example.com 781 Response codes are identical to above. 783 4.5.2.6. Revoke Access 785 Like all OAuth flows, the user can revoke the access at any time 786 using UX at the DNS Provider site. So the Service Provider needs to 787 be aware that their access to the API may be denied. 789 4.6. Domain Connect Objects and Templates 791 Templates are not versioned. Instead, if a breaking change is made 792 to a template it is recommended that a new template be created. 793 While on the surface versioning looks appealing, the reality is that 794 the settings in a template rarely change. This is because a 795 successful service will have many customers with settings in their 796 DNS, some applied by templates using this protocol, and some manually 797 applied. As such changes to the template need to be done in a manner 798 that accounts for existing customers. 800 A template is defined as a standard JSON data structure containing 801 the following data: 803 o providerId: The unique identifier of the Service Provider that 804 created this template. This is used in the URLs to identify the 805 Service Provider. To ensure non-coordinated uniqueness, this 806 would be the domain name of the Service Provider. 807 o providerName: The name of the Service Provider. This will be 808 displayed to the user. 809 o templateId: The name or identifier of the template. This is used 810 in URLs to identify the template. 812 o templateName: The friendly name of this service. This will be 813 displayed to the user. 814 o logoUrl: A graphical logo for use in any web-based flow. This is 815 a URL to a graphical logo sufficient for retrieval. 816 o description: A textual description of what this template attempts 817 to do. This is meant to assist integrators, and therefore should 818 not be displayed to the user. 819 o syncBlock: Indicates that the synchronous protocol should not be 820 enabled for this template. 821 o synchPubKeyDomain: When present, indicates that calls to apply a 822 template synchronously will be digitally signed. This element 823 contains the domain name for querying a TXT record from DNS. 824 o launchUrl: OPTIONAL. A URL suitable for a DNS Provider to call to 825 initiate the execution of this template. This allows the flow to 826 begin with the DNS Provider as described above. 827 o records: A list of records for the template. 829 Each template record is an entry that contains a type and several 830 optional parameters based on the value. 832 For all entries of a record template other than "type" and "groupId", 833 the value can contain variables denoted by %%. These 834 are the values substituted at runtime when writing into DNS. 836 It should be noted that as a best practice, the variable should be 837 equal to the portion of the values in the template that change as 838 little as possible. 840 For example, say a Service Provider requires a CNAME of one of three 841 values for their users: s01.example.com, s02.example.com, and 842 s03.example.com. 844 The value in the template could simply contain %servercluster%, and 845 the fully qualified string passed in. Alternatively, the value in 846 the template could contain s%var%.example.com. By placing more fixed 847 data into the template, the data is more constrained. 849 Each record will contain the following elements: 851 o type: Describes the type of record in DNS, or the operation 852 impacting DNS. Valid values include: A, AAAA, CNAME, MX, TXT, 853 SRV, NS, APEXCNAME, REDIR301, or REDIR302. 854 o groupId: This OPTIONAL parameter identifies the group the record 855 belongs to when applying changes. 856 o host: The host for A, AAAA, CNAME, TXT, and MX values. This is 857 the hostname in DNS. 858 o pointsTo: The pointsTo location for A, AAAA, CNAME and MX records. 860 o ttl: This is the time-to-live for the record in DNS. Valid for A, 861 AAAA, CNAME, TXT, MX, and SRV records. 862 o data: This is the data for a TXT record in DNS. 863 o priority: This is the priority for an MX or SRV record in DNS. 864 o weight: This is the weight for the SRV record. 865 o port: This is the port for the SRV record. 866 o protocol: This is the protocol for the SRV record. 867 o service: This is the protocol for the SRV record. 869 4.7. Operational and Implementation Considerations 871 The DNS Provider is responsible for handling of the conflicts with 872 records already existing in the DNS Zone. This includes detection of 873 conflicts, removing conflicts when a new template is applied, and 874 merging records when appropriate. 876 For example, if the application of a template through the web based 877 flow would interfere with previously set DNS records (either through 878 another template or manual settings), it is envisioned that the user 879 would be asked to confirm the clearing of the previously set 880 template. If it would interfere with DNS records accessible through 881 a previously issued OAuth flow, the provider could revoke the 882 previously issued token. 884 Similarly, when granting an OAuth token that interferes with a 885 previously issued OAuth token, access to the old token could 886 automatically be revoked. 888 Manual changes to DNS through the DNS Provider could have appropriate 889 warnings in place to prevent unwanted changes; with overrides being 890 possible and removing conflicting templates. 892 The behavior of these interactions is left to the sophistication of 893 the DNS Provider. However, a general recommendation is to ensure 894 that a newly configured service works correctly. 896 A proposing handling of records is as follows (if not otherwise 897 specified, conflicts occur if the records have the same name): 899 Replace records of the same type for A, AAAA, MX, CNAME, 900 APEXCNAME, SRV. If the template specifies an A or AAAA, the 901 respective AAAA or A record should be removed to avoid IPv4 and 902 IPv6 pointing to different services 903 Append to the existing records of the same type for TXT 904 Replace any record for CNAME 905 Remove any CNAME record existing at the same or parent level to 906 any records added by the template 908 Additional record types and/or extensions to records in the template 909 can be implemented on a per DNS Provider basis. However, care should 910 be taken when defining extensions so as to not conflict with other 911 protocols and standards. Certain record names are reserved for use 912 in DNS for protocols like DNSSEC (DNSKEY, RRSIG) at the registry 913 level. 915 Defining these optional extensions in an open manner as part of this 916 specification is highly recommended. The following are the initial 917 optional extensions a DNS Provider/Service Provider may support. 919 Some Service Providers desire the behavior of a CNAME record, but in 920 the apex record. This would allow for an A Record at the root of the 921 domain but dynamically determined at runtime. 923 The recommended record type for DNS Providers that wish to support 924 this an APEXCNAME record. Additional fields included with this 925 record would include pointsTo and TTL. 927 Defining a standard for such functionality in DNS is beyond the scope 928 of this specification. But for DNS Providers that support this 929 functionality, using the same record type name across DNS Providers 930 allows template reuse. 932 Some Service Providers desire a redirection service associated with 933 the A Record. A typical example is a service that requires a 934 redirect of the domain (e.g. example.com) to the www variant 935 (www.example.com). The www would often contain a CNAME. 937 Since implementation of a redirection service is typically simple, it 938 is recommended that service providers implement redirection on their 939 own. But for DNS Providers that have a redirection service, 940 supporting simple templates with this functionality may be desired. 942 While technically not a "record" in DNS, when supporting this 943 optional functionality, it is recommended that this be implemented 944 using two new record types. 946 REDIR301 and REDIR302 would implement 301 and 302 redirects 947 respectively. Associated with this record would be a single field 948 called the "target", containing the target domain of the redirect. 950 Several service providers have asked for functionality supporting an 951 update to the nameserver records at the registrar associated with the 952 domain. 954 This functionality is again deemed as optional and up to the DNS 955 Provider to determine if they desire to support this functionality. 957 When implementing this, two records will be provided. NS1 and NS2, 958 each containing a pointsTo argument. 960 Requests have also been made to allow for updates to the DS record 961 for DNSSEC. This record is required at the registry to enable 962 DNSSEC, but can only be written by the registrar. 964 Note that the registrar may or may not be the DNS Provider, but in 965 this case the implementation of updates of the DS record into the 966 registry would be handled exclusively by the registrar. 968 For DNS Providers that support this record, the record type should be 969 DS. Values will be keyTag, algorithm, digestType, and digest. 971 Variables in templates that are hard-coded host names are the 972 responsibility of the DNS Provider to protect. That is, DNS 973 Providers are responsible for ensuring that host names do not 974 interfere with known values (such as m. or www. or mail.) or internal 975 names that provide critical functionality that is outside the scope 976 of this specification. 978 This template format is intended for internal use by a DNS Provider 979 and there are no codified API endpoints for creation or modification 980 of these objects. API endpoints do not use this object directly. 981 Instead, API endpoints reference a template by ID and then provide 982 key/value pairs that match any variable values in these record 983 objects. 985 However, by defining a standard template format it is believed it 986 will make it easier for Service Providers to share their provisioning 987 across DNS Providers. Further revisions of this specification may 988 include a repository for publishing and consuming these templates. 989 For now, templates are maintained at http://domainconnect.org. 991 Implementers are responsible for data integrity and should use the 992 record type field to validate that variable input meets the criteria 993 for each different data type. 995 Some considerations are necessary for configuring a domain 996 (example.com) vs. a sub-domain (sub.example.com) for a Service. 998 The DNS Provider will only implement the _domainconnect record at the 999 domain level. This means that during discovery, the Service Provider 1000 would need to call the root domain for this information. 1002 The DNS Provider should support configuring services on domains vs. 1003 sub-domains. 1005 If the template is identical for the root and for the sub-domain, the 1006 Service Provider simply needs to call domain connect with the fully 1007 qualified domain name. Here passing in sub.example.com vs. 1008 example.com to the domain connect flow is all that is necessary. 1010 If there are differences, two templates would be created and the 1011 Service Provider would invoke the appropriate version. 1013 It is also highly recommended that this approach be taken, vs. 1014 variables for host names passed into the template. 1016 Example Records: Single static host record 1018 Consider a template for setting a single host record. The records 1019 section of the template would have a single record of type "A" and 1020 could have a value of: 1022 [{ 1023 ''type'': ''A'', 1024 ''host'': ''www'', 1025 ''pointsTo'': ''192.168.1.1'', 1026 ''ttl'': 600 1027 }] 1029 This would have no variable substitution and the application of this 1030 template to a domain would simply set the host name "www" to the IP 1031 address "192.168.1.1" 1033 Example Records: Single variable host record for A 1035 In the case of a template for setting a single host record from a 1036 variable, the template would have a single record of type "A" and 1037 could have a value of: 1039 [{ 1040 ''type'': ''A'', 1041 ''host'': ''@'', 1042 ''pointsTo'': ''192.168.1.%srv%'', 1043 ''ttl'': 600 1044 }] 1046 A query string with a key/value pair of 1048 srv=8 1050 would cause the application of this template to a domain to set the 1051 host name for the apex A record to the IP address "192.168.1.8" with 1052 a TTL of 600. 1054 5. IANA Considerations 1056 5.1. XML Namespace 1058 This document uses URNs to describe XML namespaces and XML schemas 1059 conforming to a registry mechanism described in [RFC3688]. The 1060 following URI assignment is requested of IANA: 1062 URI: ietf:params:xml:ns:validate-1.0 1064 Registrant Contact: See the "Author's Address" section of this 1065 document. 1067 6. Acknowledgements 1069 The authors wish to thank the following persons for their feedback 1070 and suggestions: 1072 o Chris Ambler of GoDaddy Inc. 1073 o Jody Kolker of GoDaddy Inc. 1075 7. Change History 1077 7.1. Change from 02 to 03 1079 Added width/height JSON values returned by DNS Provider Discovery. 1080 Corrected text of GET method for getting the authorization token. 1081 Added clarifying text to Group ID description parameter of the apply 1082 template POST method. Quite a few minor edits and clarifications 1083 that were found during implementation, especially in the 1084 Implementation Considerations section. 1086 7.2. Change from 01 to 02 1088 Added new GET method for Service Providers to determine if the DNS 1089 Provider supports a specific template. Some other minor edits for 1090 clarification. 1092 7.3. Change from 00 to 01 1094 Minor edits and clarifications found during implementation. 1096 8. Normative References 1098 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 1099 Requirement Levels", BCP 14, RFC 2119, 1100 DOI 10.17487/RFC2119, March 1997, 1101 . 1103 [RFC3688] Mealling, M., "The IETF XML Registry", BCP 81, RFC 3688, 1104 DOI 10.17487/RFC3688, January 2004, 1105 . 1107 Authors' Addresses 1109 Arnold Blinn 1110 GoDaddy Inc. 1111 14455 N. Hayden Rd. #219 1112 Scottsdale, AZ 85260 1113 US 1115 Email: arnoldb@godaddy.com 1116 URI: http://www.godaddy.com 1118 Roger Carney 1119 GoDaddy Inc. 1120 14455 N. Hayden Rd. #219 1121 Scottsdale, AZ 85260 1122 US 1124 Email: rcarney@godaddy.com 1125 URI: http://www.godaddy.com