idnits 2.17.1 draft-carney-regext-domainconnect-02.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 : ---------------------------------------------------------------------------- ** The document seems to lack a Security Considerations section. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year -- The document date (February 1, 2017) is 2640 days in the past. Is this intentional? Checking references for intended status: Informational ---------------------------------------------------------------------------- No issues found here. Summary: 1 error (**), 0 flaws (~~), 1 warning (==), 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: August 5, 2017 February 1, 2017 7 Domain Connect API - Communications between DNS Provider and Services 8 draft-carney-regext-domainconnect-02 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 http://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 August 5, 2017. 33 Copyright Notice 35 Copyright (c) 2017 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 (http://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 . . . . . . . . . . . . . . . . . . . . . . . . . . . 3 54 4.1. Web-Based Authentication, Authorization & Template Action 55 Flow . . . . . . . . . . . . . . . . . . . . . . . . . . 5 56 4.2. OAuth Based Authentication and Authorization Flow . . . . 5 57 4.3. DNS Provider Initiated Flows . . . . . . . . . . . . . . 6 58 4.4. DNS Provider Discovery . . . . . . . . . . . . . . . . . 7 59 4.5. Domain Connect Endpoints . . . . . . . . . . . . . . . . 8 60 4.5.1. Web Based Flow . . . . . . . . . . . . . . . . . . . 8 61 4.5.1.1. Web Based Flow: Template . . . . . . . . . . . . 8 62 4.5.1.2. Web Based Flow: Initiation . . . . . . . . . . . 8 63 4.5.2. OAuth Flow . . . . . . . . . . . . . . . . . . . . . 10 64 4.5.2.1. Getting an Authorization Token . . . . . . . . . 10 65 4.5.2.2. Requesting an Access Token . . . . . . . . . . . 11 66 4.5.2.3. Making Requests with Access Tokens . . . . . . . 12 67 4.5.2.4. Apply Template to Domain . . . . . . . . . . . . 12 68 4.5.2.5. Revert Template . . . . . . . . . . . . . . . . . 13 69 4.5.2.6. Revoke Access . . . . . . . . . . . . . . . . . . 14 70 4.6. Domain Connect Objects and Templates . . . . . . . . . . 14 71 4.7. Implementation Notes . . . . . . . . . . . . . . . . . . 16 72 4.8. Operational and Implementation Considerations . . . . . . 19 73 5. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 20 74 6. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 20 75 7. Change History . . . . . . . . . . . . . . . . . . . . . . . 20 76 7.1. Change from 01 to 02 . . . . . . . . . . . . . . . . . . 20 77 7.2. Change from 00 to 01 . . . . . . . . . . . . . . . . . . 20 78 8. Normative References . . . . . . . . . . . . . . . . . . . . 20 79 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 21 81 1. Introduction 83 Configuring a service at a Service Provider to work with a domain is 84 a complex task and is difficult for users. 86 Typically a customer will try to configure their service by entering 87 their domain name with the Service Provider. The Service Provider 88 then uses a number of techniques to discover the DNS Provider. This 89 might include DNS queries to determine the registrar and/or the 90 nameserver providing DNS. 92 Once the Service Provider discovers the DNS Provider, they typically 93 give the customer instructions for proper configuration of DNS. This 94 might include help text, screen shots, or even links to the 95 appropriate tools. 97 This often presents a number of technologies or processes to the user 98 that they may not understand. DNS record types, TTLs, Hostnames, 99 etc. are all confusing to many users. Instructions authored by the 100 Service Provider may also be out of date, further confusing the 101 issue. 103 The goal of the protocol presented in this RFC is to create a system 104 where Service Providers can easily enable their applications/services 105 to work with the domain names of their customers. This includes both 106 discovery of the DNS Provider and subsequent modification of DNS. 108 2. Terminology 110 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 111 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 112 document are to be interpreted as described in RFC 2119 [RFC2119]. 114 XML is case sensitive. Unless stated otherwise, XML specifications 115 and examples provided in this document MUST be interpreted in the 116 character case presented in order to develop a conforming 117 implementation. 119 3. Definitions 121 The following definitions are used in this document: 123 o Service Providers - refers to entities that provide products and 124 services attached to domain names. Examples include web hosting 125 providers (such as Wix or SquareSpace), email Service Providers 126 (such as Microsoft or Google) and potentially even hardware 127 manufacturers with DNS-enabled devices including home routers or 128 automation controls (such as Linksys, Nest, and Philips). 129 o DNS Providers - refers to entities that provide DNS services such 130 as registrars (e.g. GoDaddy, eNom or Tucows) or standalone DNS 131 services (e.g. CloudFlare). 132 o Customer/User - refers to the end-user of these services. 133 o Templates/Service Templates - refers to a file that describes a 134 set of changes to DNS and domain functionality to enable a 135 specific service. 137 4. The API 139 The system will be implemented using simple web based interactions 140 and standard authentication protocols, allowing for the creation and 141 modification of DNS settings through the application of templates 142 instead of direct manipulation of individual DNS records. 144 The core of this proposal is based on templates. Templates describe 145 a service owned by a Service Provider, and contain all of the 146 information necessary to describe the changes to the domain and to 147 DNS required to enable and operate/maintain a service. These changes 148 are in the form of records/commands which map to records in DNS or 149 other domain behavior (e.g. redirects). 151 The individual records/commands may be identified by a group 152 identifier. This allows for the application of templates in 153 different stages. For example, an email provider might first set a 154 TXT record to verify the domain, and later set an MX record to 155 configure email. While done separately, both changes are 156 fundamentally part of the same service. 158 Templates can also contain variable portions, as often values of data 159 in the template change based on the rules of the Service Provider 160 (e.g. the IP address of a service). 162 Configuration and onboarding of templates between the DNS Provider 163 and the Service Provider is initially seen as a manual process. The 164 template is defined by the Service Provider and given to the DNS 165 Provider. Future versions of this specification may allow for an 166 independent repository of templates. 168 By basing the protocol on templates instead of DNS Records, several 169 advantages are achieved. The DNS Provider has very explicit 170 knowledge and control on the settings being changed to enable a 171 service. The system is also more secure as templates are tightly 172 controlled and contained. 174 All parties benefit by having an open standard. With more DNS 175 Providers supporting the standard, more Service Providers are likely 176 to adopt and vice versa. 178 The value to customers is simple, Domain Connect makes configuration 179 of services much easier. Instead of editing individual DNS records, 180 a customer simply approves the application of a template to their 181 domain. 183 To attach a domain name to a service provided by a Service Provider, 184 the customer would first enter their domain name. 186 Instead of relying on examination of the nameserver and mapping these 187 to DNS Providers, DNS Provider discovery would be handled through 188 simple records in DNS and an API. The Service Provider would query 189 for a specific record in the zone to determine a REST endpoint, call 190 an API, and a Domain Connect compliant DNS Provider would return 191 information about that domain at the DNS Provider. 193 For the application of the changes to DNS, there are two main use 194 cases. The first is a synchronous web flow. The second is an 195 asynchronous flow using oAuth and an API. 197 It should be noted that a DNS Provider may choose to only implement 198 the synchronous web flow, or only the asynchronous oAuth based flow, 199 adding the alternative later. As a matter of practice many Service 200 Providers are based on the synchronous flow, with only a couple of 201 them based on the asynchronous oAuth flow. So many DNS providers may 202 choose to only implement the synchronous flow. 204 4.1. Web-Based Authentication, Authorization & Template Action Flow 206 This flow is tailored for the Service Provider that requires a one- 207 time synchronous change to DNS. 209 The user would first enter their domain name at the Service Provider. 211 After the Service Provider determines the DNS Provider, the Service 212 Provider would display a link to the user indicating that they can 213 "Connect their Domain" to the service. 215 After clicking the link, the user is directed to a browser window on 216 the DNS Provider's site. This could be in place, another tab, or in 217 a new browser window. This link would indicate the domain name being 218 updated, the service being enabled, and any additional parameters 219 needed to configure the service. 221 The user would be asked to authenticate at the DNS Provider site. 223 After authenticating at the DNS Provider, the DNS Provider would 224 verify the domain name, provided by the user, is owned by the user. 225 The DNS Provider would also verify other parameters passed in are 226 valid and would prompt the user to give consent for making the change 227 to DNS. 229 Assuming the user grants this consent, the DNS changes would be 230 applied. Upon successful application of the DNS changes, an optional 231 callback URL would be called at the Service Provider indicating 232 success. 234 4.2. OAuth Based Authentication and Authorization Flow 236 The OAuth flow is tailored for the Service Provider that wishes to 237 make changes to DNS asynchronously to the user interaction, or may 238 wish to make multiple or additional changes to DNS over time. 240 The OAuth based authentication and authorization flow begins 241 similarly to the web based synchronous flow. 243 However, instead of applying the DNS changes on user confirmation, 244 OAuth access is granted to the Service Provider. An OAuth token is 245 generated and handed back to the Service Provider. 247 The permission granted in the OAuth token is a right for the Service 248 Provider to apply changes based on the template to the specific 249 domain owned by a specific user. 251 The Service Provider would call an API that applies this template to 252 the domain, including any necessary parameters along with the access 253 token(s). As in all OAuth flows, access can be revoked by the user 254 at any time. This would be done on the DNS Providers user 255 experience. 257 If the OAuth flow is used, once a Service Provider has an OAuth token 258 the Domain Connect API becomes available for use. The Domain Connect 259 API is a simple REST service. 261 This REST service allows the application or removal of the changes in 262 the template on a domain name. The domain name, user, and template 263 must be authorized through the OAuth token and corresponding access 264 token. 266 Additional parameters named keys are expected to be passed as name/ 267 value pairs on the query string of each API call. 269 4.3. DNS Provider Initiated Flows 271 It may be desired to expose different services available from the DNS 272 Provider, mainly to expose interesting services that the user could 273 attach to their domain. An example would be suggesting to a user 274 that they might want to connect their domain to a partner Service 275 Provider. 277 If the template for the service is static, it is sometimes possible 278 to simply apply the template, and be done. 280 However, often the template has some dynamic elements. For this 281 scenario, the DNS Provider need simply call a URL at the Service 282 Provider. The Service Provider can then sign the user in, collect 283 any necessary information, and call the normal web-based flows 284 described above. 286 4.4. DNS Provider Discovery 288 In order to facilitate discovery of the DNS Provider given a domain 289 name, a domain will contain a record in DNS. 291 This record will be a simple TXT record containing a URL used as a 292 prefix for calling a discovery API. This record will be named 293 domainconnect. 295 An example of this record would contain: 297 https://domainconnect.godaddy.com 299 As a practical matter of implementation, the DNS Provider need not 300 contain a copy of this data in each and every zone. Instead, the DNS 301 Provider needs simply to respond to the DNS query for the 302 domainconnect TXT record with the appropriate data. How this is 303 implemented is up to the DNS Provider. 305 Once the URL prefix is discovered, it can be used by the Service 306 Provider to determine the additional settings for using Domain 307 Connect on this domain at the DNS Provider. This is done by calling 308 a REST API. 310 GET 311 v2/{domain}/settings 313 This will return a JSON structure containing the settings to use for 314 Domain Connect on the domain name (passed in on the path) at the DNS 315 Provider. This JSON structure will contain the following fields: 317 o providerName: The name of the DNS Provider suitable for display on 318 the Service Provider UX. 319 o urlSyncUX: The URL Prefix for linking to the UX elements of Domain 320 Connect for the synchronous flow at the DNS Provider. 321 o urlAsyncUX: The URL Prefix for linking to the UX elements of 322 Domain Connect for the asynchronous flow at the DNS Provider 323 o urlAPI: This is the URL Prefix for the REST API for the 324 asynchronous OAuth API. 326 As an example, the JSON returned by this call might contain. 328 { 329 "providerName": "GoDaddy", 330 "urlSyncUX": "https://domainconnect.godaddy.com", 331 "urlAsyncUX": "https://domainconnect.godaddy.com", 332 "urlAPI" : "https://api.domainconnect.godaddy.com" 333 } 335 4.5. Domain Connect Endpoints 337 Domain Connect contains endpoints in the form of URLs. 339 The first set of endpoints are for the UX that the Service Provider 340 links to. 342 These are for the UX which includes the web-based flow where the user 343 clicks on the link, and the OAuth flow where the user clicks on the 344 link for consent. 346 The second set of endpoints are for the API that is called as part of 347 the asynchronous OAuth flow via REST. 349 All endpoints begin with a root URL for the DNS Provider such as 350 https://connect.dnsprovider.com/ and may also include any prefix at 351 the discretion of the DNS Provider, for example, 352 https://connect.dnsprovider.com/api/ 354 The root URLs for the UX endpoints and the API endpoints are returned 355 in the JSON payload during DNS Provider discovery. 357 4.5.1. Web Based Flow 359 4.5.1.1. Web Based Flow: Template 361 GET 362 v2/domainTemplates/ 363 providers/{providerDomain}/services/{serviceName} 365 This URL can be used by the Service Provider to determine if the DNS 366 Provider supports a specific template. 368 Returning a status of 200 without a body indicates the template is 369 supported. Returning a status of 404 indicates the template is not 370 supported. 372 4.5.1.2. Web Based Flow: Initiation 374 GET 375 v2/domainTemplates/providers/{providerDomain}/services/{serviceNam 376 e}/apply?[properties] 378 This is the URL used to apply a template to a domain. This URL is 379 embedded on the Service Provider's site to start the Domain Connect 380 protocol. 382 Parameters/properties passed to this URL include: 384 o domain: This parameter contains the domain name being configured. 385 o name/value pairs: Any variable fields consumed by this template. 386 The name portion of this API call corresponds to the variable(s) 387 specified in the template and the value corresponds to the value 388 that should be used when applying the template. 389 o requestId: This OPTIONAL parameter may contain a value that will 390 be passed back to the calling Service Provider via the template's 391 callback URL. A Service Provider may use this value to identify a 392 specific call or for any other purpose. 393 o groupId: This OPTIONAL parameter specifies the group of changes 394 from the template to apply. If no group is specified, all changes 395 are applied. 397 An example query string is below: 399 GET 400 https://webconnect.dnsprovider.com/v2/domainTemplates/providers/co 401 olprovider.com/services/hosting/ 402 apply?www=192.168.42.42&m=192.168.42.43&domain=example.com 404 This call indicates that the Service Provider wishes to connect the 405 domain example.com to the service using the template identified by 406 the composite key of the provider (coolprovider.com) and the service 407 owned by them (hosting). In this example, there are two variables in 408 this template, "www" and "m" which both require values (in this case 409 each requires an IP address). These variables are passed as name/ 410 value pairs. 412 As part of the Domain Connect flow, a callback URL will be invoked if 413 provided. 415 It should also be noted that successfully getting a callback URL 416 invoked in a flow such as this isn't 100% reliable. Requests often 417 fail, and users may close their web browser before such a callback is 418 invoked. 420 This callback URL is largely for tracking and convenience. As such 421 the lack of reliability is likely not a factor. A Service Provider 422 who wishes to continue any process with certainty will simply check 423 the DNS for any applied changes as a trigger for further action. 425 The URL called is specified as part of the onboarding process with 426 the service. This URL would allow for the substitution of three 427 values: 429 o domain: The domain name configured with domain connect. 430 o requestId: The passed in requestId in the initial call. 432 o status: The status or results of the operation (SUCCESS, CANCELED, 433 FAILED, ERROR). 435 The format of this URL provided by the Service Provider to the DNS 436 Provider would be similar to: 438 http://example.com/ 439 connectresults?domain=%domain%&request=%requestId%&status=%status% 441 4.5.2. OAuth Flow 443 Using the OAuth flow is a more advanced use case, needed by Service 444 Providers that have more complex configurations that may require 445 multiple steps and/or are asynchronous from the user's interaction. 447 Details of an OAuth implementation are beyond the scope of this 448 specification. Instead, an overview of how OAuth fits with Domain 449 Connect is given here. 451 Service providers wishing to use the OAuth flow must register as an 452 OAuth client with the DNS Provider. This is envisioned as a manual 453 process. 455 To register, the Service Provider would provide (in addition to their 456 template) one or more callback URLs that specify where the customer 457 will be redirected after the provider authorization. In return, the 458 DNS Provider will give the Service Provider a client id and secret 459 which will be used when requesting tokens as part of the OAuth 460 process flow. 462 4.5.2.1. Getting an Authorization Token 464 GET 465 v2/domainTemplates/ 466 providers/{providerDomain}/services/{serviceName} 468 To initiate the OAuth flow the Service Provider would link to the DNS 469 Provider to gain consent. This endpoint is similar to the 470 synchronous flow described above, and will handle authenticating the 471 user and asking for the user's permission to allow the Service 472 Provider to make the specified changes to the domain. 474 Upon successful authorization, the DNS Provider will direct the end 475 user's browser to the redirect URI provided in the request, appending 476 the authorization code as a query parameter of "code". 478 Upon error, the DNS Provider will direct the end user's browser to 479 the redirect URI provided in the request, appending the error code as 480 a query parameter "error". 482 The following describes the values to be included in the query string 483 parameters for this request. 485 o domain: This parameter contains the domain name being configured. 486 o client_id: This is the client id that was provided by the DNS 487 Provider, to the Service Provider during registration. 488 o redirect_uri: The location to direct the client's browser to upon 489 successful authorization, or upon error. 490 o scope: This is the name of the resource that the Service Provider 491 is requesting access to. 492 o response_type: OPTIONAL. If included should be the string 'code' 493 to indicate an authorization code is being requested. 494 o state: OPTIONAL but recommended. This is a random, unique string 495 passed along to prevent CSRF. It will be returned as a parameter 496 when redirecting to the redirect_url described above. 498 4.5.2.2. Requesting an Access Token 500 POST /v2/oauth/access_token 502 Once authorization has been granted the Service Provider must use the 503 Authorization Token provided to request an Access Token. The OAuth 504 specification recommends that the Authorization Token be a short 505 lived token, and a reasonable recommended setting is ten minutes. As 506 such this exchange needs to be completed before that time has expired 507 or the process will need to be repeated. 509 This token exchange is done via a server to server API call from the 510 Service Provider to the DNS Provider. 512 The Access Token granted will also have a short-lived lifespan, also 513 on the order of ten minutes. To get a new access token, the Refresh 514 Token is used. 516 The following describes the POST parameters to be included in the 517 request. 519 o code: The authorization code that was provided in the previous 520 step when the customer accepted the authorization request, or the 521 refresh_token for a subsequent access token. 522 o redirect_uri: OPTIONAL. If included, needs to be the same 523 redirect uri provided in the previous step, simple for 524 verification. 526 o grant_type: The type of code in the request. Usually the string 527 'authorization_code' or 'refresh_token'. 528 o client_id: This is the client id that was provided by the DNS 529 Provider, to the Service Provider during registration. 530 o client_secret: The secret provided to the Service Provider during 531 registration. 533 Upon successful token exchange, the DNS Provider will return a 534 response with 4 properties in the body of the response. 536 o access_token: The access token to be used when making API 537 requests. 538 o token_type: Always the string "bearer". 539 o expires_in: The number of seconds until the access_token expires. 540 o refresh_token: The token that can be used to request new access 541 tokens when this one has expired. 543 4.5.2.3. Making Requests with Access Tokens 545 Once the Service Provider has the access token, they can call the DNS 546 Provider's API to make change to DNS on behalf of the user. 548 All calls to this API pass the access token in the Authorization 549 Header of the request to the call to the API. More details can be 550 found in the OAuth specifications, but as an example: 552 GET /resource/1 HTTP/1.1 553 Host: example.com 554 Authorization: Bearer mF_9.B5f-4.1JqM 556 4.5.2.4. Apply Template to Domain 558 POST 559 v2/domainTemplates/ 560 providers/{providerId}/services/{serviceId}/apply?[properties] 562 The primary function of the API is to apply a template to a customer 563 domain. 565 While the providerId and serviceId are also implied in the 566 authorization, these are on the path for consistency with the 567 synchronous flows. If not matching what is in the authorization, an 568 error is returned. 570 In addition, the call must accept the following parameters: 572 o domain: This contains the domain name being configured. It must 573 match the domain in the authorization token. 575 o name/value pairs: Any variable fields consumed by this template. 576 The name portion of this API call corresponds to the variable(s) 577 specified in the record and the value corresponds to the value 578 that should be used when applying the template as per the 579 implementation notes. 580 o groupId: This OPTIONAL parameter specifies the group of changes in 581 the template to apply. If omitted, all changes are applied. 583 An example call is below. In this example, it is contemplated that 584 there are two variables in this template, "www" and "m" which both 585 require values (in this case each requires an IP address). These 586 variables are passed as name/value pairs. 588 POST 589 https://connect.dnsprovider.com/v2/domainTemplates/providers/coolp 590 rovider.com/services/hosting/ 591 apply?www=192.168.42.42&m=192.168.42.43 593 The API must validate the access token for the Service Provider and 594 that the domain belongs to the customer and is represented by the 595 token being presented. With these checks passing, the template may 596 be applied to the domain after verifying that doing so would not 597 cause an error condition, either because of problems with required 598 variables or the current state of the domain itself (for example, 599 already having a conflicting template applied). 601 Results of this call can include information indicating success, or 602 an error. Errors will be 400 status codes, with the following codes 603 defined. 605 o Success (204): A response of an http status code of 204 indicates 606 that call was successful and the template applied. Note that any 607 200 level code should be considered a success. 608 o Unauthorized (401,403): A response of a 401 indicates that caller 609 is not authorized to make this call. This can be because the 610 token was revoked, or other access issues. 611 o Error (404,422): This indicates something wrong with the request 612 itself, such as bad parameters. 613 o Failed (409): This indicates that the call was good, and the 614 caller authorized, but the change could not be applied due to 615 other conditions. This might be the application of a conflicting 616 template or a domain state that prevents updates. 618 4.5.2.5. Revert Template 620 POST 621 v2/domainTemplates/ 622 providers/{providerId}/services/{serviceId}/revert?domain={domain} 624 This API allows the removal of a template from a customer domain 625 using an OAuth request. 627 The provider and service name in the authorizatoin must match the 628 values in the URL. So must the domain name on the query string. 630 This call must validate that the template requested exists and has 631 been applied to the domain by the Service Provider or a warning must 632 be returned that the call would have no effect. This call must 633 validate that there is a valid authorization token for the domain 634 passed in or an error condition must be reported. 636 An example query string might look like: 638 POST 639 https://connect.dnsprovider.com/v2/domainTemplates/providers/coolp 640 rovider.com/services/hosting/revert?domain=example.com 642 Response codes are identical to above. 644 4.5.2.6. Revoke Access 646 Like all OAuth flows, the user can revoke the access at any time 647 using UX at the DNS Provider site. So the Service Provider needs to 648 be aware that their access to the API may be denied. 650 4.6. Domain Connect Objects and Templates 652 This description represents the values in the template. Since 653 onboarding of a Service Provider with a DNS Provider is initially a 654 manually oriented process, this format is a recommendation. 656 There may be a repository of templates in the future. 658 A template is defined as a standard JSON data structure containing 659 the following data: 661 o providerId: The unique identifier of the Service Provider that 662 created this template. This is used in the URLs to identify the 663 Service Provider. To ensure non-coordinated uniqueness, this 664 would be the domain name of the Service Provider. 665 o providerName: The name of the Service Provider. This will be 666 displayed to the user. 667 o templateId: The name or identifier of the template. This is used 668 in URLs to identify the template. 669 o templateName: The friendly name of this service. This will be 670 displayed to the user. 672 o logoUrl: A graphical logo for use in any web-based flow. This is 673 a URL to a graphical logo sufficient for retrieval. 674 o description: A textual description of what this template attempts 675 to do. This is meant to assist integrators, and therefore should 676 not be displayed to the user. 677 o launchUrl: OPTIONAL. A URL suitable for a DNS Provider to call to 678 initiate the execution of this template. This allows the flow to 679 begin with the DNS Provider as described above. 680 o returnUrl: OPTIONAL. The URL to call indicating the status of the 681 call. 682 o records: A list of records and/or actions for the template. 684 Each template record is an entry that contains a type and several 685 optional parameters based on the value. 687 For all entries of a record template other than "type" and "groupId", 688 the value can contain variables denoted by %%. These 689 are the values substituted at runtime when writing into DNS. 691 It should be noted that as a best practice, the variable should be 692 equal to the portion of the values in the template that change as 693 little as possible. 695 For example, say a Service Provider requires a CNAME of one of three 696 values for their users: s01.example.com, s02.example.com, and 697 s03.example.com. 699 The value in the template could simply contain %servercluster%, and 700 the fully qualified string passed in. Alternatively, the value in 701 the template could contain s%var%.example.com. By placing more fixed 702 data into the template, the data is more constrained. And by using a 703 generic name the values in the query string are more obscured. 705 Each record will contain the following elements: 707 o type: Describes the type of record in DNS, or the operation 708 impacting DNS. Valid values include: A, AAAA, CNAME, MX, TXT, 709 SRV, NS, APEXCNAME, REDIR301, or REDIR302. 710 o groupId: This OPTIONAL parameter identifies the group the record 711 belongs to when applying changes. 712 o host: The host for A, AAAA, CNAME, TXT, and MX values. This is 713 the hostname in DNS. 714 o pointsTo: The pointsTo location for A, AAAA, CNAME, MX, and 715 APEXCNAME records. 716 o ttl: This is the time-to-live for the record in DNS. Valid for A, 717 AAAA, CNAME, TXT, MX, and SRV records. 718 o data: This is the data for a TXT record in DNS. 719 o priority: This is the priority for an MX or SRV record in DNS. 721 o weight: This is the weight for the SRV record. 722 o port: This is the port for the SRV record. 723 o protocol: This is the protocol for the SRV record. 724 o service: This is the protocol for the SRV record. 725 o target: This is the target url for REDIR301 and REDIR302. 727 4.7. Implementation Notes 729 This template format is intended for internal use by a DNS Provider 730 and there are no codified API endpoints for creation or modification 731 of these objects. API endpoints do not use this object directly. 732 Instead, API endpoints reference a template by ID and then provide 733 key/value pairs that match any variable values in these record 734 objects. 736 However, by defining a standard template format it is believed it 737 will make it easier for Service Providers to share their provisioning 738 across DNS Providers. Further revisions of this specification may 739 include a repository for publishing and consuming these templates. 741 Implementers are responsible for data integrity and should use the 742 record type field to validate that variable input meets the criteria 743 for each different data type. 745 Certain record types may not be valid with others (e.g. a redirect 746 and an A record), and it is up to the DNS and Service Providers to 747 author templates appropriately. As such, a practical matter may be 748 the redirect is valid only by itself. 750 Additional record types and/or extensions to the data that can be set 751 into the template can be implemented on a per DNS Provider basis. 752 For example, if a DNS Provider supports additional record types, 753 these can be added to this specification and templates. 755 Similarly other providers may not wish to support certain record 756 types (redirects, APEXCNAME). Should this be the case, a Service 757 Provider depending on this functionality would not be able to operate 758 with said DNS Provider. 760 Example Records: Single static host record 762 Consider a template for setting a single host record. The records 763 section of the template would have a single record of type "A" and 764 could have a value of: 766 [{ 767 ''type'': ''A'', 768 ''host'': ''www'', 769 ''pointsTo'': ''192.168.1.1'', 770 ''ttl'': 600 771 }] 773 This would have no variable substitution and the application of this 774 template to a domain would simply set the host name "www" to the IP 775 address "192.168.1.1" 777 Example Records: Single variable host record for A 779 In the case of a template for setting a single host record from a 780 variable, the template would have a single record of type "A" and 781 could have a value of: 783 [{ 784 ''type'': ''A'', 785 ''host'': ''@'', 786 ''pointsTo'': ''192.168.1.%srv%'', 787 ''ttl'': 600 788 }] 790 A query string with a key/value pair of 792 srv=8 794 would cause the application of this template to a domain to set the 795 host name for the apex A record to the IP address "192.168.1.8" with 796 a TTL of 600. 798 Example: Multiple variable host record for A 800 In the case of a template for setting a single host record from 801 multiple variables, the template would have a single record of type 802 "A" and could have a value of: 804 [{ 805 ''type'': ''A'', 806 ''host'': ''%hostname1%'', 807 ''pointsTo'': ''%hostip1%'', 808 ''ttl'': 600 809 }] 811 A query string with key/value pairs of 813 hostname1=example&hostip1=192.168.1.3 814 would cause the application of this template to a domain to set the 815 host name "example" to the IP address "192.168.1.3" with a TTL of 816 600. 818 Example: Redirect 820 In the case of a template for setting an HTTP redirect, the template 821 would have a record of type "REDIRECT" and could have a value of: 823 [{ 824 ''type'': REDIR301, 825 ''target'': %url% 826 }] 828 A query string with key/value pairs of 830 url=http://www.example-two.com. 832 would cause the application of this template to signal to the DNS 833 Provider to provision URL redirection to the target URL. 835 Example Template JSON Format 837 { 838 "providerId": "example.com", 839 "providerName": "Example Web Hosting", 840 "templateId": "hosting", 841 "templateName": "Wordpress by example.com", 842 "logoUrl": "https://www.example.com/images/billthecat.jpg", 843 "description": "This connects your domain to our super cool web 844 hosting", 845 "returnUrl": "https://www.example.com/connectresults", 846 "launchURL" : "https://www.example.com/connectlaunch", 847 "records": [ 849 { 850 "groupId" : "service", 851 "type": "A", 852 "host": "www", 853 "pointsTo": "%var1%", 854 "ttl": "%var2%" 855 }, 856 { 857 "groupId" : "service", 858 "type": "A", 859 "host": "m", 860 "pointsTo": "%var3%", 861 "ttl": "%var2%" 862 }, 863 { 864 "groupId" : "service", 865 "type": "CNAME", 866 "host": "webmail", 867 "pointsTo": "%var4%", 868 "ttl": "%var2%" 869 }, 870 { 871 "groupId" : "verification", 872 "type": "TXT", 873 "host": "example", 874 "pointsTo": "%var5%", 875 "ttl": "%var2%" 876 } 877 ] 878 } 880 4.8. Operational and Implementation Considerations 882 From a DNS Provider standpoint, it is envisioned that the user has 883 appropriate warnings and checks in place to prevent accidental 884 destruction of other records in DNS when applying a template or 885 making manual changes in DNS. 887 For example, if the application of a template through the web based 888 flow would interfere with previously set DNS records (either through 889 another template or manual settings), it is envisioned that the user 890 would be asked to confirm the clearing of the previously set 891 template. If it would interfere with DNS records accessible through 892 a previously issued OAuth flow, the provider could revoke the 893 previously issued token. 895 Similarly, when granting an OAuth token that interferes with a 896 previously issued OAuth token, access to the old token could 897 automatically be revoked. 899 By doing so, this minimizes if not eliminates the case where an OAuth 900 token cannot be applied due to conflicting templates or records 901 existing on the domain. 903 Manual changes to DNS through the DNS Provider could have appropriate 904 warnings in place to prevent unwanted changes; with overrides being 905 possible removing conflicting templates. 907 The behavior of these interactions is left to the sophistication of 908 the DNS Provider. 910 Variables in templates that are hard-coded host names are the 911 responsibility of the DNS Provider to protect. That is, DNS 912 Providers are responsible for ensuring that host names do not 913 interfere with known values (such as m. or www. or mail.) or internal 914 names that provide critical functionality that is outside the scope 915 of this specification. 917 5. IANA Considerations 919 This document uses URNs to describe XML namespaces and XML schemas 920 conforming to a registry mechanism described in [RFC3688]. The 921 following URI assignment is requested of IANA: 923 URI: ietf:params:xml:ns:validate-1.0 925 Registrant Contact: See the "Author's Address" section of this 926 document. 928 6. Acknowledgements 930 The authors wish to thank the following persons for their feedback 931 and suggestions: 933 o Chris Ambler of GoDaddy Inc. 934 o Jody Kolker of GoDaddy Inc. 936 7. Change History 938 7.1. Change from 01 to 02 940 Added new GET method for Service Providers to determine if the DNS 941 Provider supports a specific template. Some other minor edits for 942 clarification. 944 7.2. Change from 00 to 01 946 Minor edits and clarifications found during implementation. 948 8. Normative References 950 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 951 Requirement Levels", BCP 14, RFC 2119, 952 DOI 10.17487/RFC2119, March 1997, 953 . 955 [RFC3688] Mealling, M., "The IETF XML Registry", BCP 81, RFC 3688, 956 DOI 10.17487/RFC3688, January 2004, 957 . 959 Authors' Addresses 961 Arnold Blinn 962 GoDaddy Inc. 963 14455 N. Hayden Rd. #219 964 Scottsdale, AZ 85260 965 US 967 Email: arnoldb@godaddy.com 968 URI: http://www.godaddy.com 970 Roger Carney 971 GoDaddy Inc. 972 14455 N. Hayden Rd. #219 973 Scottsdale, AZ 85260 974 US 976 Email: rcarney@godaddy.com 977 URI: http://www.godaddy.com