idnits 2.17.1 draft-jones-appsawg-webfinger-06.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 18, 2012) is 4330 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 958, 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. '8' -- Possible downref: Non-RFC (?) normative reference: ref. '9' -- Possible downref: Non-RFC (?) normative reference: ref. '11' -- Possible downref: Non-RFC (?) normative reference: ref. '12' -- Obsolete informational reference (is this intentional?): RFC 4395 (ref. '16') (Obsoleted by RFC 7595) Summary: 4 errors (**), 0 flaws (~~), 2 warnings (==), 6 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: December 18, 2012 Joseph Smarr 6 Google 7 June 18, 2012 9 WebFinger 10 draft-jones-appsawg-webfinger-06.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 December 18, 2012. 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" URI................................................15 69 7. The "acct" Link Relation......................................16 70 7.1. Purpose for the "acct" Link Relation.....................16 71 7.2. Example Message Exchange Using the "acct" Link Relation..16 72 8. Cross-Origin Resource Sharing (CORS)..........................17 73 9. Controlling Access to Information.............................17 74 10. Implementation Notes (Non-Normative).........................18 75 11. Security Considerations......................................18 76 12. IANA Considerations..........................................19 77 12.1. Registration of the "acct" URI scheme name..............19 78 12.2. Registration of the "acct" Link Relation Type...........20 79 13. Acknowledgments..............................................20 80 14. References...................................................20 81 14.1. Normative References....................................20 82 14.2. Informative References..................................21 83 Author's Addresses...............................................22 85 1. Introduction 87 There is a utility found on UNIX systems called "finger" [15] that 88 allows a person to access information about another person. The 89 information being queried might be on a computer anywhere in the 90 world. The information returned via "finger" is simply a plain text 91 file that contains unstructured information provided by the queried 92 user. 94 WebFinger borrows the concept of the legacy finger protocol, but 95 introduces a very different approach to sharing information. Rather 96 than returning a simple unstructured text file, Webfinger uses 97 structured documents that contain link relations. These link 98 relations point to information a user or entity on the Internet 99 wishes to expose. For a person, the kinds of information that might 100 be exposed include a personal profile address, identity service, 101 telephone number, or preferred avatar. WebFinger may also be used to 102 learn information about objects on the network, such as the amount of 103 toner in a printer or the physical location of a server. 105 Information returned via WebFinger might be for direct human 106 consumption (e.g., another user's phone number) or it might be used 107 by systems to help carry out some operation (e.g., facilitate logging 108 into a web site by determining a user's identification service). 110 2. Terminology 112 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 113 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 114 document are to be interpreted as described in RFC 2119 [1]. 116 WebFinger makes heavy use of "Link Relations". Briefly, a Link 117 Relation is an attribute and value pair used on the Internet wherein 118 the attribute identifies the type of link to which the associated 119 value refers. In Hypertext Transfer Protocol (HTTP) [2] and Web 120 Linking Error! Reference source not found., the attribute is a "rel" 121 and the value is an "href". 123 3. Overview 125 WebFinger enables the discovery of information about accounts, 126 devices, and other entities that are associated with web-accessible 127 domains. In essence, there are two steps to discovering such 128 information: 130 1. By querying the domain itself, one can find out how to discover 131 information about accounts, devices, and other associated with 132 that domain. 133 2. By then querying an entity at the domain, one will find links to 134 more detailed information, which can then be queried individually. 136 To enable such functionality, WebFinger makes heavy use of well-known 137 URIs as defined in RFC 5785 [3] and "Link Relations" as defined in 138 RFC 5988 [3]. Briefly, a link is a typed connection between two web 139 resources that are identified by Internationalized Resource 140 Identifiers (IRIs) [14]; this connection consists of a context IRI, a 141 link relation type, a target IRI, and optionally some target 142 attributes, resulting in statements of the form "{context IRI} has a 143 {relation type} resource at {target IRI}, which has {target 144 attributes}". When used in the Link HTTP header, the context IRI is 145 the IRI of the requested resource, the relation type is the value of 146 the "rel" parameter, the target IRI is URI-Reference contained in the 147 Link header, and the target attributes are the parameters such as 148 "hreflang", "media", "title", "title*", "type", and any other link- 149 extension parameters. 151 Thus the framework for WebFinger consists of several building blocks: 153 1. To query the domain, one requests a web host metadata file [10] 154 located at a well-known URI of /.well-known/host-meta at the 155 domain of interest. 156 2. The web server at the domain returns an Extensible Resource 157 Descriptor (XRD) or a JavaScript Object Notation (JSON) Resource 158 Descriptor (JRD) document, including a Link-based Resource 159 Descriptor Document (LRDD) link relation. 160 3. To discover information about accounts, devices, or other entities 161 associated with the domain, one requests the actual Link-based 162 Resource Descriptor Document associated with a particular URI at 163 the domain (e.g., an 'acct' URI, 'http' URI', or 'mailto' URI). 164 4. The web server at the domain returns an XRD or JRD document about 165 the requested URI, which includes specialized link relations 166 pointing to resources that contain more detailed information about 167 the entity. 169 This model is illustrated in the examples under Section 4, then 170 described more formally under Section 5. Note that steps 2 and 3 171 above may be accomplished simultaneously by utilizing the "resource" 172 parameter defined in Section 5.2. 174 4. Example Uses of WebFinger 176 In this section, we describe just a few sample uses for WebFinger and 177 show what the protocol looks like. This is not an exhaustive list of 178 possible uses and the entire section should be considered non- 179 normative. The list of potential use cases is virtually unlimited 180 since a user can share any kind of machine-consumable information via 181 WebFinger. 183 4.1. Locating a User's Blog 185 Assume you receive an email from Bob and he refers to something he 186 posted on his blog, but you do not know where Bob's blog is located. 187 It would be simple to discover the address of Bob's blog if he makes 188 that information available via WebFinger. 190 Let's assume your email client discovers that blog automatically for 191 you. After receiving the message from Bob (bob@example.com), your 192 email client performs the following steps behind the scenes. 194 First, it tries to get the host metadata [10] information for the 195 domain example.com. It does this by issuing the following HTTPS 196 query to example.com: 198 GET /.well-known/host-meta HTTP/1.1 199 Host: example.com 201 The server replies with an XRD [9] document: 203 HTTP/1.1 200 OK 204 Access-Control-Allow-Origin: * 205 Content-Type: application/xrd+xml; charset=UTF-8 207 208 209 212 214 The client then processes the received XRD in accordance with the Web 215 Host Metadata [10] procedures. The client will see the LRDD link 216 relation and issue a query with the user's account URI [6] or other 217 URI that serves as an alias for the account. (The account URI is 218 discussed in Section 4.2.) The query might look like this: 220 GET /lrdd/?uri=acct%3Abob%40example.com HTTP/1.1 221 Host: example.com 223 The server might then respond with a message like this: 225 HTTP/1.1 200 OK 226 Access-Control-Allow-Origin: * 227 Content-Type: application/xrd+xml; charset=UTF-8 229 230 231 2012-03-13T20:56:11Z 232 acct:bob@example.com 233 http://www.example.com/~bob/ 234 236 238 240 242 The email client might take note of the "blog" link relation in the 243 above XRD document that refers to Bob's blog. This URL would then be 244 presented to you so that you could then visit his blog. 246 The email client might also note that Bob has published an avatar 247 link relation and use that picture to represent Bob inside the email 248 client. 250 Note in the above example that an alias is provided that can also be 251 used to return information about the user's account. Had the "http:" 252 URI been used to query for information about Bob, the query would 253 have appeared as: 255 GET /lrdd/?uri= http%3A%2F%2Fwww.example.com%2F~bob%2F HTTP/1.1 256 Host: example.com 258 The response would have been substantially the same, with the subject 259 and alias information changed as necessary. Other information, such 260 as the expiration time might also change, but the set of link 261 relations and properties would be the same with either response. 262 Let's assume, though, that for the above query the client requested a 263 JRD representation for the resource rather than an XRD 264 representation. In that case, the response would have been: 266 HTTP/1.1 200 OK 267 Access-Control-Allow-Origin: * 268 Content-Type: application/json; charset=UTF-8 270 { 271 "expires" : "2012-03-13T20:56:11Z", 272 "subject" : "http://www.example.com/~bob/", 273 "aliases" : 274 [ 275 "acct:bob@example.com" 276 ], 277 "links" : 278 [ 279 { 280 "rel" : "http://webfinger.net/rel/avatar", 281 "href" : "http://www.example.com/~bob/bob.jpg" 282 }, 283 { 284 "rel" : "http://webfinger.net/rel/profile-page", 285 "href" : "http://www.example.com/~bob/" 286 }, 287 { 288 "rel" : "http://packetizer.com/rel/blog", 289 "href" : "http://blogs.example.com/bob/" 290 } 292 ] 293 } 295 4.2. Retrieving a Person's Contact Information 297 Assume you have Alice in your address book, but her phone number 298 appears to be invalid. You could use WebFinger to find her current 299 phone number and update your address book. 301 Let's assume you have a web-based address book that you wish to 302 update. When you instruct the address book to pull Alice's current 303 contact information, the address book might issue a query like this 304 to get host metadata information for example.com: 306 GET /.well-known/host-meta.json HTTP/1.1 307 Host: example.com 309 Note the address book is looking for a JSON [5] representation, 310 whereas we used XML in the previous example. 312 The server might reply with something like this: 314 HTTP/1.1 200 OK 315 Access-Control-Allow-Origin: * 316 Content-Type: application/json; charset=UTF-8 318 { 319 "links" : 320 [ 321 { 322 "rel" : "lrdd", 323 "type" : "application/json", 324 "template" : 325 "https://example.com/lrdd/?format=json&uri={uri}" 326 } 327 ] 328 } 330 The client processes the response as described in RFC 6415 [10]. It 331 will process the LRDD link relation using Alice's account URI by 332 issuing this query: 334 GET /lrdd/?format=json&uri=acct%3Aalice%40example.com HTTP/1.1 335 Host: example.com 337 The server might return a response like this: 339 HTTP/1.1 200 OK 340 Access-Control-Allow-Origin: * 341 Content-Type: application/json; charset=UTF-8 343 { 344 "expires" : "2012-03-13T20:56:11Z", 345 "subject" : "acct:alice@example.com", 346 "links" : 347 [ 348 { 349 "rel" : "http://webfinger.net/rel/avatar", 350 "href" : "http://example.com/~alice/alice.jpg" 351 }, 352 { 353 "rel" : "vcard", 354 "href" : "http://example.com/~alice/alice.vcf" 355 } 356 ] 357 } 359 With this response, the address book might see the vcard [17] link 360 relation and use that file to offer you updated contact information. 362 4.3. Simplifying the Login Process 364 OpenID (http://www.openid.net) is great for allowing users to log 365 into a web site, though one criticism is that it is challenging for 366 users to remember the URI they are assigned. WebFinger can help 367 address this issue by allowing users to use user@domain-style 368 addresses. Using a user's account URI, a web site can perform a 369 query to discover the associated OpenID identifier for a user. 371 Let's assume Carol is trying to use OpenID to log into a blog. The 372 blog server might issue the following query to get the host metadata 373 information: 375 GET /.well-known/host-meta.json HTTP/1.1 376 Host: example.com 378 The response that comes back is similar to the previous example: 380 HTTP/1.1 200 OK 381 Access-Control-Allow-Origin: * 382 Content-Type: application/json; charset=UTF-8 383 { 384 "expires" : "2012-03-13T20:56:11Z", 385 "links" : 386 [ 387 { 388 "rel" : "lrdd", 389 "type" : "application/json", 390 "template" : 391 "https://example.com/lrdd/?format=json&uri={uri}" 392 } 393 ] 394 } 396 The blog server processes the response as described in RFC 6415. It 397 will process the LRDD link relation using Carol's account URI by 398 issuing this query: 400 GET /lrdd/?format=json&uri=acct%3Acarol%40example.com HTTP/1.1 402 The server might return a response like this: 404 HTTP/1.1 200 OK 405 Access-Control-Allow-Origin: * 406 Content-Type: application/json; charset=UTF-8 408 { 409 "subject" : "acct:carol@example.com", 410 "links" : 411 [ 412 { 413 "rel" : "http://webfinger.net/rel/avatar", 414 "href" : "http://example.com/~alice/alice.jpg" 415 }, 416 { 417 "rel" : "http://specs.openid.net/auth/2.0/provider", 418 "href" : "https://openid.example.com/carol" 419 } 420 ] 421 } 423 At this point, the blog server knows that Carol's OpenID identifier 424 is https://openid.example.com/carol and could then proceed with the 425 login process as usual. 427 4.4. Retrieving Device Information 429 While the examples thus far have been focused on information about 430 humans, WebFinger does not limit queries to only those that use the 431 account URI scheme. Any URI scheme that contains domain information 432 MAY be used with WebFinger. Let's suppose there are devices on the 433 network like printers and you would like to check the current toner 434 level for a particular printer identified via the URI like 435 device:p1.example.com. While the "device" URI scheme is not 436 presently specified, we use it here for illustrative purposes. 438 Following the procedures similar to those above, a query may be 439 issued to get link relations specific to this URI like this: 441 GET /lrdd/?format=json&uri=device%3Ap1.example.com HTTP/1.1 442 Host: example.com 444 The link relations that are returned may be quite different than 445 those for user accounts. Perhaps we may see a response like this: 447 HTTP/1.1 200 OK 448 Access-Control-Allow-Origin: * 449 Content-Type: application/json; charset=UTF-8 451 { 452 "subject" : "device:p1.example.com", 453 "links" : 454 [ 455 { 456 "rel" : "tipsi", 457 "href" : "http://192.168.1.5/npap/" 458 } 459 ] 460 } 462 While this example is entirely fictitious, you can imagine that 463 perhaps the Transport Independent, Printer/System Interface [19] may 464 be enhanced with a web interface that allows a device that 465 understands the TIP/SI web interface specification to query the 466 printer for toner levels. 468 5. WebFinger Protocol 470 WebFinger does not actually introduce a new protocol, per se. 471 Rather, it builds upon the existing Web Host Metadata [10] 472 specification and leverages the Cross-Origin Resource Sharing (CORS) 473 [8] specification. 475 5.1. Performing a WebFinger Query 477 The first step a client must perform in executing a WebFinger query 478 is to query for the host metadata using HTTPS or HTTP. The 479 procedures are defined in the Web Host Metadata [10] specification. 481 WebFinger clients MUST locate the LRDD link relation, if present, and 482 perform a query for that link relation, if present. All other link 483 templates found must be processed to form a complete resource 484 descriptor. The processing rules in Section 4.2 of RFC 6415 MUST be 485 followed. 487 WebFinger servers MUST accept requests for both XRD [9] and JRD [10] 488 documents. The default representation returned by the server MUST be 489 an XRD document, but a JRD document MUST be returned if the client 490 explicitly requests it by using /.well-known/host-meta.json or 491 includes an Accept header in the HTTP request with a type of 492 "application/json" [5]. 494 If the client requests a JRD document when querying for host 495 metadata, the WebFinger server can assume that the client will want a 496 JRD documents when querying the LRDD resource. As such, when the 497 WebFinger server returns a JRD document containing host metadata it 498 should include a URI for an LRDD resource that can return a JRD 499 document and MAY include a URI for an LRDD resource that will return 500 an XRD document. 502 If the client queries the LRDD resource and provides a URI for which 503 the server has no information, the server MUST return a 404 status 504 code. Likewise, any query to a URI in the resource descriptor that 505 is unknown to the server MUST result in the server returning a 404 506 status code. 508 WebFinger servers MAY include cache validators in a response to 509 enable conditional requests by clients and/or expiration times as per 510 RFC 2616 section 13. 512 5.2. The Web Host Metadata "resource" Parameter 514 In addition to the normal processing logic for processing host 515 metadata information, WebFinger defines the "resource" parameter for 516 querying for host metadata and returning all of the link relations 517 from LRDD and other resource-specific link templates in a single 518 query. This resource essentially pushes the work to the server to 519 form a complete resource descriptor for the specified resource. 521 WebFinger servers compliant with this specification MUST support for 522 the "resource" parameter as a means of improving performance and 523 reducing client complexity. Note that an RFC 6415-compliant server 524 might not implement the "resource" parameter, though the server would 525 respond to queries from the client as described in RFC 6415. Thus, 526 WebFinger clients MUST check the server response to ensure that the 527 "resource" parameter is supported as explained below. 529 To utilize the host-meta "resource" parameter, a WebFinger client 530 issues a request to /.well-known/host-meta or /.well-known/host- 531 meta.json as usual, but then appends a "resource" parameter as shown 532 in this example: 534 GET /.well-known/host-meta.json?resource=\ 535 acct%3Abob%40example.com HTTP/1.1 536 Host: example.com 538 Note that the "\" character shown above is to indicate that the line 539 breaks at this point and continues on the next line. This was shown 540 only to avoid line wrapping in this document and is not a part of the 541 HTTP protocol. 543 When processing this request, the WebFinger server MUST 545 * Return a 404 status code if the URI provided in the resource 546 parameter is unknown to the server; and 548 * Set the "Subject" returned in the response to the value of the 549 "resource" parameter if the URI provided in the resource 550 parameter is known to the server 552 The WebFinger client can verify support for the "resource" parameter 553 by checking the value of the Subject returned in the response. If 554 the Subject matches the value of the "resource" parameter, then the 555 "resource" parameter is supported by the server. 557 For illustrative purposes, the following is an example usage of the 558 "resource" parameter that aligns with the example in Section 1.1.1 of 559 RFC 6415. The WebFinger client would issue this request: 561 GET /.well-known/host-meta.json?resource=\ 562 http%3A%2F%2Fexample.com%2Fxy HTTP/1.1 563 Host: example.com 565 The WebFinger server would reply with this response: 567 HTTP/1.1 200 OK 568 Access-Control-Allow-Origin: * 569 Content-Type: application/json; charset=UTF-8 571 { 572 "subject" : "http://example.com/xy", 573 "properties" : 574 { 575 "http://spec.example.net/color" : "red" 576 }, 577 "links" : 578 [ 579 { 580 "rel" : "hub", 581 "href" : "http://example.com/hub" 582 }, 583 { 584 "rel" : "hub", 585 "href" : "http://example.com/another/hub" 586 }, 587 { 588 "rel" : "author", 589 "href" : "http://example.com/john" 590 }, 591 { 592 "rel" : "author", 593 "href" : "http://example.com/author?\ 594 q=http%3A%2F%2Fexample.com%2Fxy" 595 } 596 ] 597 } 599 5.3. The Web Host Metadata "rel" Parameter 601 WebFinger also defines the "rel" parameter for use when querying for 602 host metadata. It is used to return a subset of the information that 603 would otherwise be returned without the "rel" parameter. When the 604 "rel" parameter is used, only the link relations that match the 605 space-separated list of link relations provided via "rel" are 606 included in the list of links returned in the resource descriptor. 607 All other information normally present in a resource descriptor is 608 present in the resource descriptor, even when "rel" is employed. 610 The purpose of the "rel" parameter is to return a subset of 611 resource's link relations. It is not intended to reduce the work 612 required of a server to produce a response. That said, use of the 613 parameter might reduce processing requirements on either the client 614 or server, and it might also reduce the bandwidth required to convey 615 the partial resource descriptor, especially if there are numerous 616 link relation values to convey for a given resource. 618 Support for the "rel" parameter is OPTIONAL, but support is 619 RECOMMENDED for both the host-meta resource and the LRDD resource. 621 For illustrative purposes, the following is an example usage of the 622 "rel" parameter that aligns with the example in Section 1.1.1 of RFC 623 6415. The WebFinger client would issue this request to receive links 624 that are of the type "hub" and "copyright": 626 GET /.well-known/host-meta.json?resource=\ 627 http%3A%2F%2Fexample.com%2Fxy&rel=hub%20copyright HTTP/1.1 628 Host: example.com 630 The WebFinger server would reply with this response: 632 HTTP/1.1 200 OK 633 Access-Control-Allow-Origin: * 634 Content-Type: application/json; charset=UTF-8 636 { 637 "subject" : "http://example.com/xy", 638 "properties" : 639 { 640 "http://spec.example.net/color" : "red" 641 }, 642 "links" : 643 [ 644 { 645 "rel" : "hub", 646 "href" : "http://example.com/hub" 647 }, 648 { 649 "rel" : "hub", 650 "href" : "http://example.com/another/hub" 651 } 652 ] 653 } 655 Note that in this example, the "author" links are removed, though all 656 other content is present. Since there were no "copyright" links, 657 none are returned. 659 In the event that a client requests links for link relations that are 660 not defined for the specified resource, a resource descriptor MUST be 661 returned, void of any links. When a JRD is returned, the "links" 662 array MAY be either absent or empty. The server MUST NOT return a 663 404 status code when a particular link relation specified via "rel" 664 is not defined for the resource, as a 404 status code is reserved for 665 indicating that the resource itself (e.g., as indicated via the 666 "resource" parameter) does not exist. 668 5.4. WebFinger and URIs 670 Requests for both LRDD documents and hostmeta files can include a 671 parameter specifying the URI of an account, device, or other entity 672 (for LRDD this is the "uri" parameter as defined by the operative XRD 673 or JRD template, for hostmeta this is the "resource" parameter). 674 WebFinger itself is agnostic regarding the scheme of such a URI: it 675 could be an "acct" URI as defined in the next section, an "http" or 676 "https" URI, a "mailto" URI, or some other scheme. 678 For resources associated with a user account at a domain, use of the 679 "acct" URI scheme is RECOMMENDED, since it explicitly identifies an 680 account accessible via WebFinger. Further, the "acct" URI scheme is 681 not associated other protocols as, by way of example, the "mailto" 682 URI scheme is associated with email. Since not every domain offers 683 email service, using the "mailto" URI scheme is not ideal for 684 identifying user accounts across all domains. That said, use of the 685 "mailto" URI scheme would be ideal for use with WebFinger to discover 686 mail server configuration information for a user, for example. 688 A domain MAY utilize one or more URIs that serve as aliases for the 689 user's account, such as URIs that use the "http" URI scheme. A 690 WebFinger server MUST return substantially the same response to both 691 an "acct" URI and any alias URI for the account, including the same 692 set of link relations and properties. In addition, the server SHOULD 693 include the entire list aliases for the user's account in the XRD or 694 JRD. 696 6. The "acct" URI 698 The "acct" URI takes a familiar form in looking like an email 699 address. However, the account URI is not an email address and should 700 not be mistaken for one. Quite often, the account URI minus the 701 "acct:" scheme prefix may be exactly the same as the user's email 702 address. 704 The "acct" URI syntax is defined here in Augmented Backus-Naur Form 705 (ABNF) [7] and borrows syntax elements from RFC 3986 [6]: 707 acctURI = "acct:" userpart "@" domainpart 708 userpart = 1*( unreserved / pct-encoded ) 709 domainpart = domainlabel 1*( "." domainlabel) 710 domainlabel = alphanum / alphanum *( alphanum / "-" ) alphanum 711 alphanum = ALPHA / DIGIT 713 The "acct" URI scheme allows any character from the Unicode [12] 714 character set encoded as a UTF-8 [20] string that is then percent- 715 encoded as necessary into valid ASCII [21]. Characters in the 716 domainpart must be encoded to support internationalized domain names 717 (IDNs) [13]. 719 Characters in the userpart or domainpart that are not unreserved must 720 be percent-encoded when used in a protocol or document that only 721 supports or requires ASCII. When carried in a document (e.g., XRD or 722 JRD) or protocol that supports the Unicode character set (e.g., UTF-8 723 or UTF-16 [22]), the URI strings may appear in the protocol or 724 document's native encoding without percent-encoding. Such usage of a 725 URI is commonly referred to as an Internationalized Resource 726 Identifier (IRI). Conversion between an IRI and URI is described in 727 Section 3 of RFC 3987 [14]. 729 7. The "acct" Link Relation 731 7.1. Purpose for the "acct" Link Relation 733 Users of some services might have an "acct" URI that looks 734 significantly different from his or her email address, perhaps using 735 an entirely different domain name. It is also possible for a user 736 have multiple accounts that a user wants to advertise and that a 737 WebFinger client may want to query. To address both of these needs, 738 this specification defines the "acct" link relation. 740 Since an account may make a reference to one or more different 741 accounts, WebFinger clients MUST take steps to avoid loops wherein 742 two accounts, directly or indirectly, refer the client to each other. 744 There are no limits on the number of "acct" link relations that might 745 be returned in a WebFinger query. 747 An "acct" link relation used within the context of a WebFinger query 748 for a user's account MUST NOT return "acct" link relations for 749 another individual. 751 7.2. Example Message Exchange Using the "acct" Link Relation 753 Consider the following non-normative example. 755 Suppose Alice receives an email from bob@example.net. While Bob's 756 email identifier might be in the example.net domain, he holds his 757 account with an "acct" URI in the example.com domain. His email 758 provider may provide WebFinger services to enable redirecting Alice 759 when she queries for acct:bob@example.net. 761 Suppose Alice's client issues the following request: 763 GET /.well-known/host-meta.json?resource=\ 764 acct%3Abob%40example.net HTTP/1.1 765 Host: example.net 767 The response that Alice's client receives back might be: 769 HTTP/1.1 200 OK 770 Access-Control-Allow-Origin: * 771 Content-Type: application/json; charset=UTF-8 773 { 774 "subject" : "acct:bob@example.net", 775 "links" : 776 [ 777 { 778 "rel" : "acct", 779 "href" : "acct:bob@example.com" 780 }, 781 { 782 "rel" : "acct", 783 "href" : "acct:bob@example.org" 784 } 785 ] 786 } 788 Alice's WebFinger client could then perform queries against the URIs 789 acct:bob@example.com and acct:bob@example.org in order to get the 790 information Alice is seeking. 792 8. Cross-Origin Resource Sharing (CORS) 794 WebFinger is most useful when it is accessible without restrictions 795 on the Internet, and that includes web browsers. Therefore, 796 WebFinger servers MUST support Cross-Origin Resource Sharing (CORS) 797 [8] when serving content intended for public consumption. 798 Specifically, all queries to /.well-known/host-meta, /.well- 799 known/host-meta.json, and to the LRDD URI must include the following 800 HTTP header in the response: 802 Access-Control-Allow-Origin: * 804 Enterprise WebFinger servers that wish to restrict access to 805 information from external entities SHOULD use a more restrictive 806 Access-Control-Allow-Origin header and MAY exclude the header 807 entirely. 809 9. Controlling Access to Information 811 As with all web resources, access to the Host Metadata resource and 812 the LRDD resource MAY require authentication. Further, failure to 813 provide required credentials MAY result in the server forbidding 814 access or providing a different response than had the client 815 authenticated with the server. 817 Likewise, a server MAY provide different responses to different 818 clients based on other factors, such as whether the client is inside 819 or outside a corporate network. As a concrete example, a query 820 performed on the internal corporate network might return link 821 relations to employee pictures whereas link relations for employee 822 pictures might not be provided to external entities. 824 Further, link relations provided in a WebFinger server response MAY 825 point to web resources that impose access restrictions. For example, 826 it is possible that the aforementioned corporate server may provide 827 both internal and external entities with URIs to employee pictures, 828 but further authentication MAY be required in order for the WebFinger 829 client to access those resources if the request comes from outside 830 the corporate network. 832 The decisions made with respect to what set of link relations a 833 WebFinger server provides to one client versus another and what 834 resources require further authentication, as well as the specific 835 authentication mechanisms employed, are outside the scope of this 836 document. 838 10. Implementation Notes (Non-Normative) 840 A user should not be required to enter the "acct" URI scheme name 841 along with his account identifier into any WebFinger client. Rather, 842 the WebFinger client should accept identifiers that are void of the 843 "acct:" portion of the identifier. Composing a properly formatted 844 "acct" URI is the responsibility of the WebFinger client. 846 11. Security Considerations 848 All of the security considerations applicable to Web Host Metadata 849 [10] and Cross-Origin Resource Sharing [8] are also applicable to 850 this specification. Of particular importance is the recommended use 851 of HTTPS to ensure that information is not modified during transit. 852 Clients should verify that the certificate used on an HTTPS 853 connection is valid. 855 When using HTTP to request an XRD document, WebFinger clients SHOULD 856 verify the XRD document's signature, if present, to ensure that the 857 XRD document has not been modified. Additionally, WebFinger servers 858 SHOULD include a signature for XRD documents served over HTTP. 860 Service providers and users should be aware that placing information 861 on the Internet accessible through WebFinger means that any user can 862 access that information. While WebFinger can be an extremely useful 863 tool for allowing quick and easy access to one's avatar, blog, or 864 other personal information, users should understand the risks, too. 865 If one does not wish to share certain information with the world, do 866 not allow that information to be freely accessible through WebFinger. 868 The aforementioned word of caution is perhaps worth emphasizing again 869 with respect to dynamic information one might wish to share, such as 870 the current location of a user. WebFinger can be a powerful tool 871 used to assemble information about a person all in one place, but 872 service providers and users should be mindful of the nature of that 873 information shared and the fact that it might be available for the 874 entire world to see. Sharing location information, for example, 875 would potentially put a person in danger from any individual who 876 might seek to inflict harm on that person. 878 The easy access to user information via WebFinger was a design goal 879 of the protocol, not a limitation. If one wishes to limit access to 880 information available via WebFinger, such as a WebFinger server for 881 use inside a corporate network, the network administrator must take 882 measures necessary to limit access from outside the network. Using 883 standard methods for securing web resources, network administrators 884 do have the ability to control access to resources that might return 885 sensitive information. Further, WebFinger servers can be employed in 886 such a way as to require authentication and prevent disclosure of 887 information to unauthorized entities. 889 12. IANA Considerations 891 RFC Editor: Please replace QQQQ in the following two sub-sections 892 with a reference to this RFC. 894 12.1. Registration of the "acct" URI scheme name 896 This specification requests IANA to register the "acct" URI scheme in 897 the "Permanent URI Schemes" sub-registry in the "Uniform Resource 898 Identifier (URI) Schemes" IANA registry [18]. This registration 899 follows the URI Scheme Registration Template detailed in Section 5.4 900 of RFC 4395 [16]. 902 URI scheme name: acct 904 Status: Permanent 906 URI scheme syntax: see Section 5.2 of RFC QQQQ 908 URI scheme semantics: see Section 5 of RFC QQQQ 910 Encoding considerations: The "acct" URI scheme allows any character 911 from the Unicode character set encoded as a UTF-8 string that is 912 then percent-encoded as necessary to result in an internal 913 representation in US-ASCII [11] 915 Applications/protocols that use this URI scheme name: WebFinger 917 Security considerations: see Section 7 of RFC QQQQ 919 Contact: Gonzalo Salgueiro 921 Author/Change controller: IETF 923 References: See Section 10 of RFC QQQQ 925 12.2. Registration of the "acct" Link Relation Type 927 Relation Name: acct 929 Description: A link relation that refers to a user's WebFinger 930 account identifier. 932 Reference: RFC QQQQ 934 Notes: 936 Application Data: 938 13. Acknowledgments 940 The authors would like to acknowledge Eran Hammer-Lahav, Blaine Cook, 941 Brad Fitzpatrick, Laurent-Walter Goix, Joe Clarke, Mike Jones, and 942 Peter Saint-Andre for their invaluable input. 944 14. References 946 14.1. Normative References 948 [1] Bradner, S., "Key words for use in RFCs to Indicate Requirement 949 Levels", BCP 14, RFC 2119, March 1997. 951 [2] Fielding, R., Gettys, J., Mogul, J., Frystyk, H., 952 Masinter, L., Leach, P., and T. Berners-Lee, "Hypertext 953 Transfer Protocol -- HTTP/1.1", RFC 2616, June 1999. 955 [3] Nottingham, M., Hammer-Lahav, E., "Defining Well-Known Uniform 956 Resource Identifiers (URIs)", RFC 5785, April 2010. 958 [4] Nottingham, M., "Web Linking", RFC 5988, October 2010. 960 [5] Crockford, D., "The application/json Media Type for 961 JavaScript Object Notation (JSON)", RFC 4627, July 2006. 963 [6] Berners-Lee, T., Fielding, R., and Masinter, L., "Uniform 964 Resource Identifier (URI): Generic Syntax", STD 66, RFC 3986, 965 January 2005. 967 [7] Crocker, D. and P. Overell, "Augmented BNF for Syntax 968 Specifications: ABNF", STD 68, RFC 5234, January 2008. 970 [8] Van Kesteren, A., "Cross-Origin Resource Sharing", W3C CORS 971 http://www.w3.org/TR/cors/, July 2010. 973 [9] Hammer-Lahav, E. and W. Norris, "Extensible Resource Descriptor 974 (XRD) Version 1.0", http://docs.oasis- 975 open.org/xri/xrd/v1.0/xrd-1.0.html. 977 [10] Hammer-Lahav, E. and Cook, B., "Web Host Metadata", RFC 6415, 978 October 2011. 980 [11] American National Standards Institute, "Coded Character Set - 981 7-bit American Standard Code for Information Interchange", ANSI 982 X3.4, 1986. 984 [12] The Unicode Consortium. The Unicode Standard, Version 6.1.0, 985 (Mountain View, CA: The Unicode Consortium, 2012. ISBN 978-1- 986 936213-02-3) http://www.unicode.org/versions/Unicode6.1.0/. 988 [13] Klensin, J., "Internationalized Domain Names in Applications 989 (IDNA): Protocol", RFC 5891, August 2010. 991 [14] Duerst, M., "Internationalized Resource Identifiers (IRIs)", 992 RFC 3987, January 2005. 994 14.2. Informative References 996 [15] Zimmerman, D., "The Finger User Information Protocol", RFC 997 1288, December 1991. 999 [16] Hansen, T., Hardie, T., and L. Masinter, "Guidelines and 1000 Registration Procedures for New URI Schemes", BCP 35, RFC 4395, 1001 February 2006. 1003 [17] Perreault, S., "vCard Format Specification", RFC 6350, August 1004 2011. 1006 [18] Internet Assigned Numbers Authority (IANA) Registry, "Uniform 1007 Resource Identifier (URI) Schemes", 1008 . 1010 [19] "Transport Independent, Printer/System Interface", IEEE Std 1011 1284.1-1997, 1997. 1013 [20] Yergeau, F., "UTF-8, a transformation format of ISO 10646", RFC 1014 3629, November 2003. 1016 [21] Information Systems -- Coded Character Sets 7-Bit American 1017 National Standard Code for Information Interchange (7-Bit 1018 ASCII), ANSI X3.4-1986, December 30, 1986. 1020 [22] Hoffman, P., Yergeau, F., "UTF-16, an encoding of ISO 10646", 1021 RFC 2781, February 2000. 1023 Author's Addresses 1025 Paul E. Jones 1026 Cisco Systems, Inc. 1027 7025 Kit Creek Rd. 1028 Research Triangle Park, NC 27709 1029 USA 1031 Phone: +1 919 476 2048 1032 Email: paulej@packetizer.com 1033 IM: xmpp:paulej@packetizer.com 1035 Gonzalo Salgueiro 1036 Cisco Systems, Inc. 1037 7025 Kit Creek Rd. 1038 Research Triangle Park, NC 27709 1039 USA 1041 Phone: +1 919 392 3266 1042 Email: gsalguei@cisco.com 1043 IM: xmpp:gsalguei@cisco.com 1045 Joseph Smarr 1046 Google 1048 Email: jsmarr@google.com 1050 Change Log (To Be Deleted Before Publication) 1051 ============================================= 1053 -06 Draft 1055 * Added an overview section 1057 * Made changes to example to show use of aliases 1059 * Added text to highlight that WebFinger may use various URI schemes 1061 * Reduced the text in the "acct" URI scheme section 1063 * Added an Implementation Notes section 1065 -05 Draft 1067 * Minor editorial corrections 1069 * Removed last paragraph from Section 6.1 1071 * Clarified use of CORS and how it may differ for enterprise use 1073 -04 Draft 1075 * Added text that makes the "resource" parameter required 1077 * Added a new section 8 that discusses controlling access to information 1079 * Added a little more to the security considerations section to briefly 1080 cover what was more fully explained in the new section 8 1082 -03 Draft 1084 * Changed the name from Webfinger to WebFinger (common usage) 1086 * Added a new paragraph to Section 4.1 to remind readers that WebFinger 1087 benefits from all of the existing HTTP caching functionality 1089 * Added the "rel" parameter to allow filtering the results of a 1090 WebFinger query to include Links of the specified type(s) 1092 * Corrected a reference to an obsoleted RFC 1093 * Removed extraneous text from the terminology section 1095 -02 Draft 1097 * Minor editorial changes 1099 * Added to the XML example to highlight that this element 1100 exists, since some may not be aware 1102 * Changed some of the link relation values, particularly for those that 1103 are not yet standardized 1105 * Added a note about "device:" not being standard 1107 * Overhauled the "acct" link relation text, breaking the normative and 1108 non-normative pieces apart 1110 * Added additional text to the security considerations section related 1111 to dynamic information (e.g., geographic information)