idnits 2.17.1 draft-ietf-appsawg-webfinger-12.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 (March 28, 2013) is 4046 days in the past. Is this intentional? Checking references for intended status: Proposed Standard ---------------------------------------------------------------------------- (See RFCs 3967 and 4897 for information about using normative references to lower-maturity documents in RFCs) == Unused Reference: '15' is defined on line 1036, 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-03 -- 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 2818 (ref. '14') (Obsoleted by RFC 9110) Summary: 5 errors (**), 0 flaws (~~), 3 warnings (==), 4 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: September 28, 2013 Joseph Smarr 6 Google 7 March 28, 2013 9 WebFinger 10 draft-ietf-appsawg-webfinger-12.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. WebFinger discovers 17 information for a URI that might not be usable as a locator 18 otherwise, such as account or email URIs. 20 Status of this Memo 22 This Internet-Draft is submitted in full conformance with the 23 provisions of BCP 78 and BCP 79. 25 Internet-Drafts are working documents of the Internet Engineering 26 Task Force (IETF). Note that other groups may also distribute 27 working documents as Internet-Drafts. The list of current Internet- 28 Drafts is at http://datatracker.ietf.org/drafts/current/. 30 Internet-Drafts are draft documents valid for a maximum of six months 31 and may be updated, replaced, or obsoleted by other documents at any 32 time. It is inappropriate to use Internet-Drafts as reference 33 material or to cite them other than as "work in progress." 35 This Internet-Draft will expire on September 28, 2013. 37 Copyright Notice 39 Copyright (c) 2013 IETF Trust and the persons identified as the 40 document authors. All rights reserved. 42 This document is subject to BCP 78 and the IETF Trust's Legal 43 Provisions Relating to IETF Documents 44 (http://trustee.ietf.org/license-info) in effect on the date of 45 publication of this document. Please review these documents 46 carefully, as they describe your rights and restrictions with respect 47 to this document. Code Components extracted from this document must 48 include Simplified BSD License text as described in Section 4.e of 49 the Trust Legal Provisions and are provided without warranty as 50 described in the Simplified BSD License. 52 Table of Contents 54 1. Introduction...................................................2 55 2. Terminology....................................................3 56 3. Example Uses of WebFinger......................................3 57 3.1. Locating a User's Blog....................................3 58 3.2. Identity Provider Discovery for OpenID Connect............5 59 3.3. Auto-Configuration of Email Clients.......................6 60 3.4. Retrieving Device Information.............................7 61 4. WebFinger Protocol.............................................8 62 4.1. Constructing a WebFinger Request URI......................9 63 4.2. Performing a WebFinger Query..............................9 64 4.3. The "rel" Parameter......................................10 65 4.4. The JSON Resource Descriptor (JRD).......................11 66 4.4.1. subject.............................................12 67 4.4.2. aliases.............................................12 68 4.4.3. properties..........................................12 69 4.4.4. links...............................................12 70 4.5. WebFinger and URIs.......................................15 71 5. Cross-Origin Resource Sharing (CORS)..........................15 72 6. Access Control................................................15 73 7. Hosted WebFinger Services.....................................16 74 8. Security Considerations.......................................17 75 8.1. Transport-Related Issues.................................17 76 8.2. User Privacy Considerations..............................17 77 8.3. Abuse Potential..........................................18 78 8.4. Information Reliability..................................18 79 9. IANA Considerations...........................................19 80 9.1. Well-Known URI...........................................19 81 9.2. JSON Resource Descriptor (JRD) Media Type................19 82 10. Acknowledgments..............................................21 83 11. References...................................................21 84 11.1. Normative References....................................21 85 11.2. Informative References..................................22 86 Author's Addresses...............................................23 88 1. Introduction 90 WebFinger is used to discover information about people or other 91 entities on the Internet that are identified by a URI [6] or IRI [7] 92 using standard Hypertext Transfer Protocol (HTTP) [2] methods over a 93 secure transport [14]. A WebFinger resource returns a JavaScript 94 Object Notation (JSON) [5] object describing the entity that is 95 queried. The JSON object is referred to as the JSON Resource 96 Descriptor (JRD). 98 For a person, the kinds of information that might be discoverable via 99 WebFinger include a personal profile address, identity service, 100 telephone number, or preferred avatar. For other entities on the 101 Internet, a WebFinger resource might return JRDs containing link 102 relations [10] that enable a client to discover, for example, the 103 amount of toner in a printer or the physical location of a server. 105 Information returned via WebFinger might be for direct human 106 consumption (e.g., looking up someone's phone number), or it might be 107 used by systems to help carry out some operation (e.g., facilitate 108 logging into a web site by determining a user's identity service). 110 Use of WebFinger is illustrated in the examples in Section 3 and 111 described more formally in Section 4. 113 2. Terminology 115 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 116 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 117 document are to be interpreted as described in RFC 2119 [1]. 119 WebFinger makes heavy use of "Link Relations". A Link Relation is an 120 attribute-and-value pair in which the attribute identifies the type 121 of relationship between the linked entity or resource and the 122 information specified in the value. In Web Linking [4], the link 123 relation is represented using an HTTP entity-header of "Link", where 124 the "rel" attribute specifies the type of relationship and the "href" 125 attribute specifies the information that is linked to the entity or 126 resource. In WebFinger, the same concept is represented using a JSON 127 array of "links" objects, where each member named "rel" specifies the 128 type of relationship and each member named "href" specifies the 129 information that is linked to the entity or resource. Note that 130 WebFinger narrows the scope of a link relation beyond what is defined 131 for Web Linking by stipulating that the value of the "rel" member 132 needs to be either a single IANA-registered link relation type [10] 133 or a URI [6]. 135 3. Example Uses of WebFinger 137 This non-normative section shows a few sample uses of WebFinger. 139 3.1. Locating a User's Blog 141 Assume you receive an email from Bob and he refers to something he 142 posted on his blog, but you do not know where Bob's blog is located. 143 It would be simple to discover the address of Bob's blog if he made 144 that information available via WebFinger. 146 Assume your email client can discover the blog for you. After 147 receiving the message from Bob (bob@example.com), your email client 148 performs a WebFinger query either automatically or at your command. 149 It does so by issuing the following HTTPS [14] query to example.com: 151 GET /.well-known/webfinger? 152 resource=acct%3Abob%40example.com HTTP/1.1 153 Host: example.com 155 The server might then respond with a message like this: 157 HTTP/1.1 200 OK 158 Access-Control-Allow-Origin: * 159 Content-Type: application/jrd+json 161 { 162 "subject" : "acct:bob@example.com", 163 "aliases" : 164 [ 165 "http://www.example.com/~bob/" 166 ], 167 "properties" : 168 { 169 "http://example.com/ns/role/" : "employee" 170 }, 171 "links" : 172 [ 173 { 174 "rel" : "http://webfinger.example/rel/avatar", 175 "type" : "image/jpeg", 176 "href" : "http://www.example.com/~bob/bob.jpg" 177 }, 178 { 179 "rel" : "http://webfinger.example/rel/profile-page", 180 "href" : "http://www.example.com/~bob/" 181 }, 182 { 183 "rel" : "http://webfinger.example/rel/blog", 184 "type" : "text/html", 185 "href" : "http://blogs.example.com/bob/", 186 "titles" : 187 { 188 "en-us" : "The Magical World of Bob", 189 "fr" : "Le Monde Magique de Bob" 190 } 191 }, 192 { 193 "rel" : "http://webfinger.example/rel/businesscard", 194 "href" : "https://www.example.com/~bob/bob.vcf" 196 } 197 ] 198 } 200 Note the assumption made in the above example is that there is an 201 "acct" URI for the given "mailto" URI. This may not always be the 202 case. 204 The email client would take note of the link relation in the above 205 JRD that refers to Bob's blog. The blog's URI would then be 206 presented to you so that you could then visit his blog. The email 207 client might also note that Bob has published an avatar link relation 208 and use that picture to represent Bob inside the email client. 209 Lastly, the client might automatically retrieve the data located at 210 the URI specified by the "businesscard" link relation (which might be 211 a vcard [16]) to update the information about Bob in its internal 212 address book. 214 In the above example, an "acct" URI [8] is used in the query, though 215 any valid alias for the user might also be used. See Section 4.5 for 216 more information on WebFinger and URIs. 218 An alias is a URI that is different from the "subject" URI, yet 219 identifies the same entity. In the above example, there is one 220 "http" alias returned, though there might have been more than one. 221 Had the "http:" URI shown as an alias been used to query for 222 information about Bob, the query would have appeared as: 224 GET /.well-known/webfinger? 225 resource=http%3A%2F%2Fwww.example.com%2F~bob%2F HTTP/1.1 226 Host: www.example.com 228 Note that the host queried in this example is different than for the 229 acct URI example, since the URI refers to a different host. Either 230 this host would provide a response, or it would redirect the client 231 to another host (e.g., redirect back to example.com). Either way, 232 the response would have been substantially the same, with the subject 233 and alias information changed as necessary. 235 3.2. Identity Provider Discovery for OpenID Connect 237 Suppose Carol wishes to authenticate with a web site she visits using 238 OpenID Connect [18]. She would provide the web site with her OpenID 239 Connect identifier, say carol@example.com. The visited web site 240 would perform a WebFinger query looking for the OpenID Connect 241 Provider. Since the site is interested in only one particular link 242 relation, the WebFinger resource might utilize the "rel" parameter as 243 described in Section 4.3: 245 GET /.well-known/webfinger? 246 resource=acct%3Acarol%40example.com& 247 rel=http%3A%2F%2Fopenid.net%2Fspecs%2Fconnect%2F1.0%2Fissuer 248 HTTP/1.1 249 Host: example.com 251 The server might respond like this: 253 HTTP/1.1 200 OK 254 Access-Control-Allow-Origin: * 255 Content-Type: application/jrd+json 257 { 258 "subject" : "acct:carol@example.com", 259 "links" : 260 [ 261 { 262 "rel" : "http://openid.net/specs/connect/1.0/issuer", 263 "href" : "https://openid.example.com" 264 } 265 ] 266 } 268 Since the "rel" parameter only serves to filter the link relations 269 returned by the resource, other name/value pairs in the response, 270 including any aliases or properties, would be returned. Also, since 271 support for the "rel" parameter is not guaranteed, the client must 272 not assume the "links" array will contain only the requested link 273 relation. 275 3.3. Auto-Configuration of Email Clients 277 WebFinger could be used to auto-provision an email client with basic 278 configuration data. Suppose that sue@example.com wants to configure 279 her email client. Her email client might issue the following query: 281 GET /.well-known/webfinger? 282 resource=mailto%3Asue%40example.com HTTP/1.1 283 Host: example.com 285 The returned resource representation would contain entries for the 286 various protocols, transport options, and security options. If there 287 are multiple options, the resource representation might include a 288 link relation for each of the valid options, and the client or Sue 289 might select which option to choose. Since JRDs list link relations 290 in a specific order, then the most-preferred choices could be 291 presented first. Consider this response: 293 HTTP/1.1 200 OK 294 Access-Control-Allow-Origin: * 295 Content-Type: application/jrd+json 297 { 298 "subject" : "mailto:sue@example.com", 299 "links" : 300 [ 301 { 302 "rel" : "http://webfinger.example/rel/smtp-server", 303 "properties" : 304 { 305 "http://webfinger.example/email/host" : "smtp.example.com", 306 "http://webfinger.example/email/port" : "587", 307 "http://webfinger.example/email/login-required" : "yes", 308 "http://webfinger.example/email/transport" : "starttls" 309 } 310 }, 311 { 312 "rel" : "http://webfinger.example/rel/imap-server", 313 "properties" : 314 { 315 "http://webfinger.example/email/host" : "imap.example.com", 316 "http://webfinger.example/email/port" : "993", 317 "http://webfinger.example/email/transport" : "ssl" 318 } 319 } 320 ] 321 } 323 In this example, you can see that the WebFinger resource 324 representation advertises an SMTP service and an IMAP service. In 325 this example, the "href" entries associated with the link relation 326 are absent. This is valid when there is no additional reference that 327 needs to be made. 329 3.4. Retrieving Device Information 331 As another example, suppose there are printers on the network and you 332 would like to check the current toner level for a particular printer 333 identified via the URI device:p1.example.com. While the "device" URI 334 scheme is not presently specified, we use it here for illustrative 335 purposes. 337 Following the procedures similar to those above, a query may be 338 issued to get link relations specific to this URI like this: 340 GET /.well-known/webfinger? 341 resource=device%3Ap1.example.com HTTP/1.1 342 Host: p1.example.com 344 The link relations that are returned for a device may be quite 345 different than those for user accounts. Perhaps we may see a 346 response like this: 348 HTTP/1.1 200 OK 349 Access-Control-Allow-Origin: * 350 Content-Type: application/jrd+json 352 { 353 "subject" : "device:p1.example.com", 354 "links" : 355 [ 356 { 357 "rel" : "http://webfinger.example/rel/tipsi", 358 "href" : "http://192.168.1.5/npap/" 359 } 360 ] 361 } 363 While this example is fictitious, you can imagine that perhaps the 364 Transport Independent, Printer/System Interface [17] may be enhanced 365 with a web interface enabling a device that understands the TIP/SI 366 web interface specification to query the printer for toner levels. 368 4. WebFinger Protocol 370 A WebFinger resource is a well-known URI [3] using the HTTPS scheme. 371 WebFinger resources MUST NOT be served with any other URI scheme 372 (such as HTTP). 374 A WebFinger resource is always given a query target, which is another 375 URI that identifies the entity whose information is sought. GET 376 requests to a WebFinger resource convey the query target in the 377 "resource" parameter in the WebFinger URI's query string; see Section 378 4.1 for details. 380 The WebFinger resource returns a JSON Resource Descriptor (JRD) as 381 the resource representation to convey information about an entity on 382 the Internet. Also, the Cross-Origin Resource Sharing (CORS) [9] 383 specification is utilized to facilitate queries made via a web 384 browser. 386 4.1. Constructing a WebFinger Request URI 388 This specification defines parameters that can be passed from the 389 client to the WebFinger resource when issuing a request. These 390 parameters, "resource" and "rel", and the parameter values are 391 included in the query component of the URI (see Section 3.4 of RFC 392 3986). To construct the query component, the client performs the 393 following steps. First, each parameter value is percent-encoded, as 394 per Section 2.1 of RFC 3986. The encoding is done to conform to the 395 query production in Section 3.4 of that specification, with the 396 addition that any instances of the "=" and "&" characters within the 397 parameter values are also percent-encoded. Next, the client 398 constructs a string to be placed in the query component by 399 concatenating the name of the first parameter together with an equal 400 sign ("=") and the percent-encoded parameter value. For any 401 subsequent parameters, the client appends an ampersand ("&") to the 402 string, the name of the next parameter, an equal sign, and the 403 parameter value. The client MUST NOT insert any spaces while 404 constructing the string. The order in which the client places each 405 attribute-and-value pair within the query component does not matter 406 in the interpretation of the query component. 408 4.2. Performing a WebFinger Query 410 A WebFinger client issues a query to the well-known [3] resource 411 identified by the URI whose path component begins with "/.well- 412 known/webfinger" and whose query component MUST include the 413 "resource" parameter exactly once and set to the value of the URI for 414 which information is being sought. If the "resource" parameter is 415 absent or malformed, the WebFinger resource MUST indicate that the 416 request is bad as per Section 10.4.1 of RFC 2616 [2]. 418 A client MUST query the WebFinger resource using HTTPS only. If the 419 client determines that the resource has an invalid certificate, the 420 resource returns a 4xx or 5xx status code, or the HTTPS connection 421 cannot be established for any reason, then the client MUST accept 422 that the WebFinger query has failed and MUST NOT attempt to reissue 423 the WebFinger request using HTTP over a non-secure connection. 425 A WebFinger resource MUST return a JRD as the representation for the 426 resource if the client requests no other supported format explicitly 427 via the HTTP "Accept" header. The client MAY include the "Accept" 428 header to indicate a desired representation; representations other 429 than JRD might be defined in future specifications. The WebFinger 430 resource MUST silently ignore any requested representations that it 431 does not understand and support. The media type used for the JSON 432 Resource Descriptor (JRD) is "application/jrd+json" (see Section 433 9.2). 435 A WebFinger resource MAY redirect the client; if it does, the 436 redirection MUST only be to an "https" URI. 438 A WebFinger resource can include cache validators in a response to 439 enable conditional requests by the client and/or expiration times as 440 per Section 13 of RFC 2616. 442 4.3. The "rel" Parameter 444 When issuing a request to a WebFinger resource, the client MAY 445 utilize the "rel" parameter to request only a subset of the 446 information that would otherwise be returned without the "rel" 447 parameter. When the "rel" parameter is used and accepted, only the 448 link relation types that match the link relation types provided via 449 the "rel" parameter are included in the array of links returned in 450 the JRD. If there are no matching link relation types defined for 451 the resource, the "links" array in the JRD will either be absent or 452 empty. All other information present in a resource descriptor 453 remains present, even when "rel" is employed. 455 The "rel" parameter MAY be included multiple times in order to 456 request multiple link relation types. 458 The purpose of the "rel" parameter is to return a subset of "link 459 relation objects" (see Section 4.4.4) that would otherwise be 460 returned in the resource descriptor. Use of the parameter might 461 reduce processing requirements on either the client or server, and it 462 might also reduce the bandwidth required to convey the partial 463 resource descriptor, especially if there are numerous link relation 464 values to convey for a given "resource" value. 466 WebFinger resources SHOULD support the "rel" parameter. If the 467 resource does not support the "rel" parameter, it MUST ignore the 468 parameter and process the request as if no "rel" parameter values 469 were present. 471 The following example presents the same example as found in Section 472 3.1, but uses the "rel" parameter to select two link relations: 474 GET /.well-known/webfinger? 475 resource=acct%3Abob%40example.com& 476 rel=http%3A%2F%2Fwebfinger.example%2Frel%2Fprofile-page& 477 rel=http://webfinger.example/rel/businesscard HTTP/1.1 478 Host: example.com 480 In this example, the client requests the link relations of type 481 "http://webfinger.example/rel/profile-page" and 482 "http://webfinger.example/rel/businesscard". The server then 483 responds with a message like this: 485 HTTP/1.1 200 OK 486 Access-Control-Allow-Origin: * 487 Content-Type: application/jrd+json 489 { 490 "subject" : "acct:bob@example.com", 491 "aliases" : 492 [ 493 "http://www.example.com/~bob/" 494 ], 495 "properties" : 496 { 497 "http://example.com/ns/role/" : "employee" 498 }, 499 "links" : 500 [ 501 { 502 "rel" : "http://webfinger.example/rel/profile-page", 503 "href" : "http://www.example.com/~bob/" 504 }, 505 { 506 "rel" : "http://webfinger.example/rel/businesscard", 507 "href" : "http://www.example.com/~bob/bob.vcf" 508 } 509 ] 510 } 512 As you can see in the response, the resource representation contains 513 only the link relations requested by the client, but the other parts 514 of the JRD are still present. 516 4.4. The JSON Resource Descriptor (JRD) 518 The JSON Resource Descriptor (JRD), originally introduced in RFC 6415 519 [19] and based on the Extensible Resource Descriptor (XRD) format 520 [20], is a JSON object that comprises the following name/value pairs: 522 o subject 523 o aliases 524 o properties 525 o links 527 The member "subject" is a name/value pair whose value is a string, 528 "aliases" is an array of strings, "properties" is an object 529 comprising name/value pairs whose values are strings, and "links" is 530 an array of objects that contain link relation information. 532 When processing a JRD, the client MUST ignore any unknown member and 533 not treat the presence of an unknown member as an error. 535 Below, each of these members of the JRD is described in more detail. 537 4.4.1. subject 539 The value of the "subject" member is a URI that identifies the entity 540 that the JRD describes. 542 The "subject" value returned by a WebFinger resource MAY differ from 543 the value of the "resource" parameter used in the client's request. 544 This might happen, for example, when the subject's identity changes 545 (e.g., a user moves his or her account to another service) or when 546 the resource prefers to express URIs in canonical form. 548 The "subject" member MUST be present in the JRD. 550 4.4.2. aliases 552 The "aliases" array is an array of zero or more URI strings that 553 identify the same entity as the "subject" URI. Each URI must be an 554 absolute URI. 556 The "aliases" array is OPTIONAL in the JRD. 558 4.4.3. properties 560 The "properties" object comprises zero or more name/value pairs whose 561 names are absolute URIs and whose values are strings or null. 562 Properties are used to convey additional information about the 563 subject of the JRD. As an example, consider this use of 564 "properties": 566 "properties" : { "http://webfinger.example/ns/name" : "Bob Smith" } 568 The "properties" member is OPTIONAL in the JRD. 570 4.4.4. links 572 The "links" array has any number of member objects, each of which 573 represents a link [4]. Each of these link objects can have the 574 following members: 576 o rel 577 o type 578 o href 579 o titles 580 o properties 582 The "rel" and "href" members are strings representing the link's 583 relation type and the target IRI, respectively. The context of the 584 link is the "subject" (see Section 4.4.1). 586 The "type" member is a string indicating what the media type of the 587 result of dereferencing the link ought to be. 589 The order of elements in the "links" array indicates an order of 590 preference. Thus, if there are two or more link relations having the 591 same "rel" value, the first link relation would indicate the user's 592 preferred link. 594 The "links" array is OPTIONAL in the JRD. 596 Below, each of the members of the objects found in the "links" array 597 is described in more detail. Each object in the "links" array, 598 referred to as a "link relation object", is completely independent 599 from any other object in the array; any requirement to include a 600 given member in the link relation object refers only to that 601 particular object. 603 4.4.4.1. rel 605 The value of the "rel" member is a string that is either an absolute 606 URI or a registered relation type [10] (see RFC 5988 [4]). The value 607 of the "rel" member MUST contain exactly one URI or registered 608 relation type. The URI or registered relation type identifies the 609 type of the link relation. 611 The other members of the object have meaning only once the type of 612 link relation is understood. In some instances, the link relation 613 will have associated semantics enabling the client to query for other 614 resources on the Internet. In other instances, the link relation 615 will have associated semantics enabling the client to utilize the 616 other members of the link relation object without fetching additional 617 external resources. 619 URI link relation type values are compared using the "Simple String 620 Comparison" algorithm of section 6.2.1 of RFC 3986 [6]. 622 The "rel" member MUST be present in the link relation object. 624 4.4.4.2. type 626 The value of the "type" member is a string that indicates the media 627 type [11] of the target resource (see RFC 6838 [12]). 629 The "type" member is OPTIONAL in the link relation object. 631 4.4.4.3. href 633 The value of the "href" member is a string that contains a URI 634 pointing to the target resource. 636 The "href" member is OPTIONAL in the link relation object. 638 4.4.4.4. titles 640 The "titles" object comprises zero or more name/value pairs whose 641 name is a language tag [13] or the string "default". The string is 642 human-readable and describes the link relation. More than one title 643 for the link relation MAY be provided for the benefit of users who 644 utilize the link relation and, if used, a language identifier SHOULD 645 be duly used as the name. If the language is unknown or unspecified, 646 then the name is "default". 648 A JRD SHOULD NOT include more than one title identified with the same 649 language tag (or "default") within the link relation object. Meaning 650 is undefined if a link relation object includes more than one title 651 named with the same language tag (or "default"), though this MUST NOT 652 be treated as an error. A client MAY select whichever title or 653 titles it wishes to utilize. 655 Here is an example of the titles object: 657 "titles" : 658 { 659 "en-us" : "The Magical World of Bob", 660 "fr" : "Le Monde Magique de Bob" 661 } 663 The "titles" member is OPTIONAL in the link relation object. 665 4.4.4.5. properties 667 The "properties" object within the link relation object comprises 668 zero or more name/value pairs whose names are absolute URIs and whose 669 values are strings or null. Properties are used to convey additional 670 information about the link relation. As an example, consider this 671 use of "properties": 673 "properties" : { "http://webfinger.example/mail/port" : "993" } 675 The "properties" member is OPTIONAL in the link relation object. 677 4.5. WebFinger and URIs 679 WebFinger requests include a "resource" parameter (see Section 4.1) 680 specifying the URI of an account, device, or other entity. WebFinger 681 is neutral regarding the scheme of such a URI: it could be an "acct" 682 URI [7], an "http" or "https" URI, a "mailto" URI [21], or some other 683 scheme. 685 To perform a WebFinger lookup on an account specific to the host 686 being queried, use of the "acct" URI scheme is recommended, since it 687 explicitly identifies an account accessible via WebFinger. Further, 688 the "acct" URI scheme is not associated with other protocols as, by 689 way of example, the "mailto" URI scheme is associated with email. 690 Since not every host offers email service, using the "mailto" URI 691 scheme is not ideal for identifying user accounts on all hosts. That 692 said, use of the "mailto" URI scheme would be ideal for use with 693 WebFinger to discover mail server configuration information for a 694 user. 696 5. Cross-Origin Resource Sharing (CORS) 698 WebFinger resources might not be accessible from a web browser due to 699 "Same-Origin" policies. The current best practice is to make 700 resources available to browsers through Cross-Origin Resource Sharing 701 (CORS) [9], and servers MUST include the Access-Control-Allow-Origin 702 HTTP header in responses. Servers SHOULD support the least 703 restrictive setting by allowing any domain access to the WebFinger 704 resource: 706 Access-Control-Allow-Origin: * 708 There are cases where defaulting to the least restrictive setting is 709 not appropriate, for example a server on an intranet that provides 710 sensitive company information SHOULD NOT allow CORS requests from any 711 domain, as that could allow leaking of that sensitive information. A 712 server that wishes to restrict access to information from external 713 entities SHOULD use a more restrictive Access-Control-Allow-Origin 714 header. 716 6. Access Control 718 As with all web resources, access to the WebFinger resource could 719 require authentication. Further, failure to provide required 720 credentials might result in the server forbidding access or providing 721 a different response than had the client authenticated with the 722 server. 724 Likewise, a WebFinger resource MAY provide different responses to 725 different clients based on other factors, such as whether the client 726 is inside or outside a corporate network. As a concrete example, a 727 query performed on the internal corporate network might return link 728 relations to employee pictures, whereas link relations for employee 729 pictures might not be provided to external entities. 731 Further, link relations provided in a WebFinger resource 732 representation might point to web resources that impose access 733 restrictions. For example, the aforementioned corporate server may 734 provide both internal and external entities with URIs to employee 735 pictures, but further authentication might be required in order for 736 the client to access the picture resources if the request comes from 737 outside the corporate network. 739 The decisions made with respect to what set of link relations a 740 WebFinger resource provides to one client versus another and what 741 resources require further authentication, as well as the specific 742 authentication mechanisms employed, are outside the scope of this 743 document. 745 7. Hosted WebFinger Services 747 As with most services provided on the Internet, it is possible for a 748 domain owner to utilize "hosted" WebFinger services. By way of 749 example, a domain owner might control most aspects of their domain, 750 but use a third-party hosting service for email. In the case of 751 email, MX records identify mail servers for a domain. An MX record 752 points to the mail server to which mail for the domain should be 753 delivered. It does not matter to the sending mail server whether 754 those MX records point to a server in the destination domain or a 755 different domain. 757 Likewise, a domain owner might utilize the services of a third party 758 to provide WebFinger services on behalf of its users. Just as a 759 domain owner was required to insert MX records into DNS to allow for 760 hosted email serves, the domain owner is required to redirect HTTP 761 queries to its domain to allow for hosted WebFinger services. 763 When a query is issued to the WebFinger resource, the web server MUST 764 return a response with a redirection status code that includes a 765 Location header pointing to the location of the hosted WebFinger 766 service URI. This WebFinger service URI does not need to point to 767 the well-known WebFinger location on the hosting service provider 768 server. 770 As an example, assume that example.com's WebFinger services are 771 hosted by wf.example.net. Suppose a client issues a query for 772 acct:alice@example.com like this: 774 GET /.well-known/webfinger? 775 resource=acct%3Aalice%40example.com HTTP/1.1 776 Host: example.com 778 The server might respond with this: 780 HTTP/1.1 307 Temporary Redirect 781 Access-Control-Allow-Origin: * 782 Location: https://wf.example.net/example.com/webfinger? 783 resource=acct%3Aalice%40example.com 785 The client can then follow the redirection, re-issuing the request to 786 the URI provided in the Location header. Note that the server will 787 include any required URI parameters in the Location header value, 788 which could be different than the URI parameters the client 789 originally used. 791 8. Security Considerations 793 8.1. Transport-Related Issues 795 Since this specification utilizes Cross-Origin Resource Sharing 796 (CORS) [9], all of the security considerations applicable to CORS are 797 also applicable to this specification. 799 The use of HTTPS is REQUIRED to ensure that information is not 800 modified during transit. It should be appreciated that in 801 environments where a web server is normally available, there exists 802 the possibility that a compromised network might have its WebFinger 803 resource operating on HTTPS replaced with one operating only over 804 HTTP. As such, clients MUST NOT issue queries over a non-secure 805 connection. 807 Clients MUST verify that the certificate used on an HTTPS connection 808 is valid (as defined in [14]) and accept a response only if the 809 certificate is valid. 811 8.2. User Privacy Considerations 813 Service providers and users should be aware that placing information 814 on the Internet means that any user can access that information and 815 WebFinger can be used to make it even easier to discover that 816 information. While WebFinger can be an extremely useful tool for 817 discovering one's avatar, blog, or other personal data, users should 818 understand the risks, too. If one does not wish to share certain 819 information with the world, do not allow that information to be 820 freely accessible on the Internet or discoverable via WebFinger. 821 Further, WebFinger MUST NOT be used to provide any personal data to 822 any party unless explicitly authorized by the person whose 823 information is being shared. Publishing one's personal data within 824 an access-controlled or otherwise limited environment on the Internet 825 does not equate to providing implicit authorization of further 826 publication of that data via WebFinger. 828 The aforementioned word of caution is perhaps worth emphasizing again 829 with respect to information that might reveal a user's current 830 context (e.g., the user's location). The power of WebFinger comes 831 from providing a single place where others can find pointers to 832 information about a person, but service providers and users should be 833 mindful of the nature of that information shared and the fact that it 834 might be available for the entire world to see. Sharing location 835 information, for example, would potentially put a person in danger 836 from any individual who might seek to inflict harm on that person. 838 The easy access to user information via WebFinger was a design goal 839 of the protocol, not a limitation. If one wishes to limit access to 840 information available via WebFinger, such as WebFinger resources for 841 use inside a corporate network, the network administrator needs to 842 take necessary measures to limit access from outside the network. 843 Using standard methods for securing web resources, network 844 administrators do have the ability to control access to resources 845 that might return sensitive information. Further, a server can be 846 employed in such a way as to require authentication and prevent 847 disclosure of information to unauthorized entities. 849 8.3. Abuse Potential 851 Service providers should be mindful of the potential for abuse using 852 WebFinger. 854 As one example, one might query a WebFinger server only to discover 855 whether a given URI is valid or not. With such a query, the person 856 may deduce that an email identifier is valid, for example. Such an 857 approach could help spammers maintain a current list of known email 858 addresses and to discover new ones. 860 WebFinger could be used to associate a name or other personal data 861 with an email address, allowing spammers to craft more convincing 862 email messages. This might be of particular value in phishing 863 attempts. 865 8.4. Information Reliability 867 A WebFinger resource has no means of ensuring that information 868 provided by a user is accurate. Likewise, neither the resource nor 869 the client can be absolutely guaranteed that information has not been 870 manipulated either at the server or along the communication path 871 between the client and server. Use of HTTPS helps to address some 872 concerns with manipulation of information along the communication 873 path, but it clearly cannot address issues where the resource 874 provided incorrect information, either due to being provided false 875 information or due to malicious behavior on the part of the server 876 administrator. As with any information service available on the 877 Internet, users should be wary of information received from untrusted 878 sources. 880 9. IANA Considerations 882 9.1. Well-Known URI 884 This specification registers the "webfinger" well-known URI in the 885 Well-Known URI Registry as defined by [3]. 887 URI suffix: webfinger 889 Change controller: IETF 891 Specification document(s): RFC XXXX 893 Related information: The query to the WebFinger resource will 894 include one or more parameters in the query string; see Section 4.1 895 of RFCXXXX. Resources at this location are able to return a JSON 896 Resource Descriptor (JRD) as described in Section 4.4 of RFCXXXX. 898 [RFC EDITOR: Please replace "XXXX" references in this section and the 899 following section with the number for this RFC.] 901 9.2. JSON Resource Descriptor (JRD) Media Type 903 This specification registers the media type application/jrd+json for 904 use with WebFinger in accordance with media type registration 905 procedures defined in [12]. 907 Type name: application 909 Subtype name: jrd+json 911 Required parameters: N/A 913 Optional parameters: N/A 915 In particular, because RFC 4627 already defines the character 916 encoding for JSON, no "charset" parameter is used. 918 Encoding considerations: See RFC 6839, section 3.1. 920 Security considerations: 922 The JSON Resource Descriptor (JRD) is a JavaScript Object Notation 923 (JSON) object. It is a text format that must be parsed by entities 924 that wish to utilize the format. Depending on the language and 925 mechanism used to parse a JSON object, it is possible for an 926 attacker to inject behavior into a running program. Therefore, 927 care must be taken to properly parse a received JRD to ensure that 928 only a valid JSON object is present and that no JavaScript or other 929 code is injected or executed unexpectedly. 931 Interoperability considerations: 933 This media type is a JavaScript Object Notation (JSON) object and 934 can be consumed by any software application that can consume JSON 935 objects. 937 Published specification: RFC XXXX 939 Applications that use this media type: 941 The JSON Resource Descriptor (JRD) is used by the WebFinger 942 protocol (RFC XXXX) to enable the exchange of information between a 943 client and a WebFinger resource over HTTPS. 945 Fragment identifier considerations: 947 The syntax and semantics of fragment identifiers SHOULD be as 948 specified for "application/json". (At publication of this 949 document, there is no fragment identification syntax defined for 950 "application/json".) 952 Additional information: 954 Deprecated alias names for this type: N/A 956 Magic number(s): N/A 958 File extension(s): jrd 960 Macintosh file type code(s): N/A 962 Person & email address to contact for further information: 964 Paul E. Jones 966 Intended usage: COMMON 968 Restrictions on usage: N/A 970 Author: Paul E. Jones 971 Change controller: 973 IESG has change control over this registration. 975 Provisional registration? (standards tree only): N/A 977 10. Acknowledgments 979 This document has benefited from extensive discussion and review of 980 many of the members of the APPSAWG working group. The authors would 981 like to especially acknowledge the invaluable input of Eran Hammer- 982 Lahav, Blaine Cook, Brad Fitzpatrick, Laurent-Walter Goix, Joe 983 Clarke, Michael B. Jones, Peter Saint-Andre, Dick Hardt, Tim Bray, 984 James Snell, Melvin Carvalho, Evan Prodromou, Mark Nottingham, Barry 985 Leiba, Elf Pavlik, Bjoern Hoehrmann, SM, Joe Gregorio and others that 986 we have undoubtedly, but inadvertently, missed. Special thanks go to 987 the chairs of APPSAWG, especially Salvatore Loreto for his assistance 988 in shepherding this document. 990 11. References 992 11.1. Normative References 994 [1] Bradner, S., "Key words for use in RFCs to Indicate Requirement 995 Levels", BCP 14, RFC 2119, March 1997. 997 [2] Fielding, R., Gettys, J., Mogul, J., Frystyk, H., Masinter, L., 998 Leach, P., and T. Berners-Lee, "Hypertext Transfer Protocol -- 999 HTTP/1.1", RFC 2616, June 1999. 1001 [3] Nottingham, M., Hammer-Lahav, E., "Defining Well-Known Uniform 1002 Resource Identifiers (URIs)", RFC 5785, April 2010. 1004 [4] Nottingham, M., "Web Linking", RFC 5988, October 2010. 1006 [5] Crockford, D., "The application/json Media Type for JavaScript 1007 Object Notation (JSON)", RFC 4627, July 2006. 1009 [6] Berners-Lee, T., Fielding, R., and Masinter, L., "Uniform 1010 Resource Identifier (URI): Generic Syntax", STD 66, RFC 3986, 1011 January 2005. 1013 [7] Duerst, M., "Internationalized Resource Identifiers (IRIs)", 1014 RFC 3987, January 2005. 1016 [8] Saint-Andre, P., "The 'acct' URI Scheme", draft-ietf-appsawg- 1017 acct-uri-03, February 2013. 1019 [9] Van Kesteren, A., "Cross-Origin Resource Sharing", W3C CORS 1020 http://www.w3.org/TR/cors/, July 2010. 1022 [10] IANA, "Link Relations", http://www.iana.org/assignments/link- 1023 relations/. 1025 [11] IANA, "MIME Media Types", 1026 http://www.iana.org/assignments/media-types/index.html. 1028 [12] Freed, N., Klensin, J., Hansen, T., "Media Type Specifications 1029 and Registration Procedures", RFC 6838, January 2013. 1031 [13] Phillips, A., Davis, M., "Tags for Identifying Languages", RFC 1032 5646, January 2009. 1034 [14] Rescorla, E., "HTTP Over TLS", RFC 2818, May 2000. 1036 [15] Klyne, G., Newman, C., "Date and Time on the Internet: 1037 Timestamps", RFC 3339, July 2002. 1039 11.2. Informative References 1041 [16] Perreault, S., "vCard Format Specification", RFC 6350, August 1042 2011. 1044 [17] "Transport Independent, Printer/System Interface", IEEE Std 1045 1284.1-1997, 1997. 1047 [18] Sakimura, N., Bradley, J., Jones, M., de Medeiros, B., 1048 Mortimore, C., and E. Jay, "OpenID Connect Messages 1.0", 1049 January 2013, http://openid.net/specs/openid-connect-messages- 1050 1_0.html. 1052 [19] Hammer-Lahav, E. and Cook, B., "Web Host Metadata", RFC 6415, 1053 October 2011. 1055 [20] Hammer-Lahav, E. and W. Norris, "Extensible Resource Descriptor 1056 (XRD) Version 1.0", http://docs.oasis- 1057 open.org/xri/xrd/v1.0/xrd-1.0.html. 1059 [21] Duerst, M., Masinter, L., and J. Zawinski, "The 'mailto' URI 1060 Scheme", RFC 6068, October 2010. 1062 Author's Addresses 1064 Paul E. Jones 1065 Cisco Systems, Inc. 1066 7025 Kit Creek Rd. 1067 Research Triangle Park, NC 27709 1068 USA 1070 Phone: +1 919 476 2048 1071 Email: paulej@packetizer.com 1072 IM: xmpp:paulej@packetizer.com 1074 Gonzalo Salgueiro 1075 Cisco Systems, Inc. 1076 7025 Kit Creek Rd. 1077 Research Triangle Park, NC 27709 1078 USA 1080 Phone: +1 919 392 3266 1081 Email: gsalguei@cisco.com 1082 IM: xmpp:gsalguei@cisco.com 1084 Joseph Smarr 1085 Google 1087 Email: jsmarr@google.com