idnits 2.17.1 draft-daboo-aggregated-service-discovery-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 : ---------------------------------------------------------------------------- No issues found here. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year -- The document date (June 28, 2013) is 3955 days in the past. Is this intentional? Checking references for intended status: Proposed Standard ---------------------------------------------------------------------------- (See RFCs 3967 and 4897 for information about using normative references to lower-maturity documents in RFCs) == Outdated reference: A later version (-18) exists of draft-ietf-appsawg-webfinger-14 == Outdated reference: A later version (-09) exists of draft-newton-json-content-rules-01 ** Obsolete normative reference: RFC 2616 (Obsoleted by RFC 7230, RFC 7231, RFC 7232, RFC 7233, RFC 7234, RFC 7235) ** Obsolete normative reference: RFC 2818 (Obsoleted by RFC 9110) ** Obsolete normative reference: RFC 4627 (Obsoleted by RFC 7158, RFC 7159) ** Obsolete normative reference: RFC 5988 (Obsoleted by RFC 8288) ** Obsolete normative reference: RFC 6125 (Obsoleted by RFC 9525) -- Obsolete informational reference (is this intentional?): RFC 3501 (Obsoleted by RFC 9051) Summary: 5 errors (**), 0 flaws (~~), 3 warnings (==), 2 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Network Working Group A. McMillan 3 Internet-Draft Morphoss 4 Intended status: Standards Track C. Daboo 5 Expires: December 30, 2013 Apple Inc. 6 June 28, 2013 8 Automated Service Configuration 9 draft-daboo-aggregated-service-discovery-03 11 Abstract 13 This specification describes how clients can retrieve configuration 14 for multiple services with a minimum of user-provided information, 15 and as short as possible sequence of queries, and with a minimum of 16 overhead for administrators of the services. 18 Status of This Memo 20 This Internet-Draft is submitted in full conformance with the 21 provisions of BCP 78 and BCP 79. 23 Internet-Drafts are working documents of the Internet Engineering 24 Task Force (IETF). Note that other groups may also distribute 25 working documents as Internet-Drafts. The list of current Internet- 26 Drafts is at http://datatracker.ietf.org/drafts/current/. 28 Internet-Drafts are draft documents valid for a maximum of six months 29 and may be updated, replaced, or obsoleted by other documents at any 30 time. It is inappropriate to use Internet-Drafts as reference 31 material or to cite them other than as "work in progress." 33 This Internet-Draft will expire on December 30, 2013. 35 Copyright Notice 37 Copyright (c) 2013 IETF Trust and the persons identified as the 38 document authors. All rights reserved. 40 This document is subject to BCP 78 and the IETF Trust's Legal 41 Provisions Relating to IETF Documents 42 (http://trustee.ietf.org/license-info) in effect on the date of 43 publication of this document. Please review these documents 44 carefully, as they describe your rights and restrictions with respect 45 to this document. Code Components extracted from this document must 46 include Simplified BSD License text as described in Section 4.e of 47 the Trust Legal Provisions and are provided without warranty as 48 described in the Simplified BSD License. 50 Table of Contents 52 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 3 53 2. Open Issues . . . . . . . . . . . . . . . . . . . . . . . . . 4 54 3. Conventions Used in This Document . . . . . . . . . . . . . . 4 55 4. Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . 4 56 5. Automated Service Configuration Document Format . . . . . . . 4 57 5.1. Extensions to the Document Format . . . . . . . . . . . . 8 58 5.2. Service names . . . . . . . . . . . . . . . . . . . . . . 8 59 6. Finding the Automated Service Configuration Information . . . 8 60 7. Handling multiple, alternative services . . . . . . . . . . . 9 61 8. Internationalization Considerations . . . . . . . . . . . . . 10 62 9. Security Considerations . . . . . . . . . . . . . . . . . . . 10 63 10. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 10 64 10.1. Link Relation Registration . . . . . . . . . . . . . . . . 10 65 10.1.1. service-configuration Link Relation Registration . . 10 66 11. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 11 67 12. References . . . . . . . . . . . . . . . . . . . . . . . . . . 11 68 12.1. Normative References . . . . . . . . . . . . . . . . . . . 11 69 12.2. Informative References . . . . . . . . . . . . . . . . . . 12 70 Appendix A. Change History (to be removed prior to 71 publication as an RFC) . . . . . . . . . . . . . . . 12 72 Appendix B. Example of multiple services . . . . . . . . . . . . 13 73 Appendix C. Example - multiple, alternative mail retrieval 74 services . . . . . . . . . . . . . . . . . . . . . . 15 75 Appendix D. Example - multiple links . . . . . . . . . . . . . . 18 77 1. Introduction 79 There are currently various systems in place for discovery and 80 configuration of individual services, but the process can often 81 require an extensive series of requests using different protocols to 82 discover all of the details needed to set up the various client 83 services which an individual might use to interact with an 84 organisation or service provider. 86 Consider Jason, a new employee at Example Enterprises. Jason needs 87 to configure his e-mail program to use IMAP [RFC3501] + TLS on port 88 143 against mail.example.com, he needs to send mail on port 8557 via 89 TLS+SMTP to smtp.example.com, his calendar is on port 8443 at 90 https://caldav.example.com:8443/calendar/, and so forth. Some of 91 these things can be discovered relatively easily, with a combination 92 of DNS queries (including SRV lookups, certificate checking, and http 93 requests). However, each protocol has its own requirements and 94 settings and each has to be done separately. Whilst the client can 95 "hide" the multiple service setup from the user, the actual 96 implementation often requires separate code and processes to manage, 97 making it more complex that it needs to be. 99 This specification defines a single protocol which will allow for 100 retrieval of a variety of service configuration information in a 101 single call, allowing developers to simplify the coding and user 102 interface in client software, and in particular in multi-function 103 client software such as a combined e-mail and calendar clients. 104 Configuration is retrieved from a single document on a server, 105 improving performance over per-service configuration mechanisms that 106 require multiple network operations. In addition, complex 107 dependencies between different services can be easily represented, so 108 that, for example, some services can be prioritized over others, or 109 grouped together by "logical" function. Further, rich information 110 about each service can be included, such as details about required 111 transport layer security or authentication. 113 This protocol is intended to provide a simple one-way retrieval of 114 configuration information, with the data flow from service provider 115 to client, building on successful technologies such as HTTP and JSON 116 to accomplish its goals. As such it differs from other "client 117 configuration" orientated protocols, such as ACAP [RFC2244], which 118 have not had much deployment success due to complexity introduced by 119 having a a two-way exchange of data, and the resulting need to keep 120 multiple clients synchronized as changes occur. 122 2. Open Issues 124 1. Is it OK to embed certificate details for the actual services or 125 a root certificate? 127 3. Conventions Used in This Document 129 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 130 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 131 document are to be interpreted as described in [RFC2119]. 133 4. Overview 135 The following outlines the steps a client carries out to setup 136 multiple services for a user: 138 1. The client software is expected to capture a user identifier and 139 domain name (possibly entered in the form of an email address) 140 from the user, and possibly authentication information. e.g., 141 'cyrus@example.com'. 143 2. The client uses the WebFinger [I-D.ietf-appsawg-webfinger] 144 protocol to request a link relation with the value "service- 145 configuration", using the identifier supplied by the user, 146 following any redirects and responding to any authentication 147 challenges. 149 3. The client retrieves a JSON [RFC4627] document conforming to the 150 format described in Section 5 from the target of the link 151 relation returned in Step #2. The client parses this document to 152 extract information about the available services. At that point 153 it can either present a list of services to the user, so that 154 they can decide exactly what they want setup, or it can 155 automatically setup services for all those it supports. 157 5. Automated Service Configuration Document Format 159 The automated service configuration document is an JSON [RFC4627] 160 document. The document contains a single object with two members 161 representing two pieces of information: overall service provider 162 information (e.g., name, icon "badge", contact information), and a 163 list of each service supported. Each service will contain some 164 information common to each type of service, and then information 165 specific to each service. 167 The JSON document format is defined here using the syntax in 168 [I-D.newton-json-content-rules]. An example of such an automated 169 service configuration document for some common services is shown in 170 Appendix B. 172 JSON Content Rules for the JSON document returned for a 173 "capabilities" action request. 175 ; root object 177 root { 178 provider, 179 entries 180 } 182 ; ----- provider ----- 184 ; Contains information describing the service provider, that can be 185 ; used by clients to "group" individual services together under a 186 ; common name or section when presenting details to the user. 187 provider "provider" { 188 provider_name, 189 ?description, 190 ?image, 191 ?contact, 192 ?manage, 193 ?password_reset, 194 ?ttl 195 } 197 ; The name for the service provider. 198 provider_name "name" : string 200 ; The description of the service provider. 201 description "description" : string 203 ; A URI for an image that can be used as an "icon" for the service 204 ; provider. The URI SHOULD be an http or https URI and clients 205 ; SHOULD use standard HTTP Accept header behavior to request an 206 ; appropriate image format from the server (see Section 14.1 of 207 ; [RFC2616]). The image SHOULD NOT exceed a size of 128 x 128 208 ; pixels. 209 image "image" : uri 211 ; Contact information for the service provider. 212 contact "contact" { 213 email / (?email, uri) 214 } 216 ; An email address that can be used to contact the service 217 ; provider. 219 email "email" : email 221 ; A URI for a webpage providing information about the service 222 ; provider. 223 url "url" : uri 225 ; A URI for a webpage where a user can manage details of their 226 ; account. 227 ; e.g., a place where users can go to add additional (possibly 228 ; payment required) services. 229 manage "manage" : uri 231 ; A URI for a webpage where a user can change their account 232 ; password. 233 password_reset "password-reset" : uri 235 ; The minimum interval in seconds which clients SHOULD wait 236 ; before re-fetching the document to check for changes. 237 ttl "ttl" : integer 239 ; ----- entries ----- 241 ; List of services. 242 entries "entries" [ *entry ] 244 entry { 245 name, 246 service, 247 ?(group, priority), 248 uri / (host, ?port), 249 ?tls, 250 ?auth, 251 } 253 ; A description for the service. 254 name "name" : string 256 ; The service type. See below for details of the value used. 257 service "service" : string 259 ; Identifies the nature of the service to allow similar services to 260 ; be grouped together. 261 group "group" : string 263 ; Identifies the nature of the service to allow similar services to 264 ; be grouped together. 265 priority "priority" : integer 1 266 ; The URI used to contact the server providing the service. 267 uri "uri" : uri 269 ; The hostname of the server providing the service. 270 host "host" : string 272 ; The network port number of the server providing the service. 273 port "port" : integer 0..65535 275 ; Provides detail of transport layer security to be used with the 276 ; service. 277 tls "tls" { 278 ?required, 279 ?at_start, 280 ?certificates 281 } 283 ; Indicates that clients MUST use transport layer security when 284 ; connecting to the server providing the service. 285 required "required" : boolean 287 ; Indicates that clients MUST initiate TLS immediately upon 288 ; connecting to the server rather than using an "in-protocol" 289 ; upgrade mechanism. 290 at_start "at-start" : boolean 292 ; List of certificates. 293 certificates "certificates" [ *certificate ] 295 ; Details about the TLS certificate the server will use. Clients 296 ; MAY use the specified certificate information to validate any TLS 297 ; connection to the server, otherwise existing rules for the target 298 ; protocol are used. 299 certificate "certificate" { 300 cert_name / 301 fingerprint / 302 public_key 303 } 305 ; The name of the certificate. 306 cert_name "name" : string 308 ; The fingerprint of the certificate. 309 fingerprint "fingerprint" : string 311 ; The fingerprint of the certificate. 312 public_key "public-key" : string 313 ; List of authentication methods to use in server preferred order. 314 ; If the protocol supports SASL [RFC4422] then this is a list of 315 ; SASL authentication mechanisms, otherwise it is a protocol 316 ; specific list of names. In either case, clients MUST NOT use 317 ; a mechanism that is not advertised in this list. 318 auth "auth" [ *string ] 320 5.1. Extensions to the Document Format 322 Additional members can be added to the JSON document root, "provider" 323 or "entries" objects with the following rules: 325 1. Standards based members MUST be defined in an RFC and registered 326 with IANA. TBD - precise details of this and IANA registry 327 setup. 329 2. Member names that include a prefix of the form "{...}", where the 330 contents of the curly braces is a vendor id, are considered to be 331 vendor specific private extensions which do not require 332 registration. TBD nature of vendor id. 334 Clients SHOULD ignore all extension member elements that they are 335 unable to process. 337 5.2. Service names 339 The "service" member in the "entry" object is used to convey an 340 identifier for the type of service being described. This can have 341 one of two forms: 343 1. An identifier from the IANA ports registry defining a service 344 type. 346 2. Identifiers that include a prefix of the form "{...}", where the 347 contents of the curly braces is a vendor id, are considered to be 348 vendor specific private service type. TBD nature of vendor id. 350 6. Finding the Automated Service Configuration Information 352 This specification makes use of the WebFinger 353 [I-D.ietf-appsawg-webfinger] protocol to allow a client to find a 354 link to the automated service configuration document corresponding to 355 an identifier supplied by a user. This specification registers the 356 "service-configuration" link relation type for use with WebFinger, to 357 identify the links for automated service configuration documents. 358 When the client makes a WebFinger request, it SHOULD use the "rel" 359 query parameter, defined in Section 4.3 of 361 [I-D.ietf-appsawg-webfinger], to ensure the relevant link relations 362 are returned. The URI referenced by the links MUST be an HTTPS 363 [RFC2818] URI, and MUST point to a resource that the client can use 364 to retrieve the automated service configuration document for the 365 site. 367 Servers can return multiple "service-configuration" links in the 368 webfinger response. Clients SHOULD treat each link as separate, 369 complementary services available to the user. 371 When requesting automated service configuration documents, clients 372 MUST include a URI query parameter "id" set to the user identifier 373 entered by the user. Clients MUST handle HTTP redirects on the link 374 URI, but MUST NOT allow a redirect to an insecure URI. When 375 responding to the request, the server MUST tailor the automated 376 service configuration document for the user making the request and 377 MUST require HTTP authentication by that user before returning the 378 document. 380 Clients SHOULD cache the document for a period of time no less than 381 the value of the "ttl" member in the "provider" object, or for a 382 minimum of 24 hours of no "ttl" member is present. 384 7. Handling multiple, alternative services 386 The "group" and "priority" members of an entry provide a way for a 387 service provider to distinguish multiple services of the same type, 388 as well as allow the client to select the most appropriate service 389 when several alternatives exist. 391 For example, consider the case of a service provider supporting two 392 separate email retrieval services, one the "primary" account, and the 393 other for "internal" messaging only. It is expected that clients 394 configure accounts for both services. Each service also offers 395 either IMAP [RFC3501] or POP3 [RFC1939] as an email retrieval 396 protocol. In this case the automated service configuration document 397 would contain four entry items: two describing an IMAP service and 398 two describing a POP3 service. Each entry would contain a "group" 399 member that groups one IMAP and one POP3 service together for each of 400 the "primary" and "internal" account groups. Each entry would also 401 contain a "priority" member indicating the service providers 402 preference for clients to use either IMAP or POP3. An example of 403 such an automated service configuration document is shown in 404 Appendix C. 406 When a client retrieves and processes such a document, it would first 407 group services based on the SD:application value. For each group, it 408 iterates over the list of entries in the group, ordered by SD: 410 priority values, and configures an account for the first one it finds 411 with an SD:service that it supports. 413 8. Internationalization Considerations 415 Some elements of the automated service configuration document can 416 contain human readable text that clients might choose to present to a 417 user. Clients SHOULD use the Accept-Language header behavior 418 described in Section 14.4 of [RFC2616] to ensure the server can 419 return a document suitable for the user's chosen language. Servers 420 SHOULD support variations of the automated service configuration 421 document based on language, returning the appropriate variation in 422 response to client requests. 424 9. Security Considerations 426 When using WebFinger to discover a server hosting the automated 427 service configuration document, a malicious attacker with access to 428 the DNS server data, or able to get spoofed answers cached in a 429 recursive resolver, can potentially cause clients to connect to a 430 server hosting a bogus automated service configuration document with 431 service data chosen by the attacker. In the absence of a secure DNS 432 option, clients SHOULD check that the target FQDN returned in the 433 link relation URI record matches the original service domain that was 434 queried. If the target FQDN is not in the queried domain, clients 435 SHOULD verify with the user that the link URI target FQDN is suitable 436 for use before executing any connections to the host. 438 HTTP requests for the automated service configuration document MUST 439 be performed via TLS. Clients MUST use the procedure outlined in 440 Section 4.3 of [RFC6125] to verify the service. 442 10. IANA Considerations 444 10.1. Link Relation Registration 446 This document defines a "service-configuration" link relation type 447 using the registration procedure and template from Section 6.2 of 448 [RFC5988]. 450 10.1.1. service-configuration Link Relation Registration 452 Relation Name: service-configuration 454 Description: Refers to an automated service configuration document 455 Reference: This RFC. 457 11. Acknowledgments 459 The authors would like to thank the following individuals for 460 contributing their ideas and providing feedback for writing this 461 specification: Andrew Biggs, Mike Douglass, Joe Hildebrand, Paul 462 Jones, Markus Lanthaler, Matt Miller, Stepan Potys, and Peter Saint- 463 Andre 465 The authors would also like to thank CalConnect, The Calendaring and 466 Scheduling Consortium, for advice with this specification. 468 12. References 470 12.1. Normative References 472 [I-D.ietf-appsawg-webfinger] Jones, P., Salgueiro, G., and J. 473 Smarr, "WebFinger", 474 draft-ietf-appsawg-webfinger-14 475 (work in progress), May 2013. 477 [I-D.newton-json-content-rules] Newton, A., "A Language for Rules 478 Describing JSON Content", 479 draft-newton-json-content-rules-01 480 (work in progress), January 2013. 482 [RFC2119] Bradner, S., "Key words for use in 483 RFCs to Indicate Requirement 484 Levels", BCP 14, RFC 2119, 485 March 1997. 487 [RFC2616] Fielding, R., Gettys, J., Mogul, J., 488 Frystyk, H., Masinter, L., Leach, 489 P., and T. Berners-Lee, "Hypertext 490 Transfer Protocol -- HTTP/1.1", 491 RFC 2616, June 1999. 493 [RFC2818] Rescorla, E., "HTTP Over TLS", 494 RFC 2818, May 2000. 496 [RFC4422] Melnikov, A. and K. Zeilenga, 497 "Simple Authentication and Security 498 Layer (SASL)", RFC 4422, June 2006. 500 [RFC4627] Crockford, D., "The application/json 501 Media Type for JavaScript Object 502 Notation (JSON)", RFC 4627, 503 July 2006. 505 [RFC5988] Nottingham, M., "Web Linking", 506 RFC 5988, October 2010. 508 [RFC6125] Saint-Andre, P. and J. Hodges, 509 "Representation and Verification of 510 Domain-Based Application Service 511 Identity within Internet Public Key 512 Infrastructure Using X.509 (PKIX) 513 Certificates in the Context of 514 Transport Layer Security (TLS)", 515 RFC 6125, March 2011. 517 12.2. Informative References 519 [RFC1939] Myers, J. and M. Rose, "Post Office 520 Protocol - Version 3", STD 53, 521 RFC 1939, May 1996. 523 [RFC2244] Newman, C. and J. Myers, "ACAP -- 524 Application Configuration Access 525 Protocol", RFC 2244, November 1997. 527 [RFC3501] Crispin, M., "INTERNET MESSAGE 528 ACCESS PROTOCOL - VERSION 4rev1", 529 RFC 3501, March 2003. 531 Appendix A. Change History (to be removed prior to publication as an 532 RFC) 534 Changes in -03: 536 1. Fix examples to properly show request/response headers. 538 2. Title change. 540 3. Added text to the Introduction to differentiate this from other 541 protocols. 543 4. Switched to WebFinger instead of SRV. 545 Changes in -02: 547 1. Switched to JSON document format. 549 Changes in -01: 551 1. Renamed various elements for clarity. 553 2. Added an SD:manage element. 555 3. Added a section on handling of multiple, alternative services, 556 together with a second appendix example. 558 Appendix B. Example of multiple services 560 First comes the WebFinger request to retrieve the appropriate link 561 relation. 563 >> Request << 565 GET /.well-known/webfinger? 566 resource=acct:cyrus@example.com& 567 rel=service-configuration HTTP/1.1 568 Host:example.com:443 569 Authorization: basic QmFzZTY0IGlzIGVhc3kgdG8gZGVjb2Rl 571 >> Response << 573 HTTP/1.1 200 OK 574 Date: Wed, 20 Feb 2013 09:32:12 GMT 575 Content-Type: application/jrd+json 576 Content-Length: xxx 578 { 579 "subject" : "acct:cyrus@example.com", 580 "links" : 581 [ 582 { 583 "rel" : "service-configuration", 584 "type" : "application/json", 585 "href" : "https://example.com/service-config" 586 } 587 ] 588 } 590 Next is the retrieval of the automated service configuration document 591 using the URI from the WebFinger link relation. 593 >> Request << 595 GET /service-config?id=cyrus@example.com HTTP/1.1 596 Host:example.com:443 597 Authorization: basic QmFzZTY0IGlzIGVhc3kgdG8gZGVjb2Rl 598 >> Response << 600 HTTP/1.1 200 OK 601 Date: Wed, 20 Feb 2013 09:32:12 GMT 602 Content-Type: application/json 603 Content-Length: xxx 605 { 606 "provider" : { 607 "name" : "Super-duper ISP", 608 "description" : "Super-duper ISP is the home for all your data.", 609 "contact" : { 610 "email" : "superduper@example.com", 611 "uri" : "http://www.example.com" 612 }, 613 "manage" : "http://www.example.com/myaccount.html", 614 "ttl" : 2592000 615 }, 617 "entries" : [ 618 { 619 "name" : "Corporate Mail", 620 "service" : "imap", 621 "group" : "mail-access-1", 622 "priority" : 2, 623 "uri" : "imap:imap.example.com", 624 "tls" : { 625 "required" : true 626 }, 627 "auth" : ["CRAM-MD5"] 628 }, 630 { 631 "name" : "Corporate Mail", 632 "service" : "pop3", 633 "group" : "mail-access-1", 634 "priority" : 1, 635 "host" : "mail.example.com", 636 "port" : 110, 637 "tls" : { 638 "required" : true 639 }, 640 "auth" : ["CRAM-MD5"] 641 }, 643 { 644 "name" : "Corporate Mail", 645 "service" : "submission", 646 "host" : "mail.example.com", 647 "port" : 587, 648 "tls" : { 649 "required" : true 650 }, 651 "auth" : ["CRAM-MD5"] 652 }, 654 { 655 "name" : "Corporate Calendar", 656 "service" : "caldav", 657 "uri" : "https://calendar.example.com", 658 "tls" : { 659 "required" : true, 660 "at-start" : true 661 }, 662 "auth" : ["Digest"] 663 }, 665 { 666 "name" : "Corporate Contacts", 667 "service" : "carddav", 668 "uri" : "https://contacts.example.com", 669 "tls" : { 670 "required" : true, 671 "at-start" : true 672 }, 673 "auth" : ["Digest"] 674 } 675 ] 676 } 678 Appendix C. Example - multiple, alternative mail retrieval services 680 First comes the WebFinger request to retrieve the appropriate link 681 relation. 683 >> Request << 685 GET /.well-known/webfinger? 686 resource=acct:cyrus@example.com& 687 rel=service-configuration HTTP/1.1 688 Host:example.com:443 689 Authorization: basic QmFzZTY0IGlzIGVhc3kgdG8gZGVjb2Rl 691 >> Response << 693 HTTP/1.1 200 OK 694 Date: Wed, 20 Feb 2013 09:32:12 GMT 695 Content-Type: application/jrd+json 696 Content-Length: xxx 698 { 699 "subject" : "acct:cyrus@example.com", 700 "links" : 701 [ 702 { 703 "rel" : "service-configuration", 704 "type" : "application/json", 705 "href" : "https://example.com/service-config" 706 } 707 ] 708 } 710 Next is the retrieval of the automated service configuration document 711 using the URI from the WebFinger link relation. This example shows 712 two different email services: "Primary Mail" (which has both IMAP4 713 and POP3 services available), and "Internal Mail" (which additionally 714 has a private "webmail" service available). An extension member is 715 also specified for the "webmail" service. 717 >> Request << 719 GET /service-config?id=cyrus@example.com HTTP/1.1 720 Host:example.com:443 721 Authorization: basic QmFzZTY0IGlzIGVhc3kgdG8gZGVjb2Rl 723 >> Response << 725 HTTP/1.1 200 OK 726 Date: Wed, 20 Feb 2013 09:32:12 GMT 727 Content-Type: application/json 728 Content-Length: xxx 730 { 731 "provider" : { 732 "name" : "Mail Agrregator ISP", 733 "description" : "Primary and internal email services.", 734 "contact" : { 735 "email" : "emails@example.com", 736 "uri" : "http://www.example.com" 737 }, 738 "manage" : "http://www.example.com/myaccount.html", 739 "ttl" : 2592000 740 }, 742 "entries" : [ 743 { 744 "name" : "Primary Mail", 745 "service" : "imap", 746 "group" : "primary", 747 "priority" : 2, 748 "uri" : "imap:mail.example.com", 749 "tls" : { 750 "required" : true 751 }, 752 "auth" : ["CRAM-MD5"] 753 }, 755 { 756 "name" : "Primary Mail", 757 "service" : "pop3", 758 "group" : "primary", 759 "priority" : 1, 760 "host" : "mail.example.com", 761 "port" : 110, 762 "tls" : { 763 "required" : true 764 }, 765 "auth" : ["CRAM-MD5"] 766 }, 768 { 769 "name" : "Internal Mail", 770 "service" : "imap", 771 "group" : "internal", 772 "priority" : 2, 773 "uri" : "imap:int.example.com", 774 "tls" : { 775 "required" : true 776 }, 777 "auth" : ["CRAM-MD5"] 778 }, 779 { 780 "name" : "Internal Mail", 781 "service" : "pop3", 782 "group" : "internal", 783 "priority" : 1, 784 "host" : "int.example.com", 785 "port" : 110, 786 "tls" : { 787 "required" : true 788 }, 789 "auth" : ["CRAM-MD5"] 790 } 792 { 793 "name" : "Internal Mail", 794 "service" : "{example.com}webmail", 795 "group" : "internal", 796 "priority" : 1, 797 "uri" : "https://int.example.com/webmail", 798 "{example.com}bookmark": "https://int.example.com/webmail" 799 } 800 ] 801 } 803 Appendix D. Example - multiple links 805 TODO: example of webfinger returning multiple "service-configuration" 806 links. 808 Authors' Addresses 810 Andrew McMillan 811 Morphoss Ltd 812 6 Karoro Place 813 Porirua 5024 814 New Zealand 816 EMail: andrew@morphoss.com 817 URI: http://www.morphoss.com/ 818 Cyrus Daboo 819 Apple Inc. 820 1 Infinite Loop 821 Cupertino, CA 95014 822 USA 824 EMail: cyrus@daboo.name 825 URI: http://www.apple.com/