idnits 2.17.1 draft-ietf-appsawg-webfinger-01.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 (October 19, 2012) is 4207 days in the past. Is this intentional? -- Found something which looks like a code comment -- if you have code sections in the document, please surround them with '' and '' lines. 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: '12' is defined on line 1049, but no explicit reference was found in the text == Unused Reference: '15' is defined on line 1061, but no explicit reference was found in the text == Unused Reference: '17' is defined on line 1068, but no explicit reference was found in the text == Unused Reference: '19' is defined on line 1075, 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) == Outdated reference: A later version (-07) exists of draft-ietf-appsawg-acct-uri-00 -- 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 (==), 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: April 19, 2013 Joseph Smarr 6 Google 7 October 19, 2012 9 WebFinger 10 draft-ietf-appsawg-webfinger-01.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 discover 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 April 19, 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. Simplifying the Login Process.............................7 61 4.3. Retrieving Device Information.............................8 62 5. WebFinger Protocol.............................................8 63 5.1. Performing a WebFinger Query..............................9 64 5.2. The Web Host Metadata "resource" Parameter...............10 65 5.3. The Web Host Metadata "rel" Parameter....................12 66 5.4. WebFinger and URIs.......................................14 67 6. The "acct" Link Relation......................................14 68 6.1. Purpose for the "acct" Link Relation.....................14 69 6.2. Example Message Exchange Using the "acct" Link Relation..15 70 7. Cross-Origin Resource Sharing (CORS)..........................16 71 8. Controlling Access to Information.............................17 72 9. Hosted and Distributed WebFinger Services.....................17 73 9.1. Hosting the Entire Domain................................17 74 9.2. Distributed WebFinger Services...........................18 75 10. Web Host Metadata Interoperability Considerations............20 76 11. Security Considerations......................................20 77 12. IANA Considerations..........................................21 78 12.1. Registration of the "acct" Link Relation Type...........21 79 13. Acknowledgments..............................................21 80 14. References...................................................21 81 14.1. Normative References....................................21 82 14.2. Informative References..................................22 83 APPENDIX A: XRD Usage (Non-normative)............................24 84 A.1. How XRD Documents are Requested via WebFinger............24 85 A.2. WebFinger Example using XRDs.............................24 86 A.3. Security Considerations Related to XRDs..................25 87 Author's Addresses...............................................26 89 1. Introduction 91 There is a utility found on UNIX systems called "finger" [14] that 92 allows a person to access information about another person or entity 93 that has a UNIX account. The information queried might be on the 94 same computer or a computer anywhere in the world. What is returned 95 via "finger" is simply a plain text file that contains unstructured 96 information provided by the queried user, stored in a file named 97 .plan in the user's home directory. 99 WebFinger borrows the concept of the legacy finger protocol, but 100 introduces a very different approach to sharing information. Rather 101 than return a simple unstructured text file, Webfinger uses 102 structured documents that contain link relations. These link 103 relations point to information and might return properties related to 104 information a user or entity on the Internet wishes to expose. For a 105 person, the kinds of information that might be exposed include a 106 personal profile address, identity service, telephone number, or 107 preferred avatar. WebFinger may also be used to discover information 108 about objects on the network, such as the amount of toner in a 109 printer or the physical location of a server. 111 Information returned via WebFinger might be for direct human 112 consumption (e.g., another user's phone number) or it might be used 113 by systems to help carry out some operation (e.g., facilitate logging 114 into a web site by determining a user's identity service). 116 2. Terminology 118 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 119 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 120 document are to be interpreted as described in RFC 2119 [1]. 122 WebFinger makes heavy use of "Link Relations". Briefly, a Link 123 Relation is an attribute and value pair used on the Internet wherein 124 the attribute identifies the type of link to which the associated 125 value refers. In Hypertext Transfer Protocol (HTTP) [2] and Web 126 Linking [4], the attribute is a "rel" and the value is an "href". 128 3. Overview 130 WebFinger enables the discovery of information about accounts, 131 devices, and other entities that are associated with a host. 132 Discover involves two distinct steps that may be optimized as a 133 single step, as will be explained later. The first step is to query 134 the host to find out how to discover information about accounts, 135 devices, and other entities associated with that host. The second 136 step is to query explicitly for a specific resource (e.g., user 137 account) to discover a set of link relations that point to resource- 138 specific information about the entity being queried. 140 This protocol makes heavy use of well-known URIs as defined in RFC 141 5785 [3] and "Link Relations" as defined in RFC 5988 [4]. Further, 142 the protocol builds on RFC 6415 [11], which provides the foundation 143 for the procedures described in this document. 145 Briefly, a link is a typed connection between two web resources that 146 are identified by Internationalized Resource Identifiers (IRIs) [13]; 147 this connection consists of a context IRI, a link relation type, a 148 target IRI, and optionally some target attributes, resulting in 149 statements of the form "{context IRI} has a {relation type} resource 150 at {target IRI}, which has {target attributes}". When used in the 151 Link HTTP header, the context IRI is the IRI of the requested 152 resource, the relation type is the value of the "rel" parameter, the 153 target IRI is URI-Reference contained in the Link header, and the 154 target attributes are the parameters such as "hreflang", "media", 155 "title", "title*", "type", and any other link-extension parameters. 157 Thus the framework for WebFinger consists of several building blocks: 159 1. To query the host, one requests a web host metadata document 160 located at the well-known URI /.well-known/host-meta or /.well- 161 known/host-meta.json (referred to as the host-meta resources) at 162 the host. 163 2. The web server at the host returns a JavaScript Object Notation 164 (JSON) [5] Resource Descriptor (JRD) or an Extensible Resource 165 Descriptor (XRD) [10] document, including a Link-based Resource 166 Descriptor Document (LRDD) link relation. 167 3. To discover information about accounts, devices, or other entities 168 associated with the host, one requests the actual Link-based 169 Resource Descriptor Document associated with a particular URI at 170 the host (e.g., an "acct" URI, "http" URI, or "mailto" URI). 171 4. The web server at the host returns a JRD or XRD document for the 172 requested URI, which includes link relations pointing to resources 173 that contain more detailed information about the entity. 175 This model is illustrated in the examples in Section 4, then 176 described more formally in Section 5. Steps 2 and 3 above can be 177 accomplished simultaneously by utilizing the "resource" parameter 178 defined in Section 5.2. 180 4. Example Uses of WebFinger 182 In this section, we describe just a few sample uses for WebFinger and 183 show what the protocol looks like. This is not an exhaustive list of 184 possible uses and the entire section should be considered non- 185 normative. The list of potential use cases is virtually unlimited 186 since a user can share any kind of machine-consumable information via 187 WebFinger. 189 All of the following examples utilize JRDs, as that is the only 190 mandatory format required to be supported by WebFinger servers. For 191 completeness, an example utilizing XRDs is presented in Appendix A. 193 4.1. Locating a User's Blog 195 Assume you receive an email from Bob and he refers to something he 196 posted on his blog, but you do not know where Bob's blog is located. 198 It would be simple to discover the address of Bob's blog if he makes 199 that information available via WebFinger. 201 Let's assume your email client discovers that blog automatically for 202 you. After receiving the message from Bob (bob@example.com), your 203 email client performs the following steps behind the scenes. 205 First, your email client tries to get the host metadata information 206 for the host example.com. It does this by issuing the following 207 HTTPS query to example.com: 209 GET /.well-known/host-meta.json HTTP/1.1 210 Host: example.com 212 The server replies with a JRD document: 214 HTTP/1.1 200 OK 215 Access-Control-Allow-Origin: * 216 Content-Type: application/json; charset=UTF-8 218 { 219 "links" : 220 [ 221 { 222 "rel" : "lrdd", 223 "type" : "application/json", 224 "template" : "https://example.com/lrdd/?f=json&uri={uri}" 225 } 226 ] 227 } 229 The client then processes the received JRD in accordance with the Web 230 Host Metadata procedures. The client will see the LRDD link relation 231 and issue a query with the user's account URI [6] or other URI that 232 serves as an alias for the account. (The account URI is discussed in 233 Section 4.2.) The query might look like this: 235 GET /lrdd/?f=json&uri=acct%3Abob%40example.com HTTP/1.1 236 Host: example.com 238 The server might then respond with a message like this: 240 HTTP/1.1 200 OK 241 Access-Control-Allow-Origin: * 242 Content-Type: application/json; charset=UTF-8 244 { 245 "expires" : "2012-10-12T20:56:11Z", 246 "subject" : "acct:bob@example.com", 247 "aliases" : 248 [ 249 "http://www.example.com/~bob/" 250 ], 251 "links" : 252 [ 253 { 254 "rel" : "http://webfinger.net/rel/avatar", 255 "href" : "http://www.example.com/~bob/bob.jpg" 256 }, 257 { 258 "rel" : "http://webfinger.net/rel/profile-page", 259 "href" : "http://www.example.com/~bob/" 260 }, 261 { 262 "rel" : "http://packetizer.com/rel/blog", 263 "href" : "http://blogs.example.com/bob/" 264 }, 265 { 266 "rel" : "vcard", 267 "href" : "http://www.example.com/~bob/bob.vcf" 268 } 269 ] 270 } 272 The email client might take note of the "blog" link relation in the 273 above JRD document that refers to Bob's blog. This URL would then be 274 presented to you so that you could then visit his blog. The email 275 client might also note that Bob has published an avatar link relation 276 and use that picture to represent Bob inside the email client. 277 Lastly, the client might consider the vcard [16] link relation in 278 order to update contact information for Bob. 280 Note in the above example that an alias is provided that can also be 281 used to return information about the user's account. Had the "http:" 282 URI shown as an alias been used to query for information about Bob, 283 the query would have appeared as: 285 GET /lrdd/?uri=http%3A%2F%2Fwww.example.com%2F~bob%2F HTTP/1.1 286 Host: example.com 288 The response would have been substantially the same, with the subject 289 and alias information changed as necessary. Other information, such 290 as the expiration time might also change, but the set of link 291 relations and properties would be the same with either response. 293 4.2. Simplifying the Login Process 295 OpenID (http://www.openid.net) is great for allowing users to log 296 into a web site, though one criticism is that it is challenging for 297 users to remember the URI they are assigned. WebFinger can help 298 address this issue by allowing users to use user@domain-style 299 addresses. Using a user's account URI, a web site can perform a 300 query to discover the associated OpenID identifier for a user. 302 Let's assume Carol is trying to use OpenID to log into a blog. The 303 blog server might issue the following query to discover the OpenID 304 identity provider URL for Carol and to get Carol's avatar. In this 305 example, we utilize the "rel" and "resource" parameters as described 306 in sections 5.2 and 5.3: 308 GET /.well-known/host-meta.json?\ 309 rel=avatar%20\ 310 http%3A%3F%3Fspecs.openid.net%3Fauth%3F2.0%3Fprovider&\ 311 resource=acct%3Acarol%40example.com HTTP/1.1 312 Host: example.com 314 The server might return a response like this: 316 HTTP/1.1 200 OK 317 Access-Control-Allow-Origin: * 318 Content-Type: application/json; charset=UTF-8 320 { 321 "subject" : "acct:carol@example.com", 322 "links" : 323 [ 324 { 325 "rel" : "http://webfinger.net/rel/avatar", 326 "href" : "http://example.com/~alice/alice.jpg" 327 }, 328 { 329 "rel" : "http://specs.openid.net/auth/2.0/provider", 330 "href" : "https://openid.example.com/carol" 331 } 332 ] 333 } 335 At this point, the blog server knows that Carol's OpenID identifier 336 is https://openid.example.com/carol and could then proceed with the 337 login process as usual. Her avatar can also be displayed for the 338 benefit of other users on the blog. 340 4.3. Retrieving Device Information 342 While the examples thus far have been focused on information about 343 humans, WebFinger does not limit queries to only those that use the 344 account URI scheme. Any URI scheme that contains host information 345 MAY be used with WebFinger. Let's suppose there are devices on the 346 network like printers and you would like to check the current toner 347 level for a particular printer identified via the URI like 348 device:p1.example.com. While the "device" URI scheme is not 349 presently specified, we use it here only for illustrative purposes. 351 Following the procedures similar to those above, a query may be 352 issued to get link relations specific to this URI like this: 354 GET /.well-known/host-meta.json?resource=\ 355 device%3Ap1.example.com HTTP/1.1 356 Host: example.com 358 The link relations that are returned may be quite different than 359 those for user accounts. Perhaps we may see a response like this: 361 HTTP/1.1 200 OK 362 Access-Control-Allow-Origin: * 363 Content-Type: application/json; charset=UTF-8 365 { 366 "subject" : "device:p1.example.com", 367 "links" : 368 [ 369 { 370 "rel" : "tipsi", 371 "href" : "http://192.168.1.5/npap/" 372 } 373 ] 374 } 376 While this example is entirely fictitious, you can imagine that 377 perhaps the Transport Independent, Printer/System Interface [18] may 378 be enhanced with a web interface that allows a device that 379 understands the TIP/SI web interface specification to query the 380 printer for toner levels. 382 5. WebFinger Protocol 384 WebFinger does not actually introduce a new protocol, per se. 385 Rather, it builds upon the existing Web Host Metadata specification 386 and leverages the Cross-Origin Resource Sharing (CORS) [9] 387 specification. 389 While WebFinger strives to maintain backward-compatibility with RFC 390 6415, this specification introduces a fundamental change in 391 requirements. Specifically, support for server-side production of 392 JSON Resource Descriptor (JRD) documents is mandatory and support for 393 server-side production Extensible Resource Descriptor (XRD) documents 394 is optional. Please refer to Section 10 for interoperability 395 considerations. 397 5.1. Performing a WebFinger Query 399 The first step a client performs in executing a WebFinger query is to 400 query for the host metadata using HTTPS or HTTP. The procedures are 401 defined in the Web Host Metadata specification. It is strongly 402 RECOMMENDED that WebFinger servers return content using secure 403 (HTTPS) connections. Clients MUST first attempt queries using HTTPS 404 before attempting a query using HTTP. 406 WebFinger clients MUST locate the LRDD link relation and perform a 407 query for that link relation, if present. All other link templates 408 found must be processed to form a complete resource descriptor. The 409 processing rules in Section 4.2 of RFC 6415 MUST be followed. 411 WebFinger servers MAY accept requests for both JRD and XRD documents, 412 but MUST support requests for JRD documents. For interoperability 413 with RFC 6415 implementations, the default representation returned by 414 a server via the resource at /.well-known/host-meta MUST be an XRD 415 document if XRD is supported by the server and a JRD document is not 416 explicitly requested by the client. The default format returned via 417 the resource /.well-known/host-meta.json MUST be a JRD document. 419 As per RFC 6415, a JRD document MUST be returned by the WebFinger 420 server if the client explicitly requests it by querying /.well- 421 known/host-meta.json or by querying /.well-known/host-meta and 422 including an "Accept" header in the HTTP request with a type of 423 "application/json" [5]. Additionally, the server MUST return a JRD 424 document if it does not support production of XRD documents (or any 425 other format requested by the client). Servers MUST indicate the 426 type of document returned using the "Content-Type" header in the HTTP 427 response. 429 To avoid the possibility of receiving the wrong document format, 430 WebFinger clients SHOULD submit queries to the server via the /.well- 431 known/host-meta.json resource. 433 If the client requests a JRD document when querying for host 434 metadata, the WebFinger server MUST assume that the client will want 435 a JRD document when querying the LRDD resource. Thus when the 436 WebFinger server returns a JRD document containing host metadata that 437 contains an LRDD link relation, it MUST include a URI for the LRDD 438 resource(s) that will return a JRD document. Likewise, if a client 439 requests an XRD document when querying the host metadata resource, 440 the server MUST, unless unable due to external factors, return LRDD 441 link relations that would return XRD documents. 443 It is important to note that unless the "resource" parameter is used 444 as per section 5.2, it is the responsibility of the client to process 445 each of the LRDD link relations as per Section 4.2 of RFC 6415 if a 446 server returns multiple LRDD link relations. Multiple LRDD link 447 relations in a server response do not represent alternative URIs for 448 the same LRDD document. 450 If the client queries the LRDD resource and provides a URI for which 451 the server has no information, the server MUST return a 404 status 452 code. Likewise, any query to a URI in the resource descriptor that 453 is unknown to the server MUST result in the server returning a 404 454 status code. 456 WebFinger servers MAY include cache validators in a response to 457 enable conditional requests by clients and/or expiration times as per 458 RFC 2616 section 13. 460 5.2. The Web Host Metadata "resource" Parameter 462 In addition to the traditional processing logic for processing host 463 metadata information, WebFinger defines the "resource" parameter for 464 querying for host metadata and returning all of the link relations 465 from LRDD and other resource-specific link templates in a single 466 response. This parameter essentially pushes the work to the server 467 to form a complete resource descriptor for the specified resource. 469 WebFinger servers compliant with this specification MUST support for 470 the "resource" parameter as a means of improving performance and 471 reducing client complexity. Note that an RFC 6415-compliant server 472 might not implement the "resource" parameter, though the server would 473 respond to queries from the client as described in RFC 6415. Thus, 474 WebFinger clients MUST check the server response to ensure that the 475 "resource" parameter is supported as explained below. 477 To utilize the host-meta "resource" parameter, a WebFinger client 478 issues a request to /.well-known/host-meta.json (RECOMMENDED) or 479 /.well-known/host-meta as usual, but then appends a "resource" 480 parameter as shown in this example: 482 GET /.well-known/host-meta.json?resource=\ 483 acct%3Abob%40example.com HTTP/1.1 484 Host: example.com 486 When processing this request, the WebFinger server MUST 487 * Return a 404 status code if the URI provided in the resource 488 parameter is unknown to the server; and 490 * Set the "Subject" returned in the response to the value of the 491 "resource" parameter if the URI provided in the resource 492 parameter is known to the server; and 494 * Collect and expand all resource-specific link relations, 495 including those returned by querying for any LRDD link 496 relations, discard any host-wide link relations, and return a 497 complete resource descriptor following the processing rules in 498 Section 4.2 of RFC 6415; and 500 The WebFinger server MUST NOT issue HTTP queries for any link 501 relations other than LRDD link relations. It is not the 502 responsibility of the WebFinger server to verify, for example, that a 503 URI pointing to a person's avatar is a valid URI. When querying an 504 LRDD resource to collect additional resource-specific information, 505 any errors (e.g., 500 or 404) MUST be ignored by the server. When a 506 request for an LRDD fails, the server MUST NOT attempt to augment 507 missing resource information or return a "template" type link 508 relation to a client that utilizes the "resource" parameter. 510 The WebFinger client MUST verify support for the "resource" parameter 511 by checking the value of the Subject returned in the response. If 512 the Subject matches the value of the "resource" parameter, then the 513 "resource" parameter is supported by the server. The Subject would 514 be absent if the "resource" parameter is not supported. 516 For illustrative purposes, the following is an example usage of the 517 "resource" parameter that aligns with the example in Section 1.1.1 of 518 RFC 6415. The WebFinger client would issue this request: 520 GET /.well-known/host-meta.json?resource=\ 521 http%3A%2F%2Fexample.com%2Fxy HTTP/1.1 522 Host: example.com 524 Note: The "\" character shown above and used throughout this document 525 indicates that the line breaks at this point and continues on the 526 next line. The content of the next line should be concatenated to 527 the previous line without any whitespace characters, replacing the 528 "\" character. This is shown only to avoid line wrapping in this 529 document. 531 The WebFinger server would reply with this response: 533 HTTP/1.1 200 OK 534 Access-Control-Allow-Origin: * 535 Content-Type: application/json; charset=UTF-8 536 { 537 "subject" : "http://example.com/xy", 538 "properties" : 539 { 540 "http://spec.example.net/color" : "red" 541 }, 542 "links" : 543 [ 544 { 545 "rel" : "hub", 546 "href" : "http://example.com/hub" 547 }, 548 { 549 "rel" : "hub", 550 "href" : "http://example.com/another/hub" 551 }, 552 { 553 "rel" : "author", 554 "href" : "http://example.com/john" 555 }, 556 { 557 "rel" : "author", 558 "href" : "http://example.com/author?\ 559 q=http%3A%2F%2Fexample.com%2Fxy" 560 } 561 ] 562 } 564 5.3. The Web Host Metadata "rel" Parameter 566 WebFinger also defines the "rel" parameter for use when querying for 567 host metadata or resource-specific information. It is used to return 568 a subset of the information that would otherwise be returned without 569 the "rel" parameter. When the "rel" parameter is used, only the link 570 relations that match the space-separated list of link relations 571 provided via "rel" are included in the list of links returned in the 572 resource descriptor. All other information normally present in a 573 resource descriptor is present in the resource descriptor, even when 574 "rel" is employed. 576 The purpose of the "rel" parameter is to return a subset of 577 resource's link relations. It is not intended to reduce the work 578 required of a server to produce a response. That said, use of the 579 parameter might reduce processing requirements on either the client 580 or server, and it might also reduce the bandwidth required to convey 581 the partial resource descriptor, especially if there are numerous 582 link relation values to convey for a given resource. 584 Support for the "rel" parameter is OPTIONAL, but support is 585 RECOMMENDED for the host-meta resources and LRDD resources. 587 For illustrative purposes, the following is an example usage of the 588 "rel" parameter that aligns with the example in Section 1.1.1 of RFC 589 6415. The WebFinger client would issue this request to receive links 590 that are of the type "hub" and "copyright": 592 GET /.well-known/host-meta.json?resource=\ 593 http%3A%2F%2Fexample.com%2Fxy&rel=hub%20copyright HTTP/1.1 594 Host: example.com 596 The WebFinger server would reply with this response: 598 HTTP/1.1 200 OK 599 Access-Control-Allow-Origin: * 600 Content-Type: application/json; charset=UTF-8 602 { 603 "subject" : "http://example.com/xy", 604 "properties" : 605 { 606 "http://spec.example.net/color" : "red" 607 }, 608 "links" : 609 [ 610 { 611 "rel" : "hub", 612 "href" : "http://example.com/hub" 613 }, 614 { 615 "rel" : "hub", 616 "href" : "http://example.com/another/hub" 617 } 618 ] 619 } 621 Note that in this example, the "author" links are removed, though all 622 other content is present. Since there were no "copyright" links, 623 none are returned. 625 In the event that a client requests links for link relations that are 626 not defined for the specified resource, a resource descriptor MUST be 627 returned, void of any links. When a JRD is returned, the "links" 628 array MAY be either absent or empty. The server MUST NOT return a 629 404 status code when a particular link relation specified via "rel" 630 is not defined for the resource, as a 404 status code is reserved for 631 indicating that the resource itself (e.g., either /.well-known/host- 632 meta.json or the resource indicated via the "resource" parameter) 633 does not exist. 635 5.4. WebFinger and URIs 637 Requests for both LRDD documents and host metadata can include a 638 parameter specifying the URI of an account, device, or other entity 639 (for LRDD this is the "uri" parameter as defined by the operative JRD 640 or XRD template and for host metadata this is the "resource" 641 parameter). WebFinger itself is agnostic regarding the scheme of 642 such a URI: it could be an "acct" URI [7], an "http" or "https" URI, 643 a "mailto" URI, or some other scheme. 645 For resources associated with a user account at a host, use of the 646 "acct" URI scheme is RECOMMENDED, since it explicitly identifies an 647 account accessible via WebFinger. Further, the "acct" URI scheme is 648 not associated with other protocols as, by way of example, the 649 "mailto" URI scheme is associated with email. Since not every host 650 offers email service, using the "mailto" URI scheme [8] is not ideal 651 for identifying user accounts on all hosts. That said, use of the 652 "mailto" URI scheme would be ideal for use with WebFinger to discover 653 mail server configuration information for a user, for example. 655 A host MAY utilize one or more URIs that serve as aliases for the 656 user's account, such as URIs that use the "http" URI scheme [2]. A 657 WebFinger server MUST return substantially the same response to both 658 an "acct" URI and any alias URI for the account, including the same 659 set of link relations and properties. In addition, the server SHOULD 660 include the entire list aliases for the user's account in the JRD or 661 XRD returned when querying the LRDD resource or when utilizing the 662 "resource" parameter. 664 6. The "acct" Link Relation 666 6.1. Purpose for the "acct" Link Relation 668 Users of some services might have an "acct" URI that looks 669 significantly different from his or her email address, perhaps using 670 an entirely different domain name. It is also possible for a user to 671 have multiple accounts that a user wants to have cross-referenced 672 from another account. To address both of these needs, this 673 specification defines the "acct" link relation. 675 The "acct" link relation allows a resource descriptor to reference 676 one or more other user account URIs. The "acct" link relation is 677 intended to allow a client to incorporate additional link relations 678 by reference so that it might utilize a more complete set of link 679 relations for a user. For example, a user acct:bob@example.com might 680 wish to allow a client to discover additional information about him 681 by including an "acct" link relation with the URI 682 acct:bob@example.net. 684 Note that the "acct" link relation does not replace the use of 685 standard HTTP 3xx response codes to indicate the new temporary or 686 permanent location of a user account. If a user account is moved to 687 a different location, then a 3xx response code SHOULD be used. Also, 688 the "acct" link relation does not replace Link-based Resource 689 Descriptor Documents (LRDDs). A WebFinger server might return 690 multiple LRDD link relations for a user, each of which perhaps 691 containing link relations that are to be merged to form a complete 692 resource descriptor. The "acct" link relation is different in that 693 it would refer to an entirely different, separate resource 694 descriptor. Further, only a client would act consider the "acct" 695 link relations as it performs queries, not the WebFinger server. 697 Since an account may make a reference to one or more different 698 accounts, WebFinger clients that support automatic processing of the 699 "acct" link relations MUST take steps to avoid loops wherein two 700 account URIs, directly or indirectly, refer the client to each other. 702 There are no limits on the number of "acct" link relations that might 703 be returned in a WebFinger query. 705 An "acct" link relation used within the context of a WebFinger query 706 for a user's account MUST NOT return "acct" link relations for 707 another user. 709 Client-side consideration of the "acct" link relation is OPTIONAL and 710 WebFinger server MUST NOT assume a client will perform additional 711 processing in response to receiving an "acct" link relation. 713 6.2. Example Message Exchange Using the "acct" Link Relation 715 Consider the following non-normative example. 717 Suppose Alice receives an email from bob@example.net. While Bob's 718 email identifier might be in the example.net domain, he holds a user 719 account in the example.com domain and another account in the 720 example.org domain. His email provider may provide WebFinger 721 services, but is unable to serve information from other domains. 723 Suppose Alice's client issues the following request: 725 GET /.well-known/host-meta.json?resource=\ 726 acct%3Abob%40example.net HTTP/1.1 727 Host: example.net 729 The response that Alice's client receives back might be: 731 HTTP/1.1 200 OK 732 Access-Control-Allow-Origin: * 733 Content-Type: application/json; charset=UTF-8 735 { 736 "subject" : "acct:bob@example.net", 737 "links" : 738 [ 739 { 740 "rel" : "acct", 741 "href" : "acct:bob@example.com" 742 }, 743 { 744 "rel" : "acct", 745 "href" : "acct:bob@example.org" 746 }, 747 { 748 "rel" : "acct", 749 "href" : "mailto:bob@example.net" 750 } 751 ] 752 } 754 While these link relations provide Alice with very little 755 information, Alice's WebFinger client could then perform subsequent 756 queries against the URIs acct:bob@example.com, acct:bob@example.org, 757 and mailto:bob@example.net in order to get the information Alice is 758 seeking. 760 7. Cross-Origin Resource Sharing (CORS) 762 WebFinger is most useful when it is accessible without restrictions 763 on the Internet, and that includes web browsers. Therefore, 764 WebFinger servers MUST support Cross-Origin Resource Sharing (CORS) 765 [9] when serving content intended for public consumption. 766 Specifically, all queries to /.well-known/host-meta.json, /.well- 767 known/host-meta, and to any LRDD URIs MUST include the following HTTP 768 header in the response: 770 Access-Control-Allow-Origin: * 772 Enterprise WebFinger servers that wish to restrict access to 773 information from external entities SHOULD use a more restrictive 774 Access-Control-Allow-Origin header and MAY exclude the header 775 entirely. 777 8. Controlling Access to Information 779 As with all web resources, access to the Host Metadata resource and 780 the LRDD resource MAY require authentication. Further, failure to 781 provide required credentials MAY result in the server forbidding 782 access or providing a different response than had the client 783 authenticated with the server. 785 Likewise, a server MAY provide different responses to different 786 clients based on other factors, such as whether the client is inside 787 or outside a corporate network. As a concrete example, a query 788 performed on the internal corporate network might return link 789 relations to employee pictures whereas link relations for employee 790 pictures might not be provided to external entities. 792 Further, link relations provided in a WebFinger server response MAY 793 point to web resources that impose access restrictions. For example, 794 it is possible that the aforementioned corporate server may provide 795 both internal and external entities with URIs to employee pictures, 796 but further authentication MAY be required in order for the WebFinger 797 client to access those picture resources if the request comes from 798 outside the corporate network. 800 The decisions made with respect to what set of link relations a 801 WebFinger server provides to one client versus another and what 802 resources require further authentication, as well as the specific 803 authentication mechanisms employed, are outside the scope of this 804 document. 806 9. Hosted and Distributed WebFinger Services 808 9.1. Hosting the Entire Domain 810 As with most services provided on the Internet, it is possible for a 811 domain owner to utilize "hosted" WebFinger services. By way of 812 example, a domain owner might control most aspects of their domain, 813 but use a third-party hosting service email. In the case of email, 814 mail servers for a domain are identified by MX records. An MX record 815 points to the mail server to which mail for the domain should be 816 delivered. It does not matter to the sending mail server whether 817 those MX records point to a server in the destination domain or a 818 different domain. 820 Likewise, a domain owner might utilize the services of a third party 821 to provide WebFinger services on behalf of its users. Just as a 822 domain owner was required to insert MX records into DNS to allow for 823 hosted email serves, the domain owner is required to redirect HTTP(S) 824 queries to its domain to allow for hosted WebFinger services. 826 When a query is issued to /.well-known/host-meta.json or /.well- 827 known/host-meta, the target domain's web server MUST return a 301, 828 302, or 307 response status code that includes a Location header 829 pointing to the location of the hosted WebFinger service URL. The 830 WebFinger service URL does not need to point to /.well-known/* on the 831 hosting service provider server. In fact, it should not, as that 832 location would be reserved for queries relating to the service 833 provider's domain. WebFinger clients MUST follow all 301, 302, or 834 307 redirection requests. 836 As an example, let's assume that example.com's WebFinger services are 837 hosted by example.net. Suppose a client issues a query for 838 acct:alice@example.com like this: 840 GET /.well-known/host-meta.json? 841 resource=acct%3Aalice%40example.com HTTP/1.1 842 Host: example.com 844 The server might respond with this: 846 HTTP/1.1 301 Moved Permanently 847 Location: http://wf.example.net/example.org/host-meta.json 849 The client should follow the request, re-issuing the request to the 850 URL provided in the Location header. 852 Note that both of the /.well-known/host-meta.json and /.well- 853 known/host-meta resources need to be considered when redirecting 854 request to third party service providers. Those URLs requests SHOULD 855 NOT be redirected to the same location and without any 856 differentiation, since the default format returned by host-meta.json 857 is a JRD and the default format returned by host-meta MAY be XRD. 858 Each resource is distinct and should be redirected separately and to 859 different service locations or differentiated with a URI parameter. 860 Since the "Referer" HTTP header field is not mandatory, service 861 providers cannot rely on that header to determine the URL of the 862 original request. 864 9.2. Distributed WebFinger Services 866 A domain owner may wish to manage only a part of its WebFinger 867 services and WebFinger service providers or the domain owner may wish 868 to distribute WebFinger services across a number of WebFinger service 869 locations. The key to enabling this type of distribution is 870 placement of resource-specific information in more than one LRDD 871 document, each document existing at different locations. 873 Assume that the company operating example.com manages its own 874 WebFinger services, but also wants to utilize the services of 875 example.org to serve link relations related to some aspects of its 876 business. Suppose a client issued this request: 878 GET /.well-known/host-meta.json HTTP/1.1 879 Host: example.com 881 The server might reply with this JRD document: 883 HTTP/1.1 200 OK 884 Access-Control-Allow-Origin: * 885 Content-Type: application/json; charset=UTF-8 887 { 888 "links" : 889 [ 890 { 891 "rel" : "lrdd", 892 "type" : "application/json", 893 "template" : "https://example.com/lrdd/?f=json&uri={uri}" 894 }, 895 { 896 "rel" : "lrdd", 897 "type" : "application/json", 898 "template" : "https://wf.example.org/lrdd/?f=json&uri={uri}" 899 } 900 ] 901 } 903 This would indicate to the client that some of the resource-specific 904 information is found at example.com and some is found at example.org, 905 following those specific URLs. Observing the rules in Section 4.2 of 906 RFC 6415, the client would issue queries to both URLs and construct a 907 complete resource descriptor. 909 As discussed in Section 5.2, a client may issue a query like this to 910 the example.com domain: 912 GET /.well-known/host-meta.json?resource=\ 913 acct%3Aalice%40example.com HTTP/1.1 914 Host: example.com 916 In that case, it would be the responsibility of the WebFinger server 917 at example.com to query the LRDD URL at example.org and then compose 918 a complete descriptor document. The client that uses the resource 919 parameter remains entirely oblivious to the fact that link relation 920 information is distributed across multiple servers or domains. 922 10. Web Host Metadata Interoperability Considerations 924 As noted in Section 3, RFC 6415 required all servers to support the 925 production of Extensible Resource Documents (XRDs) and optionally 926 support the production of JSON Resource Documents (JRDs). This 927 specification reverses that requirement: WebFinger-compliant servers 928 MUST support JRD and MAY support XRD documents. 930 Given that some servers might implement only RFC 6415 and other 931 servers might implement only the minimum required set of features 932 defined for WebFinger, all clients should take care to ensure to 933 request a resource descriptor in the appropriate format. If a client 934 wishes to receive only JRDs, for example, it SHOULD issue a request 935 to /.well-known/host-meta.json, but MAY issue a request to /.well- 936 known/host-meta and include the "Accept" header with the type 937 "application/json". 939 Further, clients MUST ensure that the response returned from the 940 server contains the correct format. RFC 6415-compliant servers might 941 return an XRD document, regardless of what is requested by the 942 client. 944 Lastly, RFC 6415 did not require clients to follow 301, 302, or 307 945 redirection requests, but WebFinger clients MUST re-issue requests 946 when redirected using any of those HTTP status codes. 948 11. Security Considerations 950 All of the security considerations applicable to Web Host Metadata 951 and Cross-Origin Resource Sharing [9] are also applicable to this 952 specification. Of particular importance is the recommended use of 953 HTTPS to ensure that information is not modified during transit. 954 Clients SHOULD verify that the certificate used on an HTTPS 955 connection is valid. 957 Service providers and users should be aware that placing information 958 on the Internet accessible through WebFinger means that any user can 959 access that information. While WebFinger can be an extremely useful 960 tool for allowing quick and easy access to one's avatar, blog, or 961 other personal information, users should understand the risks, too. 962 If one does not wish to share certain information with the world, do 963 not allow that information to be freely accessible through WebFinger. 965 The aforementioned word of caution is perhaps worth emphasizing again 966 with respect to dynamic information one might wish to share, such as 967 the current location of a user. WebFinger can be a powerful tool 968 used to assemble information about a person all in one place, but 969 service providers and users should be mindful of the nature of that 970 information shared and the fact that it might be available for the 971 entire world to see. Sharing location information, for example, 972 would potentially put a person in danger from any individual who 973 might seek to inflict harm on that person. 975 The easy access to user information via WebFinger was a design goal 976 of the protocol, not a limitation. If one wishes to limit access to 977 information available via WebFinger, such as a WebFinger server for 978 use inside a corporate network, the network administrator must take 979 measures necessary to limit access from outside the network. Using 980 standard methods for securing web resources, network administrators 981 do have the ability to control access to resources that might return 982 sensitive information. Further, WebFinger servers can be employed in 983 such a way as to require authentication and prevent disclosure of 984 information to unauthorized entities. 986 12. IANA Considerations 988 RFC Editor: Please replace QQQQ in the following two sub-sections 989 with a reference to this RFC. 991 12.1. Registration of the "acct" Link Relation Type 993 Relation Name: acct 995 Description: A link relation that refers to a user's WebFinger 996 account identifier. 998 Reference: RFC QQQQ 1000 Notes: 1002 Application Data: 1004 13. Acknowledgments 1006 The authors would like to acknowledge Eran Hammer-Lahav, Blaine Cook, 1007 Brad Fitzpatrick, Laurent-Walter Goix, Joe Clarke, Mike Jones, and 1008 Peter Saint-Andre for their invaluable input. 1010 14. References 1012 14.1. Normative References 1014 [1] Bradner, S., "Key words for use in RFCs to Indicate Requirement 1015 Levels", BCP 14, RFC 2119, March 1997. 1017 [2] Fielding, R., Gettys, J., Mogul, J., Frystyk, H., 1018 Masinter, L., Leach, P., and T. Berners-Lee, "Hypertext 1019 Transfer Protocol -- HTTP/1.1", RFC 2616, June 1999. 1021 [3] Nottingham, M., Hammer-Lahav, E., "Defining Well-Known Uniform 1022 Resource Identifiers (URIs)", RFC 5785, April 2010. 1024 [4] Nottingham, M., "Web Linking", RFC 5988, October 2010. 1026 [5] Crockford, D., "The application/json Media Type for 1027 JavaScript Object Notation (JSON)", RFC 4627, July 2006. 1029 [6] Berners-Lee, T., Fielding, R., and Masinter, L., "Uniform 1030 Resource Identifier (URI): Generic Syntax", STD 66, RFC 3986, 1031 January 2005. 1033 [7] Saint-Andre, P., "The 'acct' URI Scheme", draft-ietf-appsawg- 1034 acct-uri-00, August 2012. 1036 [8] Duerst, M., Masinter, L., and J. Zawinski, "The 'mailto' URI 1037 Scheme", RFC 6068, October 2010. 1039 [9] Van Kesteren, A., "Cross-Origin Resource Sharing", W3C CORS 1040 http://www.w3.org/TR/cors/, July 2010. 1042 [10] Hammer-Lahav, E. and W. Norris, "Extensible Resource Descriptor 1043 (XRD) Version 1.0", http://docs.oasis- 1044 open.org/xri/xrd/v1.0/xrd-1.0.html. 1046 [11] Hammer-Lahav, E. and Cook, B., "Web Host Metadata", RFC 6415, 1047 October 2011. 1049 [12] American National Standards Institute, "Coded Character Set - 1050 7-bit American Standard Code for Information Interchange", ANSI 1051 X3.4, 1986. 1053 [13] Duerst, M., "Internationalized Resource Identifiers (IRIs)", 1054 RFC 3987, January 2005. 1056 14.2. Informative References 1058 [14] Zimmerman, D., "The Finger User Information Protocol", RFC 1059 1288, December 1991. 1061 [15] Hansen, T., Hardie, T., and L. Masinter, "Guidelines and 1062 Registration Procedures for New URI Schemes", BCP 35, RFC 4395, 1063 February 2006. 1065 [16] Perreault, S., "vCard Format Specification", RFC 6350, August 1066 2011. 1068 [17] Internet Assigned Numbers Authority (IANA) Registry, "Uniform 1069 Resource Identifier (URI) Schemes", 1070 . 1072 [18] "Transport Independent, Printer/System Interface", IEEE Std 1073 1284.1-1997, 1997. 1075 [19] Hoffman, P., Yergeau, F., "UTF-16, an encoding of ISO 10646", 1076 RFC 2781, February 2000. 1078 APPENDIX A: XRD Usage (Non-normative) 1080 A.1. How XRD Documents are Requested via WebFinger 1082 The framework for using XRD documents with WebFinger is as follows: 1084 1. WebFinger clients issue request for XRD documents by requesting 1085 the Web Host Metadata document located at the well-known URI 1086 /.well-known/host-meta at the host. 1087 2. The web server at the host returns an XRD document, including a 1088 Link-based Resource Descriptor Document (LRDD) link relation. 1089 3. To discover information about accounts, devices, or other 1090 entities associated with the host, a request is issued for the 1091 Link-based Resource Descriptor Document(s) associated with a 1092 particular URI at the host (e.g., an "acct" URI, "http" URI, or 1093 "mailto" URI). 1094 4. The web server at the host would return an XRD document about 1095 the requested URI, which included those resource-specific link 1096 relations pointing to resources that contain information about 1097 the entity. 1098 5. Following the procedures in Section 4.2 of RFC 6415, the client 1099 would assemble all of the resource-specific link relations from 1100 the host-meta resource and LRDD resource(s) into a complete 1101 resource descriptor. 1103 The LRDD resources return resource descriptor documents of the type 1104 "application/xrd+xml". 1106 A.2. WebFinger Example using XRDs 1108 Section 4 introduces examples where JRD documents are returned to 1109 clients. For completeness, this section shows an example where a 1110 client requests an XRD document. 1112 Recall the example from Section 4.1 where the email client tried to 1113 retrieve information about Bob to discover the URL for his blog. If 1114 the client implemented support for XRD, it tries to get the host 1115 metadata information for the domain example.com in a similar way. As 1116 with the original example, it issues the following HTTPS query to 1117 example.com: 1119 GET /.well-known/host-meta HTTP/1.1 1120 Host: example.com 1122 The server replies with an XRD document: 1124 HTTP/1.1 200 OK 1125 Access-Control-Allow-Origin: * 1126 Content-Type: application/xrd+xml; charset=UTF-8 1127 1128 1129 1132 1134 The client then processes the received XRD in accordance with the Web 1135 Host Metadata procedures. The client will see the LRDD link relation 1136 and issue a query with the user's account URI [6] or other URI that 1137 serves as an alias for the account. (The account URI is discussed in 1138 Section 4.2.) The query might look like this: 1140 GET /lrdd/?uri=acct%3Abob%40example.com HTTP/1.1 1141 Host: example.com 1143 The server might then respond with a message like this: 1145 HTTP/1.1 200 OK 1146 Access-Control-Allow-Origin: * 1147 Content-Type: application/xrd+xml; charset=UTF-8 1149 1150 1151 2012-10-12T20:56:11Z 1152 acct:bob@example.com 1153 http://www.example.com/~bob/ 1154 1156 1158 1160 1162 The email client might take note of the "blog" link relation in the 1163 above XRD document that refers to Bob's blog. This URL would then be 1164 presented to you so that you could then visit his blog. 1166 A.3. Security Considerations Related to XRDs 1168 When using HTTP to request an XRD document, WebFinger clients SHOULD 1169 verify the XRD document's signature, if present, to ensure that the 1170 XRD document has not been modified. Additionally, WebFinger servers 1171 SHOULD include a signature for XRD documents served over HTTP. 1173 Author's Addresses 1175 Paul E. Jones 1176 Cisco Systems, Inc. 1177 7025 Kit Creek Rd. 1178 Research Triangle Park, NC 27709 1179 USA 1181 Phone: +1 919 476 2048 1182 Email: paulej@packetizer.com 1183 IM: xmpp:paulej@packetizer.com 1185 Gonzalo Salgueiro 1186 Cisco Systems, Inc. 1187 7025 Kit Creek Rd. 1188 Research Triangle Park, NC 27709 1189 USA 1191 Phone: +1 919 392 3266 1192 Email: gsalguei@cisco.com 1193 IM: xmpp:gsalguei@cisco.com 1195 Joseph Smarr 1196 Google 1198 Email: jsmarr@google.com