idnits 2.17.1 draft-ietf-appsawg-webfinger-00.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 (July 3, 2012) is 4315 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) == Unused Reference: '4' is defined on line 913, but no explicit reference was found in the text == Unused Reference: '12' is defined on line 938, but no explicit reference was found in the text == Unused Reference: '15' is defined on line 950, but no explicit reference was found in the text == Unused Reference: '17' is defined on line 957, but no explicit reference was found in the text == Unused Reference: '19' is defined on line 964, but no explicit reference was found in the text ** Obsolete normative reference: RFC 2616 (ref. '2') (Obsoleted by RFC 7230, RFC 7231, RFC 7232, RFC 7233, RFC 7234, RFC 7235) ** Obsolete normative reference: RFC 5785 (ref. '3') (Obsoleted by RFC 8615) ** Obsolete normative reference: RFC 5988 (ref. '4') (Obsoleted by RFC 8288) ** Obsolete normative reference: RFC 4627 (ref. '5') (Obsoleted by RFC 7158, RFC 7159) -- Possible downref: Non-RFC (?) normative reference: ref. '9' -- Possible downref: Non-RFC (?) normative reference: ref. '10' -- Possible downref: Non-RFC (?) normative reference: ref. '12' -- Obsolete informational reference (is this intentional?): RFC 4395 (ref. '15') (Obsoleted by RFC 7595) Summary: 4 errors (**), 0 flaws (~~), 6 warnings (==), 5 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Network Working Group Paul E. Jones 3 Internet Draft Gonzalo Salgueiro 4 Intended status: Standards Track Cisco Systems 5 Expires: January 3, 2013 Joseph Smarr 6 Google 7 July 3, 2012 9 WebFinger 10 draft-ietf-appsawg-webfinger-00.txt 12 Abstract 14 This specification defines the WebFinger protocol. WebFinger may be 15 used to discover information about people on the Internet, such as a 16 person's personal profile address, identity service, telephone 17 number, or preferred avatar. WebFinger may also be used to learn 18 information about objects on the network, such as the amount of toner 19 in a printer or the physical location of a server. 21 Status of this Memo 23 This Internet-Draft is submitted in full conformance with the 24 provisions of BCP 78 and BCP 79. 26 Internet-Drafts are working documents of the Internet Engineering 27 Task Force (IETF). Note that other groups may also distribute 28 working documents as Internet-Drafts. The list of current Internet- 29 Drafts is at http://datatracker.ietf.org/drafts/current/. 31 Internet-Drafts are draft documents valid for a maximum of six months 32 and may be updated, replaced, or obsoleted by other documents at any 33 time. It is inappropriate to use Internet-Drafts as reference 34 material or to cite them other than as "work in progress." 36 This Internet-Draft will expire on January 3, 2013. 38 Copyright Notice 40 Copyright (c) 2012 IETF Trust and the persons identified as the 41 document authors. All rights reserved. 43 This document is subject to BCP 78 and the IETF Trust's Legal 44 Provisions Relating to IETF Documents 45 (http://trustee.ietf.org/license-info) in effect on the date of 46 publication of this document. Please review these documents 47 carefully, as they describe your rights and restrictions with respect 48 to this document. Code Components extracted from this document must 49 include Simplified BSD License text as described in Section 4.e of 50 the Trust Legal Provisions and are provided without warranty as 51 described in the Simplified BSD License. 53 Table of Contents 55 1. Introduction...................................................2 56 2. Terminology....................................................3 57 3. Overview.......................................................3 58 4. Example Uses of WebFinger......................................4 59 4.1. Locating a User's Blog....................................4 60 4.2. Retrieving a Person's Contact Information.................7 61 4.3. Simplifying the Login Process.............................8 62 4.4. Retrieving Device Information.............................9 63 5. WebFinger Protocol............................................10 64 5.1. Performing a WebFinger Query.............................10 65 5.2. The Web Host Metadata "resource" Parameter...............11 66 5.3. The Web Host Metadata "rel" Parameter....................13 67 5.4. WebFinger and URIs.......................................14 68 6. The "acct" Link Relation......................................15 69 6.1. Purpose for the "acct" Link Relation.....................15 70 6.2. Example Message Exchange Using the "acct" Link Relation..16 71 7. Cross-Origin Resource Sharing (CORS)..........................17 72 8. Controlling Access to Information.............................17 73 9. Implementation Notes (Non-Normative)..........................18 74 10. Security Considerations......................................18 75 11. IANA Considerations..........................................19 76 11.1. Registration of the "acct" Link Relation Type...........19 77 12. Acknowledgments..............................................19 78 13. References...................................................19 79 13.1. Normative References....................................19 80 13.2. Informative References..................................20 81 Author's Addresses...............................................21 83 1. Introduction 85 There is a utility found on UNIX systems called "finger" [14] that 86 allows a person to access information about another person. The 87 information being queried might be on a computer anywhere in the 88 world. The information returned via "finger" is simply a plain text 89 file that contains unstructured information provided by the queried 90 user. 92 WebFinger borrows the concept of the legacy finger protocol, but 93 introduces a very different approach to sharing information. Rather 94 than returning a simple unstructured text file, Webfinger uses 95 structured documents that contain link relations. These link 96 relations point to information a user or entity on the Internet 97 wishes to expose. For a person, the kinds of information that might 98 be exposed include a personal profile address, identity service, 99 telephone number, or preferred avatar. WebFinger may also be used to 100 learn information about objects on the network, such as the amount of 101 toner in a printer or the physical location of a server. 103 Information returned via WebFinger might be for direct human 104 consumption (e.g., another user's phone number) or it might be used 105 by systems to help carry out some operation (e.g., facilitate logging 106 into a web site by determining a user's identification service). 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 [1]. 114 WebFinger makes heavy use of "Link Relations". Briefly, a Link 115 Relation is an attribute and value pair used on the Internet wherein 116 the attribute identifies the type of link to which the associated 117 value refers. In Hypertext Transfer Protocol (HTTP) [2] and Web 118 Linking Error! Reference source not found., the attribute is a "rel" 119 and the value is an "href". 121 3. Overview 123 WebFinger enables the discovery of information about accounts, 124 devices, and other entities that are associated with web-accessible 125 domains. In essence, there are two steps to discovering such 126 information: 128 1. By querying the domain itself, one can find out how to discover 129 information about accounts, devices, and other associated with 130 that domain. 131 2. By then querying an entity at the domain, one will find links to 132 more detailed information, which can then be queried individually. 134 To enable such functionality, WebFinger makes heavy use of well-known 135 URIs as defined in RFC 5785 [3] and "Link Relations" as defined in 136 RFC 5988 [3]. Briefly, a link is a typed connection between two web 137 resources that are identified by Internationalized Resource 138 Identifiers (IRIs) [13]; this connection consists of a context IRI, a 139 link relation type, a target IRI, and optionally some target 140 attributes, resulting in statements of the form "{context IRI} has a 141 {relation type} resource at {target IRI}, which has {target 142 attributes}". When used in the Link HTTP header, the context IRI is 143 the IRI of the requested resource, the relation type is the value of 144 the "rel" parameter, the target IRI is URI-Reference contained in the 145 Link header, and the target attributes are the parameters such as 146 "hreflang", "media", "title", "title*", "type", and any other link- 147 extension parameters. 149 Thus the framework for WebFinger consists of several building blocks: 151 1. To query the domain, one requests a web host metadata file [11] 152 located at a well-known URI of /.well-known/host-meta at the 153 domain of interest. 154 2. The web server at the domain returns an Extensible Resource 155 Descriptor (XRD) or a JavaScript Object Notation (JSON) Resource 156 Descriptor (JRD) document, including a Link-based Resource 157 Descriptor Document (LRDD) link relation. 158 3. To discover information about accounts, devices, or other entities 159 associated with the domain, one requests the actual Link-based 160 Resource Descriptor Document associated with a particular URI at 161 the domain (e.g., an 'acct' URI, 'http' URI', or 'mailto' URI). 162 4. The web server at the domain returns an XRD or JRD document about 163 the requested URI, which includes specialized link relations 164 pointing to resources that contain more detailed information about 165 the entity. 167 This model is illustrated in the examples under Section 4, then 168 described more formally under Section 5. Note that steps 2 and 3 169 above may be accomplished simultaneously by utilizing the "resource" 170 parameter defined in Section 5.2. 172 4. Example Uses of WebFinger 174 In this section, we describe just a few sample uses for WebFinger and 175 show what the protocol looks like. This is not an exhaustive list of 176 possible uses and the entire section should be considered non- 177 normative. The list of potential use cases is virtually unlimited 178 since a user can share any kind of machine-consumable information via 179 WebFinger. 181 4.1. Locating a User's Blog 183 Assume you receive an email from Bob and he refers to something he 184 posted on his blog, but you do not know where Bob's blog is located. 185 It would be simple to discover the address of Bob's blog if he makes 186 that information available via WebFinger. 188 Let's assume your email client discovers that blog automatically for 189 you. After receiving the message from Bob (bob@example.com), your 190 email client performs the following steps behind the scenes. 192 First, it tries to get the host metadata [11] information for the 193 domain example.com. It does this by issuing the following HTTPS 194 query to example.com: 196 GET /.well-known/host-meta HTTP/1.1 197 Host: example.com 199 The server replies with an XRD [10] document: 201 HTTP/1.1 200 OK 202 Access-Control-Allow-Origin: * 203 Content-Type: application/xrd+xml; charset=UTF-8 205 206 207 210 212 The client then processes the received XRD in accordance with the Web 213 Host Metadata [11] procedures. The client will see the LRDD link 214 relation and issue a query with the user's account URI [6] or other 215 URI that serves as an alias for the account. (The account URI is 216 discussed in Section 4.2.) The query might look like this: 218 GET /lrdd/?uri=acct%3Abob%40example.com HTTP/1.1 219 Host: example.com 221 The server might then respond with a message like this: 223 HTTP/1.1 200 OK 224 Access-Control-Allow-Origin: * 225 Content-Type: application/xrd+xml; charset=UTF-8 227 228 229 2012-03-13T20:56:11Z 230 acct:bob@example.com 231 http://www.example.com/~bob/ 232 234 236 238 240 The email client might take note of the "blog" link relation in the 241 above XRD document that refers to Bob's blog. This URL would then be 242 presented to you so that you could then visit his blog. 244 The email client might also note that Bob has published an avatar 245 link relation and use that picture to represent Bob inside the email 246 client. 248 Note in the above example that an alias is provided that can also be 249 used to return information about the user's account. Had the "http:" 250 URI been used to query for information about Bob, the query would 251 have appeared as: 253 GET /lrdd/?uri= http%3A%2F%2Fwww.example.com%2F~bob%2F HTTP/1.1 254 Host: example.com 256 The response would have been substantially the same, with the subject 257 and alias information changed as necessary. Other information, such 258 as the expiration time might also change, but the set of link 259 relations and properties would be the same with either response. 260 Let's assume, though, that for the above query the client requested a 261 JRD representation for the resource rather than an XRD 262 representation. In that case, the response would have been: 264 HTTP/1.1 200 OK 265 Access-Control-Allow-Origin: * 266 Content-Type: application/json; charset=UTF-8 268 { 269 "expires" : "2012-03-13T20:56:11Z", 270 "subject" : "http://www.example.com/~bob/", 271 "aliases" : 272 [ 273 "acct:bob@example.com" 274 ], 275 "links" : 276 [ 277 { 278 "rel" : "http://webfinger.net/rel/avatar", 279 "href" : "http://www.example.com/~bob/bob.jpg" 280 }, 281 { 282 "rel" : "http://webfinger.net/rel/profile-page", 283 "href" : "http://www.example.com/~bob/" 284 }, 285 { 286 "rel" : "http://packetizer.com/rel/blog", 287 "href" : "http://blogs.example.com/bob/" 288 } 289 ] 290 } 292 4.2. Retrieving a Person's Contact Information 294 Assume you have Alice in your address book, but her phone number 295 appears to be invalid. You could use WebFinger to find her current 296 phone number and update your address book. 298 Let's assume you have a web-based address book that you wish to 299 update. When you instruct the address book to pull Alice's current 300 contact information, the address book might issue a query like this 301 to get host metadata information for example.com: 303 GET /.well-known/host-meta.json HTTP/1.1 304 Host: example.com 306 Note the address book is looking for a JSON [5] representation, 307 whereas we used XML in the previous example. 309 The server might reply with something like this: 311 HTTP/1.1 200 OK 312 Access-Control-Allow-Origin: * 313 Content-Type: application/json; charset=UTF-8 315 { 316 "links" : 317 [ 318 { 319 "rel" : "lrdd", 320 "type" : "application/json", 321 "template" : 322 "https://example.com/lrdd/?format=json&uri={uri}" 323 } 324 ] 325 } 327 The client processes the response as described in RFC 6415 [11]. It 328 will process the LRDD link relation using Alice's account URI by 329 issuing this query: 331 GET /lrdd/?format=json&uri=acct%3Aalice%40example.com HTTP/1.1 332 Host: example.com 334 The server might return a response like this: 336 HTTP/1.1 200 OK 337 Access-Control-Allow-Origin: * 338 Content-Type: application/json; charset=UTF-8 340 { 341 "expires" : "2012-03-13T20:56:11Z", 342 "subject" : "acct:alice@example.com", 343 "links" : 344 [ 345 { 346 "rel" : "http://webfinger.net/rel/avatar", 347 "href" : "http://example.com/~alice/alice.jpg" 348 }, 349 { 350 "rel" : "vcard", 351 "href" : "http://example.com/~alice/alice.vcf" 352 } 353 ] 354 } 356 With this response, the address book might see the vcard [16] link 357 relation and use that file to offer you updated contact information. 359 4.3. Simplifying the Login Process 361 OpenID (http://www.openid.net) is great for allowing users to log 362 into a web site, though one criticism is that it is challenging for 363 users to remember the URI they are assigned. WebFinger can help 364 address this issue by allowing users to use user@domain-style 365 addresses. Using a user's account URI, a web site can perform a 366 query to discover the associated OpenID identifier for a user. 368 Let's assume Carol is trying to use OpenID to log into a blog. The 369 blog server might issue the following query to get the host metadata 370 information: 372 GET /.well-known/host-meta.json HTTP/1.1 373 Host: example.com 375 The response that comes back is similar to the previous example: 377 HTTP/1.1 200 OK 378 Access-Control-Allow-Origin: * 379 Content-Type: application/json; charset=UTF-8 380 { 381 "expires" : "2012-03-13T20:56:11Z", 382 "links" : 383 [ 384 { 385 "rel" : "lrdd", 386 "type" : "application/json", 387 "template" : 388 "https://example.com/lrdd/?format=json&uri={uri}" 389 } 391 ] 392 } 394 The blog server processes the response as described in RFC 6415. It 395 will process the LRDD link relation using Carol's account URI by 396 issuing this query: 398 GET /lrdd/?format=json&uri=acct%3Acarol%40example.com HTTP/1.1 400 The server might return a response like this: 402 HTTP/1.1 200 OK 403 Access-Control-Allow-Origin: * 404 Content-Type: application/json; charset=UTF-8 406 { 407 "subject" : "acct:carol@example.com", 408 "links" : 409 [ 410 { 411 "rel" : "http://webfinger.net/rel/avatar", 412 "href" : "http://example.com/~alice/alice.jpg" 413 }, 414 { 415 "rel" : "http://specs.openid.net/auth/2.0/provider", 416 "href" : "https://openid.example.com/carol" 417 } 418 ] 419 } 421 At this point, the blog server knows that Carol's OpenID identifier 422 is https://openid.example.com/carol and could then proceed with the 423 login process as usual. 425 4.4. Retrieving Device Information 427 While the examples thus far have been focused on information about 428 humans, WebFinger does not limit queries to only those that use the 429 account URI scheme. Any URI scheme that contains domain information 430 MAY be used with WebFinger. Let's suppose there are devices on the 431 network like printers and you would like to check the current toner 432 level for a particular printer identified via the URI like 433 device:p1.example.com. While the "device" URI scheme is not 434 presently specified, we use it here for illustrative purposes. 436 Following the procedures similar to those above, a query may be 437 issued to get link relations specific to this URI like this: 439 GET /lrdd/?format=json&uri=device%3Ap1.example.com HTTP/1.1 440 Host: example.com 442 The link relations that are returned may be quite different than 443 those for user accounts. Perhaps we may see a response like this: 445 HTTP/1.1 200 OK 446 Access-Control-Allow-Origin: * 447 Content-Type: application/json; charset=UTF-8 449 { 450 "subject" : "device:p1.example.com", 451 "links" : 452 [ 453 { 454 "rel" : "tipsi", 455 "href" : "http://192.168.1.5/npap/" 456 } 457 ] 458 } 460 While this example is entirely fictitious, you can imagine that 461 perhaps the Transport Independent, Printer/System Interface [18] may 462 be enhanced with a web interface that allows a device that 463 understands the TIP/SI web interface specification to query the 464 printer for toner levels. 466 5. WebFinger Protocol 468 WebFinger does not actually introduce a new protocol, per se. 469 Rather, it builds upon the existing Web Host Metadata [11] 470 specification and leverages the Cross-Origin Resource Sharing (CORS) 471 [9] specification. 473 5.1. Performing a WebFinger Query 475 The first step a client must perform in executing a WebFinger query 476 is to query for the host metadata using HTTPS or HTTP. The 477 procedures are defined in the Web Host Metadata [11] specification. 479 WebFinger clients MUST locate the LRDD link relation, if present, and 480 perform a query for that link relation, if present. All other link 481 templates found must be processed to form a complete resource 482 descriptor. The processing rules in Section 4.2 of RFC 6415 MUST be 483 followed. 485 WebFinger servers MUST accept requests for both XRD [10] and JRD [11] 486 documents. The default representation returned by the server MUST be 487 an XRD document, but a JRD document MUST be returned if the client 488 explicitly requests it by using /.well-known/host-meta.json or 489 includes an Accept header in the HTTP request with a type of 490 "application/json" [5]. 492 If the client requests a JRD document when querying for host 493 metadata, the WebFinger server can assume that the client will want a 494 JRD documents when querying the LRDD resource. As such, when the 495 WebFinger server returns a JRD document containing host metadata it 496 should include a URI for an LRDD resource that can return a JRD 497 document and MAY include a URI for an LRDD resource that will return 498 an XRD document. 500 If the client queries the LRDD resource and provides a URI for which 501 the server has no information, the server MUST return a 404 status 502 code. Likewise, any query to a URI in the resource descriptor that 503 is unknown to the server MUST result in the server returning a 404 504 status code. 506 WebFinger servers MAY include cache validators in a response to 507 enable conditional requests by clients and/or expiration times as per 508 RFC 2616 section 13. 510 5.2. The Web Host Metadata "resource" Parameter 512 In addition to the normal processing logic for processing host 513 metadata information, WebFinger defines the "resource" parameter for 514 querying for host metadata and returning all of the link relations 515 from LRDD and other resource-specific link templates in a single 516 query. This resource essentially pushes the work to the server to 517 form a complete resource descriptor for the specified resource. 519 WebFinger servers compliant with this specification MUST support for 520 the "resource" parameter as a means of improving performance and 521 reducing client complexity. Note that an RFC 6415-compliant server 522 might not implement the "resource" parameter, though the server would 523 respond to queries from the client as described in RFC 6415. Thus, 524 WebFinger clients MUST check the server response to ensure that the 525 "resource" parameter is supported as explained below. 527 To utilize the host-meta "resource" parameter, a WebFinger client 528 issues a request to /.well-known/host-meta or /.well-known/host- 529 meta.json as usual, but then appends a "resource" parameter as shown 530 in this example: 532 GET /.well-known/host-meta.json?resource=\ 533 acct%3Abob%40example.com HTTP/1.1 534 Host: example.com 536 Note that the "\" character shown above is to indicate that the line 537 breaks at this point and continues on the next line. This was shown 538 only to avoid line wrapping in this document and is not a part of the 539 HTTP protocol. 541 When processing this request, the WebFinger server MUST 543 * Return a 404 status code if the URI provided in the resource 544 parameter is unknown to the server; and 546 * Set the "Subject" returned in the response to the value of the 547 "resource" parameter if the URI provided in the resource 548 parameter is known to the server 550 The WebFinger client can verify support for the "resource" parameter 551 by checking the value of the Subject returned in the response. If 552 the Subject matches the value of the "resource" parameter, then the 553 "resource" parameter is supported by the server. 555 For illustrative purposes, the following is an example usage of the 556 "resource" parameter that aligns with the example in Section 1.1.1 of 557 RFC 6415. The WebFinger client would issue this request: 559 GET /.well-known/host-meta.json?resource=\ 560 http%3A%2F%2Fexample.com%2Fxy HTTP/1.1 561 Host: example.com 563 The WebFinger server would reply with this response: 565 HTTP/1.1 200 OK 566 Access-Control-Allow-Origin: * 567 Content-Type: application/json; charset=UTF-8 569 { 570 "subject" : "http://example.com/xy", 571 "properties" : 572 { 573 "http://spec.example.net/color" : "red" 574 }, 575 "links" : 576 [ 577 { 578 "rel" : "hub", 579 "href" : "http://example.com/hub" 580 }, 581 { 582 "rel" : "hub", 583 "href" : "http://example.com/another/hub" 584 }, 585 { 586 "rel" : "author", 587 "href" : "http://example.com/john" 588 }, 589 { 590 "rel" : "author", 591 "href" : "http://example.com/author?\ 592 q=http%3A%2F%2Fexample.com%2Fxy" 593 } 594 ] 595 } 597 5.3. The Web Host Metadata "rel" Parameter 599 WebFinger also defines the "rel" parameter for use when querying for 600 host metadata. It is used to return a subset of the information that 601 would otherwise be returned without the "rel" parameter. When the 602 "rel" parameter is used, only the link relations that match the 603 space-separated list of link relations provided via "rel" are 604 included in the list of links returned in the resource descriptor. 605 All other information normally present in a resource descriptor is 606 present in the resource descriptor, even when "rel" is employed. 608 The purpose of the "rel" parameter is to return a subset of 609 resource's link relations. It is not intended to reduce the work 610 required of a server to produce a response. That said, use of the 611 parameter might reduce processing requirements on either the client 612 or server, and it might also reduce the bandwidth required to convey 613 the partial resource descriptor, especially if there are numerous 614 link relation values to convey for a given resource. 616 Support for the "rel" parameter is OPTIONAL, but support is 617 RECOMMENDED for both the host-meta resource and the LRDD resource. 619 For illustrative purposes, the following is an example usage of the 620 "rel" parameter that aligns with the example in Section 1.1.1 of RFC 621 6415. The WebFinger client would issue this request to receive links 622 that are of the type "hub" and "copyright": 624 GET /.well-known/host-meta.json?resource=\ 625 http%3A%2F%2Fexample.com%2Fxy&rel=hub%20copyright HTTP/1.1 626 Host: example.com 628 The WebFinger server would reply with this response: 630 HTTP/1.1 200 OK 631 Access-Control-Allow-Origin: * 632 Content-Type: application/json; charset=UTF-8 633 { 634 "subject" : "http://example.com/xy", 635 "properties" : 636 { 637 "http://spec.example.net/color" : "red" 638 }, 639 "links" : 640 [ 641 { 642 "rel" : "hub", 643 "href" : "http://example.com/hub" 644 }, 645 { 646 "rel" : "hub", 647 "href" : "http://example.com/another/hub" 648 } 649 ] 650 } 652 Note that in this example, the "author" links are removed, though all 653 other content is present. Since there were no "copyright" links, 654 none are returned. 656 In the event that a client requests links for link relations that are 657 not defined for the specified resource, a resource descriptor MUST be 658 returned, void of any links. When a JRD is returned, the "links" 659 array MAY be either absent or empty. The server MUST NOT return a 660 404 status code when a particular link relation specified via "rel" 661 is not defined for the resource, as a 404 status code is reserved for 662 indicating that the resource itself (e.g., as indicated via the 663 "resource" parameter) does not exist. 665 5.4. WebFinger and URIs 667 Requests for both LRDD documents and hostmeta files can include a 668 parameter specifying the URI of an account, device, or other entity 669 (for LRDD this is the "uri" parameter as defined by the operative XRD 670 or JRD template, for hostmeta this is the "resource" parameter). 671 WebFinger itself is agnostic regarding the scheme of such a URI: it 672 could be an "acct" URI as defined in the next section, an "http" or 673 "https" URI, a "mailto" URI, or some other scheme. 675 For resources associated with a user account at a domain, use of the 676 "acct" URI scheme [7] is RECOMMENDED, since it explicitly identifies 677 an account accessible via WebFinger. Further, the "acct" URI scheme 678 is not associated other protocols as, by way of example, the "mailto" 679 URI scheme is associated with email. Since not every domain offers 680 email service, using the "mailto" URI scheme [8] is not ideal for 681 identifying user accounts across all domains. That said, use of the 682 "mailto" URI scheme would be ideal for use with WebFinger to discover 683 mail server configuration information for a user, for example. 685 A domain MAY utilize one or more URIs that serve as aliases for the 686 user's account, such as URIs that use the "http" URI scheme [2]. A 687 WebFinger server MUST return substantially the same response to both 688 an "acct" URI and any alias URI for the account, including the same 689 set of link relations and properties. In addition, the server SHOULD 690 include the entire list aliases for the user's account in the XRD or 691 JRD. 693 6. The "acct" Link Relation 695 6.1. Purpose for the "acct" Link Relation 697 Users of some services might have an "acct" URI that looks 698 significantly different from his or her email address, perhaps using 699 an entirely different domain name. It is also possible for a user to 700 have multiple accounts that a user wants to have cross-referenced 701 from another account. To address both of these needs, this 702 specification defines the "acct" link relation. 704 The "acct" link relation allows a WebFinger server to reference one 705 or more other user account URIs from within a user account. The 706 "acct" link relation is intended to allow a client to incorporate 707 additional link relations by reference to produce a complete set of 708 link relations for a user. Any newly discovered link relations found 709 by querying the referenced account SHOULD be merged into the resource 710 descriptor document at the point where the "acct" link relation was 711 inserted. 713 Note that the "acct" link relation does not replace the use of 714 standard HTTP 3xx response codes to indicate the new temporary or 715 permanent location of a user account. If a user account is moved to 716 a different location, then a 3xx response code SHOULD be used. 718 Since an account may make a reference to one or more different 719 accounts, WebFinger clients MUST take steps to avoid loops wherein 720 two account URIs, directly or indirectly, refer the client to each 721 other. 723 There are no limits on the number of "acct" link relations that might 724 be returned in a WebFinger query. 726 An "acct" link relation used within the context of a WebFinger query 727 for a user's account MUST NOT return "acct" link relations for 728 another user. 730 6.2. Example Message Exchange Using the "acct" Link Relation 732 Consider the following non-normative example. 734 Suppose Alice receives an email from bob@example.net. While Bob's 735 email identifier might be in the example.net domain, he holds a user 736 account in the example.com domain and another account in the 737 example.org domain. His email provider may provide WebFinger 738 services to enable redirecting Alice when she queries for 739 acct:bob@example.net. 741 Suppose Alice's client issues the following request: 743 GET /.well-known/host-meta.json?resource=\ 744 acct%3Abob%40example.net HTTP/1.1 745 Host: example.net 747 The response that Alice's client receives back might be: 749 HTTP/1.1 200 OK 750 Access-Control-Allow-Origin: * 751 Content-Type: application/json; charset=UTF-8 753 { 754 "subject" : "acct:bob@example.net", 755 "links" : 756 [ 757 { 758 "rel" : "acct", 759 "href" : "acct:bob@example.com" 760 }, 761 { 762 "rel" : "acct", 763 "href" : "acct:bob@example.org" 764 }, 766 { 767 "rel" : "acct", 768 "href" : "mailto:bob@example.net" 769 } 770 ] 771 } 773 Alice's WebFinger client could then perform queries against the URIs 774 acct:bob@example.com, acct:bob@example.org, and 775 mailto:bob@example.net in order to get the information Alice is 776 seeking. 778 7. Cross-Origin Resource Sharing (CORS) 780 WebFinger is most useful when it is accessible without restrictions 781 on the Internet, and that includes web browsers. Therefore, 782 WebFinger servers MUST support Cross-Origin Resource Sharing (CORS) 783 [9] when serving content intended for public consumption. 784 Specifically, all queries to /.well-known/host-meta, /.well- 785 known/host-meta.json, and to the LRDD URI must include the following 786 HTTP header in the response: 788 Access-Control-Allow-Origin: * 790 Enterprise WebFinger servers that wish to restrict access to 791 information from external entities SHOULD use a more restrictive 792 Access-Control-Allow-Origin header and MAY exclude the header 793 entirely. 795 8. Controlling Access to Information 797 As with all web resources, access to the Host Metadata resource and 798 the LRDD resource MAY require authentication. Further, failure to 799 provide required credentials MAY result in the server forbidding 800 access or providing a different response than had the client 801 authenticated with the server. 803 Likewise, a server MAY provide different responses to different 804 clients based on other factors, such as whether the client is inside 805 or outside a corporate network. As a concrete example, a query 806 performed on the internal corporate network might return link 807 relations to employee pictures whereas link relations for employee 808 pictures might not be provided to external entities. 810 Further, link relations provided in a WebFinger server response MAY 811 point to web resources that impose access restrictions. For example, 812 it is possible that the aforementioned corporate server may provide 813 both internal and external entities with URIs to employee pictures, 814 but further authentication MAY be required in order for the WebFinger 815 client to access those resources if the request comes from outside 816 the corporate network. 818 The decisions made with respect to what set of link relations a 819 WebFinger server provides to one client versus another and what 820 resources require further authentication, as well as the specific 821 authentication mechanisms employed, are outside the scope of this 822 document. 824 9. Implementation Notes (Non-Normative) 826 A user should not be required to enter the "acct" URI scheme name 827 along with his account identifier into any WebFinger client. Rather, 828 the WebFinger client should accept identifiers that are void of the 829 "acct:" portion of the identifier. Composing a properly formatted 830 "acct" URI is the responsibility of the WebFinger client. 832 10. Security Considerations 834 All of the security considerations applicable to Web Host Metadata 835 [11] and Cross-Origin Resource Sharing [9] are also applicable to 836 this specification. Of particular importance is the recommended use 837 of HTTPS to ensure that information is not modified during transit. 838 Clients should verify that the certificate used on an HTTPS 839 connection is valid. 841 When using HTTP to request an XRD document, WebFinger clients SHOULD 842 verify the XRD document's signature, if present, to ensure that the 843 XRD document has not been modified. Additionally, WebFinger servers 844 SHOULD include a signature for XRD documents served over HTTP. 846 Service providers and users should be aware that placing information 847 on the Internet accessible through WebFinger means that any user can 848 access that information. While WebFinger can be an extremely useful 849 tool for allowing quick and easy access to one's avatar, blog, or 850 other personal information, users should understand the risks, too. 851 If one does not wish to share certain information with the world, do 852 not allow that information to be freely accessible through WebFinger. 854 The aforementioned word of caution is perhaps worth emphasizing again 855 with respect to dynamic information one might wish to share, such as 856 the current location of a user. WebFinger can be a powerful tool 857 used to assemble information about a person all in one place, but 858 service providers and users should be mindful of the nature of that 859 information shared and the fact that it might be available for the 860 entire world to see. Sharing location information, for example, 861 would potentially put a person in danger from any individual who 862 might seek to inflict harm on that person. 864 The easy access to user information via WebFinger was a design goal 865 of the protocol, not a limitation. If one wishes to limit access to 866 information available via WebFinger, such as a WebFinger server for 867 use inside a corporate network, the network administrator must take 868 measures necessary to limit access from outside the network. Using 869 standard methods for securing web resources, network administrators 870 do have the ability to control access to resources that might return 871 sensitive information. Further, WebFinger servers can be employed in 872 such a way as to require authentication and prevent disclosure of 873 information to unauthorized entities. 875 11. IANA Considerations 877 RFC Editor: Please replace QQQQ in the following two sub-sections 878 with a reference to this RFC. 880 11.1. Registration of the "acct" Link Relation Type 882 Relation Name: acct 884 Description: A link relation that refers to a user's WebFinger 885 account identifier. 887 Reference: RFC QQQQ 889 Notes: 891 Application Data: 893 12. Acknowledgments 895 The authors would like to acknowledge Eran Hammer-Lahav, Blaine Cook, 896 Brad Fitzpatrick, Laurent-Walter Goix, Joe Clarke, Mike Jones, and 897 Peter Saint-Andre for their invaluable input. 899 13. References 901 13.1. Normative References 903 [1] Bradner, S., "Key words for use in RFCs to Indicate Requirement 904 Levels", BCP 14, RFC 2119, March 1997. 906 [2] Fielding, R., Gettys, J., Mogul, J., Frystyk, H., 907 Masinter, L., Leach, P., and T. Berners-Lee, "Hypertext 908 Transfer Protocol -- HTTP/1.1", RFC 2616, June 1999. 910 [3] Nottingham, M., Hammer-Lahav, E., "Defining Well-Known Uniform 911 Resource Identifiers (URIs)", RFC 5785, April 2010. 913 [4] Nottingham, M., "Web Linking", RFC 5988, October 2010. 915 [5] Crockford, D., "The application/json Media Type for 916 JavaScript Object Notation (JSON)", RFC 4627, July 2006. 918 [6] Berners-Lee, T., Fielding, R., and Masinter, L., "Uniform 919 Resource Identifier (URI): Generic Syntax", STD 66, RFC 3986, 920 January 2005. 922 [7] Saint-Andre, P., "The 'acct' URI Scheme", draft-saintandre- 923 acct-uri-01, July 2012. 925 [8] Duerst, M., Masinter, L., and J. Zawinski, "The 'mailto' URI 926 Scheme", RFC 6068, October 2010. 928 [9] Van Kesteren, A., "Cross-Origin Resource Sharing", W3C CORS 929 http://www.w3.org/TR/cors/, July 2010. 931 [10] Hammer-Lahav, E. and W. Norris, "Extensible Resource Descriptor 932 (XRD) Version 1.0", http://docs.oasis- 933 open.org/xri/xrd/v1.0/xrd-1.0.html. 935 [11] Hammer-Lahav, E. and Cook, B., "Web Host Metadata", RFC 6415, 936 October 2011. 938 [12] American National Standards Institute, "Coded Character Set - 939 7-bit American Standard Code for Information Interchange", ANSI 940 X3.4, 1986. 942 [13] Duerst, M., "Internationalized Resource Identifiers (IRIs)", 943 RFC 3987, January 2005. 945 13.2. Informative References 947 [14] Zimmerman, D., "The Finger User Information Protocol", RFC 948 1288, December 1991. 950 [15] Hansen, T., Hardie, T., and L. Masinter, "Guidelines and 951 Registration Procedures for New URI Schemes", BCP 35, RFC 4395, 952 February 2006. 954 [16] Perreault, S., "vCard Format Specification", RFC 6350, August 955 2011. 957 [17] Internet Assigned Numbers Authority (IANA) Registry, "Uniform 958 Resource Identifier (URI) Schemes", 959 . 961 [18] "Transport Independent, Printer/System Interface", IEEE Std 962 1284.1-1997, 1997. 964 [19] Hoffman, P., Yergeau, F., "UTF-16, an encoding of ISO 10646", 965 RFC 2781, February 2000. 967 Author's Addresses 969 Paul E. Jones 970 Cisco Systems, Inc. 971 7025 Kit Creek Rd. 972 Research Triangle Park, NC 27709 973 USA 975 Phone: +1 919 476 2048 976 Email: paulej@packetizer.com 977 IM: xmpp:paulej@packetizer.com 979 Gonzalo Salgueiro 980 Cisco Systems, Inc. 981 7025 Kit Creek Rd. 982 Research Triangle Park, NC 27709 983 USA 985 Phone: +1 919 392 3266 986 Email: gsalguei@cisco.com 987 IM: xmpp:gsalguei@cisco.com 989 Joseph Smarr 990 Google 992 Email: jsmarr@google.com