idnits 2.17.1 draft-ietf-appsawg-webfinger-02.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- 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 22, 2012) is 4196 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 1052, but no explicit reference was found in the text == Unused Reference: '15' is defined on line 1064, but no explicit reference was found in the text == Unused Reference: '17' is defined on line 1071, but no explicit reference was found in the text == Unused Reference: '19' is defined on line 1078, 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 22, 2013 Joseph Smarr 6 Google 7 October 22, 2012 9 WebFinger 10 draft-ietf-appsawg-webfinger-02.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 22, 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 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. Note that an RFC 6415-compliant server 471 might not implement the "resource" parameter, though the server would 472 respond to queries from the client as described in RFC 6415. Thus, 473 WebFinger clients MUST check the server response to ensure that the 474 "resource" parameter is supported as explained below. 476 To utilize the host-meta "resource" parameter, a WebFinger client 477 issues a request to /.well-known/host-meta.json (RECOMMENDED) or 478 /.well-known/host-meta as usual, but then appends a "resource" 479 parameter as shown in this example: 481 GET /.well-known/host-meta.json?resource=\ 482 acct%3Abob%40example.com HTTP/1.1 483 Host: example.com 485 When processing this request, the WebFinger server MUST 486 * Return a 404 status code if the URI provided in the resource 487 parameter is unknown to the server; and 489 * Set the "Subject" returned in the response to the value of the 490 "resource" parameter if the URI provided in the resource 491 parameter is known to the server; and 493 * Collect and expand all resource-specific link relations, 494 including those returned by querying for any LRDD link 495 relations, discard any host-wide link relations, and return a 496 complete resource descriptor following the processing rules in 497 Section 4.2 of RFC 6415; and 499 It is not the responsibility of the WebFinger server to verify, for 500 example, that a URI pointing to a person's avatar is a valid URI. If 501 the WebFinger server needs to query an LRDD resource to collect 502 additional resource-specific information, any errors (e.g., 500 or 503 404) MUST be ignored by the server. When a request for an LRDD 504 fails, the server MUST NOT attempt to augment missing resource 505 information or return a "template" type link relation to a client 506 that utilizes the "resource" parameter. Note that a WebFinger server 507 might be implemented such that all LRDD resource-specific information 508 can be resolved without issuing HTTP requests. How a WebFinger 509 server collects and expands such resource-specific link relations is 510 an implementation matter. 512 The WebFinger client MUST verify support for the "resource" parameter 513 by checking the value of the Subject returned in the response. If 514 the Subject matches the value of the "resource" parameter, then the 515 "resource" parameter is supported by the server. The Subject would 516 be absent if the "resource" parameter is not supported. 518 For illustrative purposes, the following is an example usage of the 519 "resource" parameter that aligns with the example in Section 1.1.1 of 520 RFC 6415. The WebFinger client would issue this request: 522 GET /.well-known/host-meta.json?resource=\ 523 http%3A%2F%2Fexample.com%2Fxy HTTP/1.1 524 Host: example.com 526 Note: The "\" character shown above and used throughout this document 527 indicates that the line breaks at this point and continues on the 528 next line. The content of the next line should be concatenated to 529 the previous line without any whitespace characters, replacing the 530 "\" character. This is shown only to avoid line wrapping in this 531 document. 533 The WebFinger server would reply with this response: 535 HTTP/1.1 200 OK 536 Access-Control-Allow-Origin: * 537 Content-Type: application/json; charset=UTF-8 539 { 540 "subject" : "http://example.com/xy", 541 "properties" : 542 { 543 "http://spec.example.net/color" : "red" 544 }, 545 "links" : 546 [ 547 { 548 "rel" : "hub", 549 "href" : "http://example.com/hub" 550 }, 551 { 552 "rel" : "hub", 553 "href" : "http://example.com/another/hub" 554 }, 555 { 556 "rel" : "author", 557 "href" : "http://example.com/john" 558 }, 559 { 560 "rel" : "author", 561 "href" : "http://example.com/author?\ 562 q=http%3A%2F%2Fexample.com%2Fxy" 563 } 564 ] 565 } 567 5.3. The Web Host Metadata "rel" Parameter 569 WebFinger also defines the "rel" parameter for use when querying for 570 host metadata or resource-specific information. It is used to return 571 a subset of the information that would otherwise be returned without 572 the "rel" parameter. When the "rel" parameter is used, only the link 573 relations that match the space-separated list of link relations 574 provided via "rel" are included in the list of links returned in the 575 resource descriptor. All other information normally present in a 576 resource descriptor is present in the resource descriptor, even when 577 "rel" is employed. 579 The purpose of the "rel" parameter is to return a subset of 580 resource's link relations. It is not intended to reduce the work 581 required of a server to produce a response. That said, use of the 582 parameter might reduce processing requirements on either the client 583 or server, and it might also reduce the bandwidth required to convey 584 the partial resource descriptor, especially if there are numerous 585 link relation values to convey for a given resource. 587 Support for the "rel" parameter is OPTIONAL, but support is 588 RECOMMENDED for the host-meta resources and LRDD resources. 590 For illustrative purposes, the following is an example usage of the 591 "rel" parameter that aligns with the example in Section 1.1.1 of RFC 592 6415. The WebFinger client would issue this request to receive links 593 that are of the type "hub" and "copyright": 595 GET /.well-known/host-meta.json?resource=\ 596 http%3A%2F%2Fexample.com%2Fxy&rel=hub%20copyright HTTP/1.1 597 Host: example.com 599 The WebFinger server would reply with this response: 601 HTTP/1.1 200 OK 602 Access-Control-Allow-Origin: * 603 Content-Type: application/json; charset=UTF-8 605 { 606 "subject" : "http://example.com/xy", 607 "properties" : 608 { 609 "http://spec.example.net/color" : "red" 610 }, 611 "links" : 612 [ 613 { 614 "rel" : "hub", 615 "href" : "http://example.com/hub" 616 }, 617 { 618 "rel" : "hub", 619 "href" : "http://example.com/another/hub" 620 } 621 ] 622 } 624 Note that in this example, the "author" links are removed, though all 625 other content is present. Since there were no "copyright" links, 626 none are returned. 628 In the event that a client requests links for link relations that are 629 not defined for the specified resource, a resource descriptor MUST be 630 returned, void of any links. When a JRD is returned, the "links" 631 array MAY be either absent or empty. The server MUST NOT return a 632 404 status code when a particular link relation specified via "rel" 633 is not defined for the resource, as a 404 status code is reserved for 634 indicating that the resource itself (e.g., either /.well-known/host- 635 meta.json or the resource indicated via the "resource" parameter) 636 does not exist. 638 5.4. WebFinger and URIs 640 Requests for both LRDD documents and host metadata can include a 641 parameter specifying the URI of an account, device, or other entity 642 (for LRDD this is the "uri" parameter as defined by the operative JRD 643 or XRD template and for host metadata this is the "resource" 644 parameter). WebFinger itself is agnostic regarding the scheme of 645 such a URI: it could be an "acct" URI [7], an "http" or "https" URI, 646 a "mailto" URI, or some other scheme. 648 For resources associated with a user account at a host, use of the 649 "acct" URI scheme is RECOMMENDED, since it explicitly identifies an 650 account accessible via WebFinger. Further, the "acct" URI scheme is 651 not associated with other protocols as, by way of example, the 652 "mailto" URI scheme is associated with email. Since not every host 653 offers email service, using the "mailto" URI scheme [8] is not ideal 654 for identifying user accounts on all hosts. That said, use of the 655 "mailto" URI scheme would be ideal for use with WebFinger to discover 656 mail server configuration information for a user, for example. 658 A host MAY utilize one or more URIs that serve as aliases for the 659 user's account, such as URIs that use the "http" URI scheme [2]. A 660 WebFinger server MUST return substantially the same response to both 661 an "acct" URI and any alias URI for the account, including the same 662 set of link relations and properties. In addition, the server SHOULD 663 include the entire list aliases for the user's account in the JRD or 664 XRD returned when querying the LRDD resource or when utilizing the 665 "resource" parameter. 667 6. The "acct" Link Relation 669 6.1. Purpose for the "acct" Link Relation 671 Users of some services might have an "acct" URI that looks 672 significantly different from his or her email address, perhaps using 673 an entirely different domain name. It is also possible for a user to 674 have multiple accounts that a user wants to have cross-referenced 675 from another account. To address both of these needs, this 676 specification defines the "acct" link relation. 678 The "acct" link relation allows a resource descriptor to reference 679 one or more other user account URIs. The "acct" link relation is 680 intended to allow a client to incorporate additional link relations 681 by reference so that it might utilize a more complete set of link 682 relations for a user. For example, a user acct:bob@example.com might 683 wish to allow a client to discover additional information about him 684 by including an "acct" link relation with the URI 685 acct:bob@example.net. 687 Note that the "acct" link relation does not replace the use of 688 standard HTTP 3xx response codes to indicate the new temporary or 689 permanent location of a user account. If a user account is moved to 690 a different location, then a 3xx response code SHOULD be used. Also, 691 the "acct" link relation does not replace Link-based Resource 692 Descriptor Documents (LRDDs). A WebFinger server might return 693 multiple LRDD link relations for a user, each of which perhaps 694 containing link relations that are to be merged to form a complete 695 resource descriptor. The "acct" link relation is different in that 696 it would refer to an entirely different, separate resource 697 descriptor. Further, only a client would act consider the "acct" 698 link relations as it performs queries, not the WebFinger server. 700 Since an account may make a reference to one or more different 701 accounts, WebFinger clients that support automatic processing of the 702 "acct" link relations MUST take steps to avoid loops wherein two 703 account URIs, directly or indirectly, refer the client to each other. 705 There are no limits on the number of "acct" link relations that might 706 be returned in a WebFinger query. 708 An "acct" link relation used within the context of a WebFinger query 709 for a user's account MUST NOT return "acct" link relations for 710 another user. 712 Client-side consideration of the "acct" link relation is OPTIONAL and 713 WebFinger server MUST NOT assume a client will perform additional 714 processing in response to receiving an "acct" link relation. 716 6.2. Example Message Exchange Using the "acct" Link Relation 718 Consider the following non-normative example. 720 Suppose Alice receives an email from bob@example.net. While Bob's 721 email identifier might be in the example.net domain, he holds a user 722 account in the example.com domain and another account in the 723 example.org domain. His email provider may provide WebFinger 724 services, but is unable to serve information from other domains. 726 Suppose Alice's client issues the following request: 728 GET /.well-known/host-meta.json?resource=\ 729 acct%3Abob%40example.net HTTP/1.1 730 Host: example.net 732 The response that Alice's client receives back might be: 734 HTTP/1.1 200 OK 735 Access-Control-Allow-Origin: * 736 Content-Type: application/json; charset=UTF-8 738 { 739 "subject" : "acct:bob@example.net", 740 "links" : 741 [ 742 { 743 "rel" : "acct", 744 "href" : "acct:bob@example.com" 745 }, 746 { 747 "rel" : "acct", 748 "href" : "acct:bob@example.org" 749 }, 750 { 751 "rel" : "acct", 752 "href" : "mailto:bob@example.net" 753 } 754 ] 755 } 757 While these link relations provide Alice with very little 758 information, Alice's WebFinger client could then perform subsequent 759 queries against the URIs acct:bob@example.com, acct:bob@example.org, 760 and mailto:bob@example.net in order to get the information Alice is 761 seeking. 763 7. Cross-Origin Resource Sharing (CORS) 765 WebFinger is most useful when it is accessible without restrictions 766 on the Internet, and that includes web browsers. Therefore, 767 WebFinger servers MUST support Cross-Origin Resource Sharing (CORS) 768 [9] when serving content intended for public consumption. 769 Specifically, all queries to /.well-known/host-meta.json, /.well- 770 known/host-meta, and to any LRDD URIs MUST include the following HTTP 771 header in the response: 773 Access-Control-Allow-Origin: * 775 Enterprise WebFinger servers that wish to restrict access to 776 information from external entities SHOULD use a more restrictive 777 Access-Control-Allow-Origin header and MAY exclude the header 778 entirely. 780 8. Controlling Access to Information 782 As with all web resources, access to the Host Metadata resource and 783 the LRDD resource MAY require authentication. Further, failure to 784 provide required credentials MAY result in the server forbidding 785 access or providing a different response than had the client 786 authenticated with the server. 788 Likewise, a server MAY provide different responses to different 789 clients based on other factors, such as whether the client is inside 790 or outside a corporate network. As a concrete example, a query 791 performed on the internal corporate network might return link 792 relations to employee pictures whereas link relations for employee 793 pictures might not be provided to external entities. 795 Further, link relations provided in a WebFinger server response MAY 796 point to web resources that impose access restrictions. For example, 797 it is possible that the aforementioned corporate server may provide 798 both internal and external entities with URIs to employee pictures, 799 but further authentication MAY be required in order for the WebFinger 800 client to access those picture resources if the request comes from 801 outside the corporate network. 803 The decisions made with respect to what set of link relations a 804 WebFinger server provides to one client versus another and what 805 resources require further authentication, as well as the specific 806 authentication mechanisms employed, are outside the scope of this 807 document. 809 9. Hosted and Distributed WebFinger Services 811 9.1. Hosting the Entire Domain 813 As with most services provided on the Internet, it is possible for a 814 domain owner to utilize "hosted" WebFinger services. By way of 815 example, a domain owner might control most aspects of their domain, 816 but use a third-party hosting service email. In the case of email, 817 mail servers for a domain are identified by MX records. An MX record 818 points to the mail server to which mail for the domain should be 819 delivered. It does not matter to the sending mail server whether 820 those MX records point to a server in the destination domain or a 821 different domain. 823 Likewise, a domain owner might utilize the services of a third party 824 to provide WebFinger services on behalf of its users. Just as a 825 domain owner was required to insert MX records into DNS to allow for 826 hosted email serves, the domain owner is required to redirect HTTP(S) 827 queries to its domain to allow for hosted WebFinger services. 829 When a query is issued to /.well-known/host-meta.json or /.well- 830 known/host-meta, the target domain's web server MUST return a 301, 831 302, or 307 response status code that includes a Location header 832 pointing to the location of the hosted WebFinger service URL. The 833 WebFinger service URL does not need to point to /.well-known/* on the 834 hosting service provider server. In fact, it should not, as that 835 location would be reserved for queries relating to the service 836 provider's domain. WebFinger clients MUST follow all 301, 302, or 837 307 redirection requests. 839 As an example, let's assume that example.com's WebFinger services are 840 hosted by example.net. Suppose a client issues a query for 841 acct:alice@example.com like this: 843 GET /.well-known/host-meta.json? 844 resource=acct%3Aalice%40example.com HTTP/1.1 845 Host: example.com 847 The server might respond with this: 849 HTTP/1.1 301 Moved Permanently 850 Location: http://wf.example.net/example.org/host-meta.json 852 The client should follow the request, re-issuing the request to the 853 URL provided in the Location header. 855 Note that both of the /.well-known/host-meta.json and /.well- 856 known/host-meta resources need to be considered when redirecting 857 request to third party service providers. Those URLs requests SHOULD 858 NOT be redirected to the same location and without any 859 differentiation, since the default format returned by host-meta.json 860 is a JRD and the default format returned by host-meta MAY be XRD. 861 Each resource is distinct and should be redirected separately and to 862 different service locations or differentiated with a URI parameter. 863 Since the "Referer" HTTP header field is not mandatory, service 864 providers cannot rely on that header to determine the URL of the 865 original request. 867 9.2. Distributed WebFinger Services 869 A domain owner may wish to manage only a part of its WebFinger 870 services and WebFinger service providers or the domain owner may wish 871 to distribute WebFinger services across a number of WebFinger service 872 locations. The key to enabling this type of distribution is 873 placement of resource-specific information in more than one LRDD 874 document, each document existing at different locations. 876 Assume that the company operating example.com manages its own 877 WebFinger services, but also wants to utilize the services of 878 example.org to serve link relations related to some aspects of its 879 business. Suppose a client issued this request: 881 GET /.well-known/host-meta.json HTTP/1.1 882 Host: example.com 884 The server might reply with this JRD document: 886 HTTP/1.1 200 OK 887 Access-Control-Allow-Origin: * 888 Content-Type: application/json; charset=UTF-8 890 { 891 "links" : 892 [ 893 { 894 "rel" : "lrdd", 895 "type" : "application/json", 896 "template" : "https://example.com/lrdd/?f=json&uri={uri}" 897 }, 898 { 899 "rel" : "lrdd", 900 "type" : "application/json", 901 "template" : "https://wf.example.org/lrdd/?f=json&uri={uri}" 902 } 903 ] 904 } 906 This would indicate to the client that some of the resource-specific 907 information is found at example.com and some is found at example.org, 908 following those specific URLs. Observing the rules in Section 4.2 of 909 RFC 6415, the client would issue queries to both URLs and construct a 910 complete resource descriptor. 912 As discussed in Section 5.2, a client may issue a query like this to 913 the example.com domain: 915 GET /.well-known/host-meta.json?resource=\ 916 acct%3Aalice%40example.com HTTP/1.1 917 Host: example.com 919 In that case, it would be the responsibility of the WebFinger server 920 at example.com to query the LRDD URL at example.org and then compose 921 a complete descriptor document. The client that uses the resource 922 parameter remains entirely oblivious to the fact that link relation 923 information is distributed across multiple servers or domains. 925 10. Web Host Metadata Interoperability Considerations 927 As noted in Section 3, RFC 6415 required all servers to support the 928 production of Extensible Resource Documents (XRDs) and optionally 929 support the production of JSON Resource Documents (JRDs). This 930 specification reverses that requirement: WebFinger-compliant servers 931 MUST support JRD and MAY support XRD documents. 933 Given that some servers might implement only RFC 6415 and other 934 servers might implement only the minimum required set of features 935 defined for WebFinger, all clients should take care to ensure to 936 request a resource descriptor in the appropriate format. If a client 937 wishes to receive only JRDs, for example, it SHOULD issue a request 938 to /.well-known/host-meta.json, but MAY issue a request to /.well- 939 known/host-meta and include the "Accept" header with the type 940 "application/json". 942 Further, clients MUST ensure that the response returned from the 943 server contains the correct format. RFC 6415-compliant servers might 944 return an XRD document, regardless of what is requested by the 945 client. 947 Lastly, RFC 6415 did not require clients to follow 301, 302, or 307 948 redirection requests, but WebFinger clients MUST re-issue requests 949 when redirected using any of those HTTP status codes. 951 11. Security Considerations 953 All of the security considerations applicable to Web Host Metadata 954 and Cross-Origin Resource Sharing [9] are also applicable to this 955 specification. Of particular importance is the recommended use of 956 HTTPS to ensure that information is not modified during transit. 957 Clients SHOULD verify that the certificate used on an HTTPS 958 connection is valid. 960 Service providers and users should be aware that placing information 961 on the Internet accessible through WebFinger means that any user can 962 access that information. While WebFinger can be an extremely useful 963 tool for allowing quick and easy access to one's avatar, blog, or 964 other personal information, users should understand the risks, too. 965 If one does not wish to share certain information with the world, do 966 not allow that information to be freely accessible through WebFinger. 968 The aforementioned word of caution is perhaps worth emphasizing again 969 with respect to dynamic information one might wish to share, such as 970 the current location of a user. WebFinger can be a powerful tool 971 used to assemble information about a person all in one place, but 972 service providers and users should be mindful of the nature of that 973 information shared and the fact that it might be available for the 974 entire world to see. Sharing location information, for example, 975 would potentially put a person in danger from any individual who 976 might seek to inflict harm on that person. 978 The easy access to user information via WebFinger was a design goal 979 of the protocol, not a limitation. If one wishes to limit access to 980 information available via WebFinger, such as a WebFinger server for 981 use inside a corporate network, the network administrator must take 982 measures necessary to limit access from outside the network. Using 983 standard methods for securing web resources, network administrators 984 do have the ability to control access to resources that might return 985 sensitive information. Further, WebFinger servers can be employed in 986 such a way as to require authentication and prevent disclosure of 987 information to unauthorized entities. 989 12. IANA Considerations 991 RFC Editor: Please replace QQQQ in the following two sub-sections 992 with a reference to this RFC. 994 12.1. Registration of the "acct" Link Relation Type 996 Relation Name: acct 998 Description: A link relation that refers to a user's WebFinger 999 account identifier. 1001 Reference: RFC QQQQ 1003 Notes: 1005 Application Data: 1007 13. Acknowledgments 1009 The authors would like to acknowledge Eran Hammer-Lahav, Blaine Cook, 1010 Brad Fitzpatrick, Laurent-Walter Goix, Joe Clarke, Mike Jones, and 1011 Peter Saint-Andre for their invaluable input. 1013 14. References 1015 14.1. Normative References 1017 [1] Bradner, S., "Key words for use in RFCs to Indicate Requirement 1018 Levels", BCP 14, RFC 2119, March 1997. 1020 [2] Fielding, R., Gettys, J., Mogul, J., Frystyk, H., 1021 Masinter, L., Leach, P., and T. Berners-Lee, "Hypertext 1022 Transfer Protocol -- HTTP/1.1", RFC 2616, June 1999. 1024 [3] Nottingham, M., Hammer-Lahav, E., "Defining Well-Known Uniform 1025 Resource Identifiers (URIs)", RFC 5785, April 2010. 1027 [4] Nottingham, M., "Web Linking", RFC 5988, October 2010. 1029 [5] Crockford, D., "The application/json Media Type for 1030 JavaScript Object Notation (JSON)", RFC 4627, July 2006. 1032 [6] Berners-Lee, T., Fielding, R., and Masinter, L., "Uniform 1033 Resource Identifier (URI): Generic Syntax", STD 66, RFC 3986, 1034 January 2005. 1036 [7] Saint-Andre, P., "The 'acct' URI Scheme", draft-ietf-appsawg- 1037 acct-uri-00, August 2012. 1039 [8] Duerst, M., Masinter, L., and J. Zawinski, "The 'mailto' URI 1040 Scheme", RFC 6068, October 2010. 1042 [9] Van Kesteren, A., "Cross-Origin Resource Sharing", W3C CORS 1043 http://www.w3.org/TR/cors/, July 2010. 1045 [10] Hammer-Lahav, E. and W. Norris, "Extensible Resource Descriptor 1046 (XRD) Version 1.0", http://docs.oasis- 1047 open.org/xri/xrd/v1.0/xrd-1.0.html. 1049 [11] Hammer-Lahav, E. and Cook, B., "Web Host Metadata", RFC 6415, 1050 October 2011. 1052 [12] American National Standards Institute, "Coded Character Set - 1053 7-bit American Standard Code for Information Interchange", ANSI 1054 X3.4, 1986. 1056 [13] Duerst, M., "Internationalized Resource Identifiers (IRIs)", 1057 RFC 3987, January 2005. 1059 14.2. Informative References 1061 [14] Zimmerman, D., "The Finger User Information Protocol", RFC 1062 1288, December 1991. 1064 [15] Hansen, T., Hardie, T., and L. Masinter, "Guidelines and 1065 Registration Procedures for New URI Schemes", BCP 35, RFC 4395, 1066 February 2006. 1068 [16] Perreault, S., "vCard Format Specification", RFC 6350, August 1069 2011. 1071 [17] Internet Assigned Numbers Authority (IANA) Registry, "Uniform 1072 Resource Identifier (URI) Schemes", 1073 . 1075 [18] "Transport Independent, Printer/System Interface", IEEE Std 1076 1284.1-1997, 1997. 1078 [19] Hoffman, P., Yergeau, F., "UTF-16, an encoding of ISO 10646", 1079 RFC 2781, February 2000. 1081 APPENDIX A: XRD Usage (Non-normative) 1083 A.1. How XRD Documents are Requested via WebFinger 1085 The framework for using XRD documents with WebFinger is as follows: 1087 1. WebFinger clients issue request for XRD documents by requesting 1088 the Web Host Metadata document located at the well-known URI 1089 /.well-known/host-meta at the host. 1090 2. The web server at the host returns an XRD document, including a 1091 Link-based Resource Descriptor Document (LRDD) link relation. 1092 3. To discover information about accounts, devices, or other 1093 entities associated with the host, a request is issued for the 1094 Link-based Resource Descriptor Document(s) associated with a 1095 particular URI at the host (e.g., an "acct" URI, "http" URI, or 1096 "mailto" URI). 1097 4. The web server at the host would return an XRD document about 1098 the requested URI, which included those resource-specific link 1099 relations pointing to resources that contain information about 1100 the entity. 1101 5. Following the procedures in Section 4.2 of RFC 6415, the client 1102 would assemble all of the resource-specific link relations from 1103 the host-meta resource and LRDD resource(s) into a complete 1104 resource descriptor. 1106 The LRDD resources return resource descriptor documents of the type 1107 "application/xrd+xml". 1109 A.2. WebFinger Example using XRDs 1111 Section 4 introduces examples where JRD documents are returned to 1112 clients. For completeness, this section shows an example where a 1113 client requests an XRD document. 1115 Recall the example from Section 4.1 where the email client tried to 1116 retrieve information about Bob to discover the URL for his blog. If 1117 the client implemented support for XRD, it tries to get the host 1118 metadata information for the domain example.com in a similar way. As 1119 with the original example, it issues the following HTTPS query to 1120 example.com: 1122 GET /.well-known/host-meta HTTP/1.1 1123 Host: example.com 1125 The server replies with an XRD document: 1127 HTTP/1.1 200 OK 1128 Access-Control-Allow-Origin: * 1129 Content-Type: application/xrd+xml; charset=UTF-8 1130 1131 1132 1135 1137 The client then processes the received XRD in accordance with the Web 1138 Host Metadata procedures. The client will see the LRDD link relation 1139 and issue a query with the user's account URI [6] or other URI that 1140 serves as an alias for the account. (The account URI is discussed in 1141 Section 4.2.) The query might look like this: 1143 GET /lrdd/?uri=acct%3Abob%40example.com HTTP/1.1 1144 Host: example.com 1146 The server might then respond with a message like this: 1148 HTTP/1.1 200 OK 1149 Access-Control-Allow-Origin: * 1150 Content-Type: application/xrd+xml; charset=UTF-8 1152 1153 1154 2012-10-12T20:56:11Z 1155 acct:bob@example.com 1156 http://www.example.com/~bob/ 1157 1159 1161 1163 1165 The email client might take note of the "blog" link relation in the 1166 above XRD document that refers to Bob's blog. This URL would then be 1167 presented to you so that you could then visit his blog. 1169 A.3. Security Considerations Related to XRDs 1171 When using HTTP to request an XRD document, WebFinger clients SHOULD 1172 verify the XRD document's signature, if present, to ensure that the 1173 XRD document has not been modified. Additionally, WebFinger servers 1174 SHOULD include a signature for XRD documents served over HTTP. 1176 Author's Addresses 1178 Paul E. Jones 1179 Cisco Systems, Inc. 1180 7025 Kit Creek Rd. 1181 Research Triangle Park, NC 27709 1182 USA 1184 Phone: +1 919 476 2048 1185 Email: paulej@packetizer.com 1186 IM: xmpp:paulej@packetizer.com 1188 Gonzalo Salgueiro 1189 Cisco Systems, Inc. 1190 7025 Kit Creek Rd. 1191 Research Triangle Park, NC 27709 1192 USA 1194 Phone: +1 919 392 3266 1195 Email: gsalguei@cisco.com 1196 IM: xmpp:gsalguei@cisco.com 1198 Joseph Smarr 1199 Google 1201 Email: jsmarr@google.com