idnits 2.17.1 draft-ietf-appsawg-webfinger-09.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 (January 28, 2013) is 4106 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) ** 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-02 -- Possible downref: Non-RFC (?) normative reference: ref. '9' -- Possible downref: Non-RFC (?) normative reference: ref. '10' -- Possible downref: Non-RFC (?) normative reference: ref. '11' ** Obsolete normative reference: RFC 4288 (ref. '12') (Obsoleted by RFC 6838) ** Obsolete normative reference: RFC 2818 (ref. '14') (Obsoleted by RFC 9110) Summary: 6 errors (**), 0 flaws (~~), 2 warnings (==), 5 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Network Working Group Paul E. Jones 3 Internet Draft Gonzalo Salgueiro 4 Intended status: Standards Track Cisco Systems 5 Expires: July 28, 2013 Joseph Smarr 6 Google 7 January 28, 2013 9 WebFinger 10 draft-ietf-appsawg-webfinger-09.txt 12 Abstract 14 This specification defines the WebFinger protocol, which can be used 15 to discover information about people or other entities on the 16 Internet using standard HTTP methods. 18 Status of this Memo 20 This Internet-Draft is submitted in full conformance with the 21 provisions of BCP 78 and BCP 79. 23 Internet-Drafts are working documents of the Internet Engineering 24 Task Force (IETF). Note that other groups may also distribute 25 working documents as Internet-Drafts. The list of current Internet- 26 Drafts is at http://datatracker.ietf.org/drafts/current/. 28 Internet-Drafts are draft documents valid for a maximum of six months 29 and may be updated, replaced, or obsoleted by other documents at any 30 time. It is inappropriate to use Internet-Drafts as reference 31 material or to cite them other than as "work in progress." 33 This Internet-Draft will expire on July 28, 2013. 35 Copyright Notice 37 Copyright (c) 2013 IETF Trust and the persons identified as the 38 document authors. All rights reserved. 40 This document is subject to BCP 78 and the IETF Trust's Legal 41 Provisions Relating to IETF Documents 42 (http://trustee.ietf.org/license-info) in effect on the date of 43 publication of this document. Please review these documents 44 carefully, as they describe your rights and restrictions with respect 45 to this document. Code Components extracted from this document must 46 include Simplified BSD License text as described in Section 4.e of 47 the Trust Legal Provisions and are provided without warranty as 48 described in the Simplified BSD License. 50 Table of Contents 52 1. Introduction...................................................2 53 2. Terminology....................................................3 54 3. Example Uses of WebFinger......................................3 55 3.1. Locating a User's Blog....................................3 56 3.2. Identity Provider Discovery for OpenID Connect............5 57 3.3. Auto-Configuration of Email Clients.......................6 58 3.4. Retrieving Device Information.............................7 59 4. WebFinger Protocol.............................................7 60 4.1. Constructing a WebFinger Query............................8 61 4.2. Performing a WebFinger Query..............................8 62 4.3. The "rel" Parameter.......................................9 63 4.4. The JSON Resource Descriptor (JRD).......................10 64 4.4.1. expires.............................................11 65 4.4.2. subject.............................................11 66 4.4.3. aliases.............................................11 67 4.4.4. properties..........................................11 68 4.4.5. links...............................................12 69 4.5. WebFinger and URIs.......................................14 70 5. Cross-Origin Resource Sharing (CORS)..........................14 71 6. Access Control................................................15 72 7. Hosted WebFinger Services.....................................15 73 8. Security Considerations.......................................16 74 9. IANA Considerations...........................................17 75 10. Acknowledgments..............................................18 76 11. References...................................................18 77 11.1. Normative References....................................18 78 11.2. Informative References..................................19 79 Author's Addresses...............................................20 81 1. Introduction 83 WebFinger is used to discover information about people or other 84 entities on the Internet that are identified by a URI [6] or IRI [7] 85 using standard Hypertext Transfer Protocol (HTTP) [2] methods over a 86 secure transport [14]. A WebFinger server returns a JavaScript 87 Object Notation (JSON) [5] object that describes a resource that is 88 queried. The JSON object is referred to as the JSON Resource 89 Descriptor (JRD). 91 For a person, the kinds of information that might be discoverable via 92 WebFinger include a personal profile address, identity service, 93 telephone number, or preferred avatar. For other entities on the 94 Internet, a WebFinger server might return JRDs containing link 95 relations that allow a client to discover, for example, the amount of 96 toner in a printer or the physical location of a server. 98 Information returned via WebFinger might be for direct human 99 consumption (e.g., looking up someone's phone number), or it might be 100 used by systems to help carry out some operation (e.g., facilitate 101 logging into a web site by determining a user's identity service). 103 Use of WebFinger is illustrated in the examples in Section 3 and 104 described more formally in Section 4. 106 2. Terminology 108 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 109 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 110 document are to be interpreted as described in RFC 2119 [1]. 112 WebFinger makes heavy use of "Link Relations". Briefly, a Link 113 Relation is an attribute and value pair used on the Internet wherein 114 the attribute identifies the type of link to which the associated 115 value refers. In HTTP and Web Linking [4], the attribute is a "rel" 116 and the value is an "href". WebFinger also uses the "rel" attribute, 117 where the "rel" value is either a single IANA-registered link 118 relation type [10] or a URI [6]. 120 3. Example Uses of WebFinger 122 This non-normative section shows a few sample uses of WebFinger. 124 3.1. Locating a User's Blog 126 Assume you receive an email from Bob and he refers to something he 127 posted on his blog, but you do not know where Bob's blog is located. 128 It would be simple to discover the address of Bob's blog if he makes 129 that information available via WebFinger. 131 Assume your email client can discover the blog for you. After 132 receiving the message from Bob (bob@example.com), you instruct your 133 email client to perform a WebFinger query. It does so by issuing the 134 following HTTPS [14] query to example.com: 136 GET /.well-known/webfinger? 137 resource=acct%3Abob%40example.com HTTP/1.1 138 Host: example.com 140 The server might then respond with a message like this: 142 HTTP/1.1 200 OK 143 Access-Control-Allow-Origin: * 144 Content-Type: application/json; charset=UTF-8 146 { 147 "expires" : "2012-11-16T19:41:35Z", 148 "subject" : "acct:bob@example.com", 149 "aliases" : 150 [ 151 "http://www.example.com/~bob/" 152 ], 153 "properties" : 154 { 155 "http://example.com/ns/role/" : "employee" 156 }, 157 "links" : 158 [ 159 { 160 "rel" : "http://webfinger.net/rel/avatar", 161 "type" : "image/jpeg", 162 "href" : "http://www.example.com/~bob/bob.jpg" 163 }, 164 { 165 "rel" : "http://webfinger.net/rel/profile-page", 166 "href" : "http://www.example.com/~bob/" 167 }, 168 { 169 "rel" : "blog", 170 "type" : "text/html", 171 "href" : "http://blogs.example.com/bob/", 172 "titles" : 173 { 174 "en-us" : "The Magical World of Bob", 175 "fr" : "Le monde magique de Bob" 176 } 177 }, 178 { 179 "rel" : "vcard", 180 "href" : "https://www.example.com/~bob/bob.vcf" 181 } 182 ] 183 } 185 The email client would take note of the "blog" link relation in the 186 above JRD that refers to Bob's blog. This URL would then be 187 presented to you so that you could then visit his blog. The email 188 client might also note that Bob has published an avatar link relation 189 and use that picture to represent Bob inside the email client. 190 Lastly, the client might consider the vcard [16] link relation in 191 order to update contact information for Bob. 193 In the above example, an "acct" URI [8] is used in the query, though 194 any valid alias for the user might also be used. See section 4.5 for 195 more information on WebFinger and URIs. 197 An alias is a URI that is different from the "subject" URI that 198 identifies the same entity. In the above example, there is one 199 "http" alias returned, though there might have been more than one. 200 Had the "http:" URI shown as an alias been used to query for 201 information about Bob, the query would have appeared as: 203 GET /.well-known/webfinger? 204 resource=http%3A%2F%2Fwww.example.com%2F~bob%2F HTTP/1.1 205 Host: www.example.com 207 Note that the host queried in this example is different than for the 208 acct URI example, since the URI refers to a different host. Either 209 this host would provide a response, or it would redirect the client 210 to another host (e.g., redirect back to example.com). Either way, 211 the response would have been substantially the same, with the subject 212 and alias information changed as necessary. Other information, such 213 as the expiration time might also change, but the set of link 214 relations and properties would be the same with either response. 216 3.2. Identity Provider Discovery for OpenID Connect 218 Suppose Carol wishes to authenticate with a web site she visits using 219 OpenID Connect [18]. She would provide the web site with her OpenID 220 Connect identifier, say carol@example.com. The visited web site 221 would perform a WebFinger query looking for the OpenID Connect 222 Provider. Since the site is interested in only one particular link 223 relation, the server might utilize the "rel" parameter as described 224 in Section 4.3: 226 GET /.well-known/webfinger? 227 resource=acct%3Acarol%40example.com& 228 rel=http%3A%2F%2Fopenid.net%2Fspecs%2Fconnect%2F1.0%2Fissuer 229 HTTP/1.1 230 Host: example.com 232 The server might respond with a JRD like this: 234 { 235 "expires" : "2012-11-16T19:41:35Z", 236 "subject" : "acct:carol@example.com", 237 "links" : 238 [ 239 { 240 "rel" : "http://openid.net/specs/connect/1.0/issuer", 241 "href" : "https://openid.example.com" 242 } 243 ] 244 } 246 Since the "rel" parameter only filters the link relations returned by 247 the server, other name/value pairs in the response, including any 248 aliases or properties, would be returned. Also, since support for 249 the "rel" parameter is optional, the client must not assume the 250 "links" array will contain only the requested link relation. 252 3.3. Auto-Configuration of Email Clients 254 WebFinger could be used to auto-provision an email client with basic 255 configuration data. Suppose that sue@example.com wants to configure 256 her email client. Her email client might issue the following query: 258 GET /.well-known/webfinger? 259 resource=mailto%3Asue%40example.com HTTP/1.1 260 Host: example.com 262 The response from the server would contain entries for the various 263 protocols, transport options, and security options. If there are 264 multiple options, the server might return a link relation that for 265 each of the valid options and the client or Sue might select which 266 option to choose. Since JRDs list link relations in a specific 267 order, then the most-preferred choices could be presented first. 268 Consider this response: 270 { 271 "subject" : "mailto:sue@example.com", 272 "links" : 273 [ 274 { 275 "rel" : "http://example.net/rel/smtp-server", 276 "properties" : 277 { 278 "http://example.net/email/host" : "smtp.example.com", 279 "http://example.net/email/port" : "587", 280 "http://example.net/email/login-required" : "yes", 281 "http://example.net/email/transport" : "starttls" 282 } 283 }, 284 { 285 "rel" : "http://example.net/rel/imap-server", 286 "properties" : 287 { 288 "http://example.net/email/host" : "imap.example.com", 289 "http://example.net/email/port" : "993", 290 "http://example.net/email/transport" : "ssl" 291 } 292 } 293 ] 294 } 295 In this example, you can see that the WebFinger server advertises an 296 SMTP service and an IMAP service. In this example, the "href" 297 entries associated with the link relation are absent. This is valid 298 when there is no external reference that needs to be made. 300 3.4. Retrieving Device Information 302 As another example, suppose there are printers on the network and you 303 would like to check the current toner level for a particular printer 304 identified via the URI device:p1.example.com. While the "device" URI 305 scheme is not presently specified, we use it here for illustrative 306 purposes. 308 Following the procedures similar to those above, a query may be 309 issued to get link relations specific to this URI like this: 311 GET /.well-known/webfinger? 312 resource=device%3Ap1.example.com HTTP/1.1 313 Host: p1.example.com 315 The link relations that are returned for a device may be quite 316 different than those for user accounts. Perhaps we may see a 317 response like this: 319 HTTP/1.1 200 OK 320 Access-Control-Allow-Origin: * 321 Content-Type: application/json; charset=UTF-8 323 { 324 "subject" : "device:p1.example.com", 325 "links" : 326 [ 327 { 328 "rel" : "http://example.com/rel/tipsi", 329 "href" : "http://192.168.1.5/npap/" 330 } 331 ] 332 } 334 While this example is fictitious, you can imagine that perhaps the 335 Transport Independent, Printer/System Interface [17] may be enhanced 336 with a web interface that allows a device that understands the TIP/SI 337 web interface specification to query the printer for toner levels. 339 4. WebFinger Protocol 341 WebFinger is a simple HTTP-based web service that returns a JSON 342 Resource Descriptor (JRD) to convey information about an entity on 343 the Internet and the Cross-Origin Resource Sharing (CORS) [9] 344 specification to facilitate queries made via a web browser. 346 4.1. Constructing a WebFinger Query 348 This specification defines URI parameters that are passed from the 349 client to the server when issuing a request. These parameters, 350 "resource" and "rel", and the parameter values are included in the 351 "query" component of the URI (see Section 3.4 of RFC 3986). To 352 construct the "query" component, the client performs the following 353 steps. First, each parameter value is percent-encoded as per Section 354 2.1 of RFC 3986. Next, the client constructs a string to be placed 355 in the query component by concatenating the name of the first 356 parameter together with an equal sign ("=") and the percent-encoded 357 parameter value. For any subsequent parameters, the client appends 358 an ampersand ("&") to the string, the name of the next parameter, an 359 equal sign, and percent-encoded parameter value. The client MUST NOT 360 insert any spaces while constructing the string. The order in which 361 the client places each parameter and its corresponding parameter 362 value is unspecified. 364 4.2. Performing a WebFinger Query 366 A WebFinger client issues a query to the well-known [3] resource 367 /.well-known/webfinger. A query MUST include the "resource" 368 parameter exactly once and set to the value of the URI for which 369 information is being sought. If the "resource" parameter is absent 370 or malformed, the WebFinger server MUST indicate that the request is 371 bad as per Section 10.4.1 of RFC 2616 [2]. 373 A client MUST query the WebFinger server using HTTPS only. If the 374 client determines that the server has an invalid certificate, the 375 server returns a 4xx or 5xx status code, or the HTTPS connection 376 cannot be established for any reason, the client MUST accept that the 377 WebFinger query has failed and MUST NOT attempt to reissue the 378 WebFinger request using HTTP over a non-secure connection. 380 A WebFinger server MUST return a JRD as the representation for the 381 resource if the client requests no other supported format explicitly 382 via the HTTP "Accept" header. The client MAY include the "Accept" 383 header to indicate a desired representation, though no other 384 representation than JRD is defined in this specification. The media 385 type used for the JSON Resource Descriptor (JRD) is 386 "application/json" [5]. 388 A WebFinger server MAY redirect the client, but MUST only redirect 389 the client to an HTTPS URI. 391 A WebFinger server can include cache validators in a response to 392 enable conditional requests by the client and/or expiration times as 393 per Section 13 of RFC 2616. 395 4.3. The "rel" Parameter 397 When issuing a request to the server, the client MAY utilize the 398 "rel" parameter to request only a subset of the information that 399 would otherwise be returned without the "rel" parameter. When the 400 "rel" parameter is used, only the link relations that match the link 401 relations provided via "rel" are included in the array of links 402 returned in the JRD. All other information normally present in a 403 resource descriptor is present in the resource descriptor, even when 404 "rel" is employed. 406 The "rel" parameter MAY be transmitted to the server multiple times 407 in order to request multiple types of link relations. 409 The purpose of the "rel" parameter is to return a subset of 410 resource's link relations. Use of the parameter might reduce 411 processing requirements on either the client or server, and it might 412 also reduce the bandwidth required to convey the partial resource 413 descriptor, especially if there are numerous link relation values to 414 convey for a given resource. 416 Support for the "rel" parameter is OPTIONAL, but RECOMMENDED on the 417 server. Should the server not support the "rel" parameter, it MUST 418 ignore it and process the request as if no "rel" parameter values 419 were present. 421 The following example presents the same example as found in Section 422 3.1, but uses the "rel" parameter in order to select two link 423 relations: 425 GET /.well-known/webfinger? 426 resource=acct%3Abob%40example.com& 427 rel=http%3A%2F%2Fwebfinger.net%2Frel%2Fprofile-page& 428 rel=vcard HTTP/1.1 429 Host: example.com 431 In this example, the client requests the link relations of type 432 "http://webfinger.net/rel/profile-page" and "vcard". The server then 433 responds with a message like this: 435 HTTP/1.1 200 OK 436 Access-Control-Allow-Origin: * 437 Content-Type: application/json; charset=UTF-8 439 { 440 "expires" : "2012-11-16T19:41:35Z", 441 "subject" : "acct:bob@example.com", 442 "aliases" : 443 [ 444 "http://www.example.com/~bob/" 445 ], 446 "properties" : 447 { 448 "http://example.com/ns/role/" : "employee" 449 }, 450 "links" : 451 [ 452 { 453 "rel" : "http://webfinger.net/rel/profile-page", 454 "href" : "http://www.example.com/~bob/" 455 }, 456 { 457 "rel" : "vcard", 458 "href" : "http://www.example.com/~bob/bob.vcf" 459 } 460 ] 461 } 463 As you can see, the server returned only the link relations requested 464 by the client, but also included the other parts of the JRD. 466 In the event that a client requests links for link relations that are 467 not defined for the specified resource, a resource descriptor MUST be 468 returned. In the returned JRD, the "links" array MAY be absent, 469 empty, or contain only links that did match a provided "rel" value. 471 4.4. The JSON Resource Descriptor (JRD) 473 The JSON Resource Descriptor (JRD), originally introduced in RFC 6415 474 [19] and based on the Extensible Resource Descriptor (XRD) format 475 [20], is a JSON object that is comprised of the following name/value 476 pairs: 478 o expires 479 o subject 480 o aliases 481 o properties 482 o links 484 The members "expires" and "subject" are name/value pairs whose value 485 are strings, "aliases" is an array of strings, "properties" is an 486 object comprised of name/value pairs whose values are strings, and 487 "links" is an array of objects that contain link relation 488 information. 490 When processing a JRD, the client MUST ignore any unknown member and 491 not treat the presence of an unknown member as an error. 493 Below, each of these members of the JRD is described in more detail. 495 4.4.1. expires 497 The value of the "expires" member is a string that indicates the date 498 and time after which the JRD SHOULD be considered expired and no 499 longer utilized. 501 This format is formally defined in RFC 3339 [15]. 503 The "expires" member MUST NOT use fractional seconds and MUST express 504 time only Universal Coordinate Time via the "Z" designation on the 505 end of the string. 507 An example of the "expires" member is: 509 "expires" : "2012-11-16T19:41:35Z" 511 The "expires" member is optional in a JRD, but SHOULD be honored if 512 present. 514 4.4.2. subject 516 The value of the "subject" member is a URI that identifies the entity 517 that the JRD describes. 519 The "subject" value returned by a WebFinger server MAY differ from 520 the value of the "resource" parameter used in the client's request. 521 This may happen, for example, when the subject's identity changes 522 (e.g., a user moves his or her account to another service) or when 523 the server prefers to express URIs in canonical form. 525 The "subject" member MUST be present. 527 4.4.3. aliases 529 The "aliases" array is an array of zero or more URI strings that 530 identify the same entity as the "subject" URI. Each URI must be an 531 absolute URI. 533 The "aliases" array is optional. 535 4.4.4. properties 537 The "properties" object is comprised of zero or more name/value pairs 538 whose names are absolute URIs and whose values are strings or null. 540 Properties are used to convey additional information about the 541 subject of the JRD. As an example, consider this use of 542 "properties": 544 "properties" : { "http://webfinger.net/ns/name" : "Bob Smith" } 546 The "properties" member is optional. 548 4.4.5. links 550 The "links" array contains zero or more elements that contain the 551 link relation information. Each element of the array is an object 552 comprised of the following name/value pairs: 554 o rel 555 o type 556 o href 557 o titles 558 o properties 560 The members "rel", "type", and "href" are a name/value pairs whose 561 values are strings, "titles" and "properties" are objects comprised 562 of name/value pairs whose values are strings. 564 The order of elements in the "links" array indicates an order of 565 preference. Thus, if there are two or more link relations having the 566 same "rel" value, the first link relation would indicate the user's 567 preferred link relation. 569 The "links" array is optional in the JRD. 571 Below, each of the members of the objects found in the "links" array 572 is described in more detail. Each object in the "links" array, 573 referred to as a "link relation object", is completely independent 574 from any other object in the array; any requirement to include a 575 given member in the link relation object refers only to that 576 particular object. 578 4.4.5.1. rel 580 The value of the "rel" member is a string that is either an absolute 581 URI or a registered relation type [10] (see RFC 5988 [4]). The value 582 of the "rel" member MUST contain exactly one URI string or registered 583 relation type and MUST NOT contain a space-separated list of URIs or 584 registered relation types. The URI or registered relation type 585 identifies the type of the link relation. The other members of the 586 object have meaning only once the type of link relation is 587 understood. In some instances, the link relation will have 588 associated semantics that allow a client to query for other resources 589 on the Internet. In other instances, the link relation will have 590 associated semantics that allow the client to utilize the other 591 members of the link relation object without fetching additional 592 external resources. 594 The "rel" member MUST be present in the link relation object. 596 4.4.5.2. type 598 The value of the "type" member is a string that indicates the media 599 type [11] of the linked resource (see RFC 4288 [12]). 601 The "type" member is optional in the link relation object. 603 4.4.5.3. href 605 The value of the "href" member is a string that contains a URI 606 pointing to the linked resource. 608 The "href" member is optional in the link relation object. 610 4.4.5.4. titles 612 The "titles" object is comprised of zero or more name/value pairs 613 whose name is a language tag [13] or the string "default". The 614 string is human-readable and describes the link relation. More than 615 one title for the link relation MAY be provided for the benefit of 616 users who utilize the link relation and, if used, a language 617 identifier SHOULD be duly used as the name. If the language is 618 unknown or unspecified, then the name is "default". 620 A JRD SHOULD NOT include more than one title identified with the same 621 language tag (or "default") within the link relation object. Meaning 622 is undefined if a link relation object includes more than one title 623 named with the same language tag (or "default"), though this MUST NOT 624 treat this as an error. A client MAY select whichever title or 625 titles it wishes to utilize. 627 Here is an example of the titles object: 629 "titles" : 630 { 631 "en-us" : "The Magical World of Bob", 632 "fr" : "Le monde magique de Bob" 633 } 635 The "titles" member is optional in the link relation object. 637 4.4.5.5. properties 639 The "properties" object within the link relation object is comprised 640 of zero or more name/value pairs whose names are absolute URIs and 641 whose values are strings or null. Properties are used to convey 642 additional information about the link relation. As an example, 643 consider this use of "properties": 645 "properties" : { "http://example.net/mail/port" : "993" } 647 The "properties" member is optional in the link relation object. 649 4.5. WebFinger and URIs 651 WebFinger requests can include a parameter specifying the URI of an 652 account, device, or other entity. WebFinger is agnostic regarding 653 the scheme of such a URI: it could be an "acct" URI [7], an "http" or 654 "https" URI, a "mailto" URI [21], or some other scheme. 656 For resources associated with a user account at a host, use of the 657 "acct" URI scheme is RECOMMENDED, since it explicitly identifies an 658 account accessible via WebFinger. Further, the "acct" URI scheme is 659 not associated with other protocols as, by way of example, the 660 "mailto" URI scheme is associated with email. Since not every host 661 offers email service, using the "mailto" URI scheme is not ideal for 662 identifying user accounts on all hosts. That said, use of the 663 "mailto" URI scheme would be ideal for use with WebFinger to discover 664 mail server configuration information for a user. 666 5. Cross-Origin Resource Sharing (CORS) 668 WebFinger resources might not be accessible from a web browser due to 669 "Same-Origin" policies. The current best practice is to make 670 resources available to browsers through Cross-Origin Resource Sharing 671 (CORS) [9], and servers MUST include the Access-Control-Allow-Origin 672 HTTP header in responses. Servers SHOULD support the least 673 restrictive setting by allowing any domain access to the WebFinger 674 resources: 676 Access-Control-Allow-Origin: * 678 There are cases where defaulting to the least restrictive setting is 679 not appropriate, for example a WebFinger server on an intranet that 680 provides sensitive company information should not allow CORS requests 681 from any domain, as that could allow leaking of that sensitive 682 information. A WebFinger server that wishes to restrict access to 683 information from external entities SHOULD use a more restrictive 684 Access-Control-Allow-Origin header. 686 6. Access Control 688 As with all web resources, access to the /.well-known/webfinger 689 resource MAY require authentication. Further, failure to provide 690 required credentials MAY result in the server forbidding access or 691 providing a different response than had the client authenticated with 692 the server. 694 Likewise, a server MAY provide different responses to different 695 clients based on other factors, such as whether the client is inside 696 or outside a corporate network. As a concrete example, a query 697 performed on the internal corporate network might return link 698 relations to employee pictures, whereas link relations for employee 699 pictures might not be provided to external entities. 701 Further, link relations provided in a WebFinger server response MAY 702 point to web resources that impose access restrictions. For example, 703 the aforementioned corporate server may provide both internal and 704 external entities with URIs to employee pictures, but further 705 authentication might be required in order for the client to access 706 the picture resources if the request comes from outside the corporate 707 network. 709 The decisions made with respect to what set of link relations a 710 WebFinger server provides to one client versus another and what 711 resources require further authentication, as well as the specific 712 authentication mechanisms employed, are outside the scope of this 713 document. 715 7. Hosted WebFinger Services 717 As with most services provided on the Internet, it is possible for a 718 domain owner to utilize "hosted" WebFinger services. By way of 719 example, a domain owner might control most aspects of their domain, 720 but use a third-party hosting service for email. In the case of 721 email, mail servers for a domain are identified by MX records. An MX 722 record points to the mail server to which mail for the domain should 723 be delivered. It does not matter to the sending mail server whether 724 those MX records point to a server in the destination domain or a 725 different domain. 727 Likewise, a domain owner might utilize the services of a third party 728 to provide WebFinger services on behalf of its users. Just as a 729 domain owner was required to insert MX records into DNS to allow for 730 hosted email serves, the domain owner is required to redirect HTTP 731 queries to its domain to allow for hosted WebFinger services. 733 When a query is issued to /.well-known/webfinger, the web server MUST 734 return a response with a redirection status code that includes a 735 Location header pointing to the location of the hosted WebFinger 736 service URL. The WebFinger service URL does not need to point to 737 /.well-known/* on the hosting service provider server. 739 As an example, assume that example.com's WebFinger services are 740 hosted by example.net. Suppose a client issues a query for 741 acct:alice@example.com like this: 743 GET /.well-known/webfinger? 744 resource=acct%3Aalice%40example.com HTTP/1.1 745 Host: example.com 747 The server might respond with this: 749 HTTP/1.1 307 Temporary Redirect 750 Access-Control-Allow-Origin: * 751 Location: https://wf.example.net/example.com/webfinger? 752 resource=acct%3Aalice%40example.com HTTP/1.1 754 The client can then follow the redirection, re-issuing the request to 755 the URL provided in the Location header. Note that the server will 756 include any required URI parameters in the Location header value, 757 which could be different than the URI parameters the client 758 originally used. 760 8. Security Considerations 762 Since this specification utilizes Cross-Origin Resource Sharing 763 (CORS) [9], all of the security considerations applicable CORS are 764 also applicable to this specification. 766 The required use of HTTPS is to ensure that information is not 767 modified during transit. It should be appreciated that in 768 environments where a web server is normally available, there exists 769 the possibility that a compromised network might have its WebFinger 770 server operating on HTTPS replaced with one operating only over HTTP. 771 As such, clients MUST NOT issue queries over a non-secure connection. 773 Clients MUST verify that the certificate used on an HTTPS connection 774 is valid and accept a response only if the certificate is valid. 776 Service providers and users should be aware that placing information 777 on the Internet accessible through WebFinger means that any user can 778 access that information. While WebFinger can be an extremely useful 779 tool for allowing quick and easy access to one's avatar, blog, or 780 other personal information, users should understand the risks, too. 781 If one does not wish to share certain information with the world, do 782 not allow that information to be freely accessible through WebFinger 783 and do not use any service supporting WebFinger. Further, a 784 WebFinger server MUST NOT be used to provide any personal information 785 to any party unless explicitly or implicitly authorized by the person 786 whose information is being shared. Implicit authorization can be 787 determined by the user's voluntary utilization of a service as 788 defined by that service's relevant terms of use or published privacy 789 policy. 791 The aforementioned word of caution is perhaps worth emphasizing again 792 with respect to dynamic information one might wish to share, such as 793 the current location of a user. WebFinger can be a powerful tool 794 used to assemble information about a person all in one place, but 795 service providers and users should be mindful of the nature of that 796 information shared and the fact that it might be available for the 797 entire world to see. Sharing location information, for example, 798 would potentially put a person in danger from any individual who 799 might seek to inflict harm on that person. 801 The easy access to user information via WebFinger was a design goal 802 of the protocol, not a limitation. If one wishes to limit access to 803 information available via WebFinger, such as a WebFinger server for 804 use inside a corporate network, the network administrator must take 805 measures necessary to limit access from outside the network. Using 806 standard methods for securing web resources, network administrators 807 do have the ability to control access to resources that might return 808 sensitive information. Further, a WebFinger server can be employed 809 in such a way as to require authentication and prevent disclosure of 810 information to unauthorized entities. 812 Finally, a WebFinger server has no means of ensuring that information 813 provided by a user is accurate. Likewise, neither the server nor the 814 client can be absolutely guaranteed that information has not been 815 manipulated either at the server or along the communication path 816 between the client and server. Use of HTTPS helps to address some 817 concerns with manipulation of information along the communication 818 path, but it clearly cannot address issues where the server provided 819 incorrect information, either due to being provided false information 820 or due to malicious behavior on the part of the server administrator. 821 As with any information service available on the Internet, users 822 should wary of information received from untrusted sources. 824 9. IANA Considerations 826 This specification registers the "webfinger" well-known URI in the 827 Well-Known URI Registry as defined by [3]. 829 URI suffix: webfinger 831 Change controller: IETF 832 Specification document(s): RFC QQQ 834 Related information: The response from WebFinger server will be a 835 JSON Resource Descriptor (JRD) as described in section 4.4 of RFC 836 QQQ. 838 [RFC EDITOR: Please replace "QQQ" references in this section with the 839 number for this RFC.] 841 10. Acknowledgments 843 The authors would like to acknowledge Eran Hammer-Lahav, Blaine Cook, 844 Brad Fitzpatrick, Laurent-Walter Goix, Joe Clarke, Michael B. Jones, 845 Peter Saint-Andre, Dick Hardt, Tim Bray, and Joe Gregorio for their 846 invaluable input. 848 11. References 850 11.1. Normative References 852 [1] Bradner, S., "Key words for use in RFCs to Indicate Requirement 853 Levels", BCP 14, RFC 2119, March 1997. 855 [2] Fielding, R., Gettys, J., Mogul, J., Frystyk, H., Masinter, L., 856 Leach, P., and T. Berners-Lee, "Hypertext Transfer Protocol -- 857 HTTP/1.1", RFC 2616, June 1999. 859 [3] Nottingham, M., Hammer-Lahav, E., "Defining Well-Known Uniform 860 Resource Identifiers (URIs)", RFC 5785, April 2010. 862 [4] Nottingham, M., "Web Linking", RFC 5988, October 2010. 864 [5] Crockford, D., "The application/json Media Type for JavaScript 865 Object Notation (JSON)", RFC 4627, July 2006. 867 [6] Berners-Lee, T., Fielding, R., and Masinter, L., "Uniform 868 Resource Identifier (URI): Generic Syntax", STD 66, RFC 3986, 869 January 2005. 871 [7] Duerst, M., "Internationalized Resource Identifiers (IRIs)", 872 RFC 3987, January 2005. 874 [8] Saint-Andre, P., "The 'acct' URI Scheme", draft-ietf-appsawg- 875 acct-uri-02, December 2012. 877 [9] Van Kesteren, A., "Cross-Origin Resource Sharing", W3C CORS 878 http://www.w3.org/TR/cors/, July 2010. 880 [10] IANA, "Link Relations", http://www.iana.org/assignments/link- 881 relations/. 883 [11] IANA, "MIME Media Types", 884 http://www.iana.org/assignments/media-types/index.html. 886 [12] Freed, N., Klensin, J., "Media Type Specifications and 887 Registration Procedures", RFC 4288, December 2005. 889 [13] Phillips, A., Davis, M., "Tags for Identifying Languages", RFC 890 5646, January 2001. 892 [14] Rescorla, E., "HTTP Over TLS", RFC 2818, May 2000. 894 [15] Klyne, G., Newman, C., "Date and Time on the Internet: 895 Timestamps", RFC 3339, July 2002. 897 11.2. Informative References 899 [16] Perreault, S., "vCard Format Specification", RFC 6350, August 900 2011. 902 [17] "Transport Independent, Printer/System Interface", IEEE Std 903 1284.1-1997, 1997. 905 [18] Sakimura, N., Bradley, J., Jones, M., de Medeiros, B., 906 Mortimore, C., and E. Jay, "OpenID Connect Messages 1.0", June 907 2012, http://openid.net/specs/openid-connect-messages-1_0.html. 909 [19] Hammer-Lahav, E. and Cook, B., "Web Host Metadata", RFC 6415, 910 October 2011. 912 [20] Hammer-Lahav, E. and W. Norris, "Extensible Resource Descriptor 913 (XRD) Version 1.0", http://docs.oasis- 914 open.org/xri/xrd/v1.0/xrd-1.0.html. 916 [21] Duerst, M., Masinter, L., and J. Zawinski, "The 'mailto' URI 917 Scheme", RFC 6068, October 2010. 919 Author's Addresses 921 Paul E. Jones 922 Cisco Systems, Inc. 923 7025 Kit Creek Rd. 924 Research Triangle Park, NC 27709 925 USA 927 Phone: +1 919 476 2048 928 Email: paulej@packetizer.com 929 IM: xmpp:paulej@packetizer.com 931 Gonzalo Salgueiro 932 Cisco Systems, Inc. 933 7025 Kit Creek Rd. 934 Research Triangle Park, NC 27709 935 USA 937 Phone: +1 919 392 3266 938 Email: gsalguei@cisco.com 939 IM: xmpp:gsalguei@cisco.com 941 Joseph Smarr 942 Google 944 Email: jsmarr@google.com