idnits 2.17.1 draft-ietf-appsawg-webfinger-14.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 (May 26, 2013) is 3981 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 1120, 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: November 26, 2013 Joseph Smarr 6 Google 7 May 26, 2013 9 WebFinger 10 draft-ietf-appsawg-webfinger-14.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 November 26, 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 the Query Component of the 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.......................................14 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..................................19 79 9. IANA Considerations...........................................19 80 9.1. Well-Known URI...........................................19 81 9.2. JSON Resource Descriptor (JRD) Media Type................20 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 that a printer can print in color on A4 paper, the physical location 104 of a server, or other static information. 106 Information returned via WebFinger might be for direct human 107 consumption (e.g., looking up someone's phone number), or it might be 108 used by systems to help carry out some operation (e.g., facilitate 109 logging into a web site by determining a user's identity service). 110 The information is intended to be static in nature and, as such, 111 WebFinger is not intended to be used to return dynamic information 112 like the temperature of a CPU or the current toner level in a laser 113 printer. 115 The WebFinger protocol is designed to be used across many 116 applications. Applications that wish to utilize WebFinger will need 117 to specify properties, titles, and link relation types that are 118 appropriate for the application. Further, applications will need to 119 define the appropriate URI scheme to utilize for the query target. 121 Use of WebFinger is illustrated in the examples in Section 3 and 122 described more formally in Section 4. 124 2. Terminology 126 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 127 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 128 document are to be interpreted as described in RFC 2119 [1]. 130 WebFinger makes heavy use of "Link Relations". A Link Relation is an 131 attribute-and-value pair in which the attribute identifies the type 132 of relationship between the linked entity or resource and the 133 information specified in the value. In Web Linking [4], the link 134 relation is represented using an HTTP entity-header of "Link", where 135 the "rel" attribute specifies the type of relationship and the "href" 136 attribute specifies the information that is linked to the entity or 137 resource. In WebFinger, the same concept is represented using a JSON 138 array of "links" objects, where each member named "rel" specifies the 139 type of relationship and each member named "href" specifies the 140 information that is linked to the entity or resource. Note that 141 WebFinger narrows the scope of a link relation beyond what is defined 142 for Web Linking by stipulating that the value of the "rel" member 143 needs to be either a single IANA-registered link relation type [10] 144 or a URI [6]. 146 3. Example Uses of WebFinger 148 This non-normative section shows a few sample uses of WebFinger. 150 3.1. Locating a User's Blog 152 Assume you receive an email from Bob and he refers to something he 153 posted on his blog, but you do not know where Bob's blog is located. 155 It would be simple to discover the address of Bob's blog if he made 156 that information available via WebFinger. 158 Assume your email client can discover the blog for you. After 159 receiving the message from Bob (bob@example.com), your email client 160 performs a WebFinger query either automatically or at your command. 161 (Please refer to Section 8.2 for user privacy considerations and 162 Section 8.3 for abuse considerations, particularly when considering 163 any kind of automated query feature.) It does so by issuing the 164 following HTTPS [14] query to example.com: 166 GET /.well-known/webfinger? 167 resource=acct%3Abob%40example.com HTTP/1.1 168 Host: example.com 170 The server might then respond with a message like this: 172 HTTP/1.1 200 OK 173 Access-Control-Allow-Origin: * 174 Content-Type: application/jrd+json 176 { 177 "subject" : "acct:bob@example.com", 178 "aliases" : 179 [ 180 "http://www.example.com/~bob/" 181 ], 182 "properties" : 183 { 184 "http://example.com/ns/role/" : "employee" 185 }, 186 "links" : 187 [ 188 { 189 "rel" : "http://webfinger.example/rel/avatar", 190 "type" : "image/jpeg", 191 "href" : "http://www.example.com/~bob/bob.jpg" 192 }, 193 { 194 "rel" : "http://webfinger.example/rel/profile-page", 195 "href" : "http://www.example.com/~bob/" 196 }, 197 { 198 "rel" : "http://webfinger.example/rel/blog", 199 "type" : "text/html", 200 "href" : "http://blogs.example.com/bob/", 201 "titles" : 202 { 203 "en-us" : "The Magical World of Bob", 204 "fr" : "Le Monde Magique de Bob" 205 } 206 }, 207 { 208 "rel" : "http://webfinger.example/rel/businesscard", 209 "href" : "https://www.example.com/~bob/bob.vcf" 210 } 211 ] 212 } 214 Note the assumption made in the above example is that there is an 215 "acct" URI for the given "mailto" URI. This may not always be the 216 case. 218 The email client would take note of the link relation in the above 219 JRD that refers to Bob's blog. The blog's URI would then be 220 presented to you so that you could then visit his blog. The email 221 client might also note that Bob has published an avatar link relation 222 and use that picture to represent Bob inside the email client. 223 Lastly, the client might automatically retrieve the data located at 224 the URI specified by the "businesscard" link relation (which might be 225 a vcard [16]) to update the information about Bob in its internal 226 address book. 228 In the above example, an "acct" URI [8] is used in the query, though 229 any valid alias for the user might also be used. See Section 4.5 for 230 more information on WebFinger and URIs. 232 An alias is a URI that is different from the "subject" URI, yet 233 identifies the same entity. In the above example, there is one 234 "http" alias returned, though there might have been more than one. 235 Had the "http:" URI shown as an alias been used to query for 236 information about Bob, the query would have appeared as: 238 GET /.well-known/webfinger? 239 resource=http%3A%2F%2Fwww.example.com%2F~bob%2F HTTP/1.1 240 Host: www.example.com 242 Note that the host queried in this example is different than for the 243 acct URI example, since the URI refers to a different host. Either 244 this host would provide a response, or it would redirect the client 245 to another host (e.g., redirect back to example.com). Either way, 246 the response would have been substantially the same, with the subject 247 and alias information changed as necessary. 249 3.2. Identity Provider Discovery for OpenID Connect 251 Suppose Carol wishes to authenticate with a web site she visits using 252 OpenID Connect [18]. She would provide the web site with her OpenID 253 Connect identifier, say carol@example.com. The visited web site 254 would perform a WebFinger query looking for the OpenID Connect 255 Provider. Since the site is interested in only one particular link 256 relation, the WebFinger resource might utilize the "rel" parameter as 257 described in Section 4.3: 259 GET /.well-known/webfinger? 260 resource=acct%3Acarol%40example.com& 261 rel=http%3A%2F%2Fopenid.net%2Fspecs%2Fconnect%2F1.0%2Fissuer 262 HTTP/1.1 263 Host: example.com 265 The server might respond like this: 267 HTTP/1.1 200 OK 268 Access-Control-Allow-Origin: * 269 Content-Type: application/jrd+json 271 { 272 "subject" : "acct:carol@example.com", 273 "links" : 274 [ 275 { 276 "rel" : "http://openid.net/specs/connect/1.0/issuer", 277 "href" : "https://openid.example.com" 278 } 279 ] 280 } 282 Since the "rel" parameter only serves to filter the link relations 283 returned by the resource, other name/value pairs in the response, 284 including any aliases or properties, would be returned. Also, since 285 support for the "rel" parameter is not guaranteed, the client must 286 not assume the "links" array will contain only the requested link 287 relation. 289 3.3. Auto-Configuration of Email Clients 291 WebFinger could be used to auto-provision an email client with basic 292 configuration data. Suppose that sue@example.com wants to configure 293 her email client. Her email client might issue the following query: 295 GET /.well-known/webfinger? 296 resource=mailto%3Asue%40example.com HTTP/1.1 297 Host: example.com 299 The returned resource representation would contain entries for the 300 various protocols, transport options, and security options. If there 301 are multiple options, the resource representation might include a 302 link relation for each of the valid options, and the client or Sue 303 might select which option to choose. Since JRDs list link relations 304 in a specific order, then the most-preferred choices could be 305 presented first. Consider this response: 307 HTTP/1.1 200 OK 308 Access-Control-Allow-Origin: * 309 Content-Type: application/jrd+json 310 { 311 "subject" : "mailto:sue@example.com", 312 "links" : 313 [ 314 { 315 "rel" : "http://webfinger.example/rel/smtp-server", 316 "properties" : 317 { 318 "http://webfinger.example/email/host" : "smtp.example.com", 319 "http://webfinger.example/email/port" : "587", 320 "http://webfinger.example/email/login-required" : "yes", 321 "http://webfinger.example/email/transport" : "starttls" 322 } 323 }, 324 { 325 "rel" : "http://webfinger.example/rel/imap-server", 326 "properties" : 327 { 328 "http://webfinger.example/email/host" : "imap.example.com", 329 "http://webfinger.example/email/port" : "993", 330 "http://webfinger.example/email/transport" : "ssl" 331 } 332 } 333 ] 334 } 336 In this example, you can see that the WebFinger resource 337 representation advertises an SMTP service and an IMAP service. In 338 this example, the "href" entries associated with the link relation 339 are absent. This is valid when there is no additional reference that 340 needs to be made. 342 3.4. Retrieving Device Information 344 As another example, suppose there are printers on the network and you 345 would like to check a particular printer identified by the URI 346 device:p1.example.com to see if it can print in color on A4 paper. 347 While the "device" URI scheme is not presently specified, we use it 348 here for illustrative purposes. 350 Following the procedures similar to those above, a query may be 351 issued to get link relations specific to this URI like this: 353 GET /.well-known/webfinger? 354 resource=device%3Ap1.example.com HTTP/1.1 355 Host: p1.example.com 357 The link relations that are returned for a device may be quite 358 different than those for user accounts. Perhaps we may see a 359 response like this: 361 HTTP/1.1 200 OK 362 Access-Control-Allow-Origin: * 363 Content-Type: application/jrd+json 365 { 366 "subject" : "device:p1.example.com", 367 "links" : 368 [ 369 { 370 "rel" : "http://webfinger.example/rel/tipsi", 371 "href" : "http://192.168.1.5/npap/" 372 } 373 ] 374 } 376 While this example is fictitious, you can imagine that perhaps the 377 Transport Independent, Printer/System Interface [17] may be enhanced 378 with a web interface enabling a device that understands the TIP/SI 379 web interface specification to query for printer capabilities. 381 4. WebFinger Protocol 383 The WebFinger protocol is used to request information about an entity 384 identified by a query target (a URI). The client can optionally 385 specify one or more link relation types for which it would like to 386 receive information. 388 A WebFinger request is an HTTPS request to a WebFinger resource. A 389 WebFinger resource is a well-known URI [3] using the HTTPS scheme, 390 constructed along with the required query target and optional link 391 relation types. WebFinger resources MUST NOT be served with any 392 other URI scheme (such as HTTP). 394 A WebFinger resource is always given a query target, which is another 395 URI that identifies the entity whose information is sought. GET 396 requests to a WebFinger resource convey the query target in the 397 "resource" parameter in the WebFinger URI's query string; see Section 398 4.1 for details. 400 The host to which a WebFinger query is issued is significant. If the 401 query target contains a "host" portion (Section 3.2.2 of RFC 3986), 402 then the host to which the WebFinger query is issued MUST be the same 403 as the "host" portion of the query target, unless the client receives 404 instructions through some out-of-band mechanism to send the query to 405 another host. If the query target does not contain a "host" portion, 406 then the client MAY choose a host to which it directs the query using 407 additional information it has. 409 The path component of a WebFinger URI MUST be the well-known path 410 "/.well-known/webfinger". A WebFinger URI MUST contain a query 411 component that encodes the query target and optional link relation 412 types as specified in Section 4.1. 414 The WebFinger resource returns a JSON Resource Descriptor (JRD) as 415 the resource representation to convey information about an entity on 416 the Internet. Also, the Cross-Origin Resource Sharing (CORS) [9] 417 specification is utilized to facilitate queries made via a web 418 browser. 420 4.1. Constructing the Query Component of the Request URI 422 A WebFinger URI MUST contain a query component (see Section 3.4 of 423 RFC 3986). The query component MUST contain a "resource" parameter 424 and MAY contain one or more "rel" parameters. The "resource" 425 parameter MUST contain the query target (URI) and the "rel" 426 parameters MUST contain encoded link relation types according to the 427 encoding described in this section. 429 To construct the query component, the client performs the following 430 steps. First, each parameter value is percent-encoded, as per 431 Section 2.1 of RFC 3986. The encoding is done to conform to the 432 query production in Section 3.4 of that specification, with the 433 addition that any instances of the "=" and "&" characters within the 434 parameter values are also percent-encoded. Next, the client 435 constructs a string to be placed in the query component by 436 concatenating the name of the first parameter together with an equal 437 sign ("=") and the percent-encoded parameter value. For any 438 subsequent parameters, the client appends an ampersand ("&") to the 439 string, the name of the next parameter, an equal sign, and the 440 parameter value. The client MUST NOT insert any spaces while 441 constructing the string. The order in which the client places each 442 attribute-and-value pair within the query component does not matter 443 in the interpretation of the query component. 445 4.2. Performing a WebFinger Query 447 A WebFinger client issues a query using the GET method to the well- 448 known [3] resource identified by the URI whose path component is 449 "/.well-known/webfinger" and whose query component MUST include the 450 "resource" parameter exactly once and set to the value of the URI for 451 which information is being sought. If the "resource" parameter is 452 absent or malformed, the WebFinger resource MUST indicate that the 453 request is bad as per Section 10.4.1 of RFC 2616 [2]. 455 A client MUST query the WebFinger resource using HTTPS only. If the 456 client determines that the resource has an invalid certificate, the 457 resource returns a 4xx or 5xx status code, or the HTTPS connection 458 cannot be established for any reason, then the client MUST accept 459 that the WebFinger query has failed and MUST NOT attempt to reissue 460 the WebFinger request using HTTP over a non-secure connection. 462 A WebFinger resource MUST return a JRD as the representation for the 463 resource if the client requests no other supported format explicitly 464 via the HTTP "Accept" header. The client MAY include the "Accept" 465 header to indicate a desired representation; representations other 466 than JRD might be defined in future specifications. The WebFinger 467 resource MUST silently ignore any requested representations that it 468 does not understand and support. The media type used for the JSON 469 Resource Descriptor (JRD) is "application/jrd+json" (see Section 470 9.2). 472 A WebFinger resource MAY redirect the client; if it does, the 473 redirection MUST only be to an "https" URI and the client MUST 474 perform certificate validation again when redirected. 476 A WebFinger resource can include cache validators in a response to 477 enable conditional requests by the client and/or expiration times as 478 per Section 13 of RFC 2616. 480 4.3. The "rel" Parameter 482 When issuing a request to a WebFinger resource, the client MAY 483 utilize the "rel" parameter to request only a subset of the 484 information that would otherwise be returned without the "rel" 485 parameter. When the "rel" parameter is used and accepted, only the 486 link relation types that match the link relation types provided via 487 the "rel" parameter are included in the array of links returned in 488 the JRD. If there are no matching link relation types defined for 489 the resource, the "links" array in the JRD will either be absent or 490 empty. All other information present in a resource descriptor 491 remains present, even when "rel" is employed. 493 The "rel" parameter MAY be included multiple times in order to 494 request multiple link relation types. 496 The purpose of the "rel" parameter is to return a subset of "link 497 relation objects" (see Section 4.4.4) that would otherwise be 498 returned in the resource descriptor. Use of the parameter might 499 reduce processing requirements on either the client or server, and it 500 might also reduce the bandwidth required to convey the partial 501 resource descriptor, especially if there are numerous link relation 502 values to convey for a given "resource" value. 504 WebFinger resources SHOULD support the "rel" parameter. If the 505 resource does not support the "rel" parameter, it MUST ignore the 506 parameter and process the request as if no "rel" parameter values 507 were present. 509 The following example presents the same example as found in Section 510 3.1, but uses the "rel" parameter to select two link relations: 512 GET /.well-known/webfinger? 513 resource=acct%3Abob%40example.com& 514 rel=http%3A%2F%2Fwebfinger.example%2Frel%2Fprofile-page& 515 rel=http://webfinger.example/rel/businesscard HTTP/1.1 516 Host: example.com 518 In this example, the client requests the link relations of type 519 "http://webfinger.example/rel/profile-page" and 520 "http://webfinger.example/rel/businesscard". The server then 521 responds with a message like this: 523 HTTP/1.1 200 OK 524 Access-Control-Allow-Origin: * 525 Content-Type: application/jrd+json 527 { 528 "subject" : "acct:bob@example.com", 529 "aliases" : 530 [ 531 "http://www.example.com/~bob/" 532 ], 533 "properties" : 534 { 535 "http://example.com/ns/role/" : "employee" 536 }, 537 "links" : 538 [ 539 { 540 "rel" : "http://webfinger.example/rel/profile-page", 541 "href" : "http://www.example.com/~bob/" 542 }, 543 { 544 "rel" : "http://webfinger.example/rel/businesscard", 545 "href" : "http://www.example.com/~bob/bob.vcf" 546 } 547 ] 548 } 550 As you can see in the response, the resource representation contains 551 only the link relations requested by the client, but the other parts 552 of the JRD are still present. 554 4.4. The JSON Resource Descriptor (JRD) 556 The JSON Resource Descriptor (JRD), originally introduced in RFC 6415 557 [19] and based on the Extensible Resource Descriptor (XRD) format 558 [20], is a JSON object that comprises the following name/value pairs: 560 o subject 561 o aliases 562 o properties 563 o links 565 The member "subject" is a name/value pair whose value is a string, 566 "aliases" is an array of strings, "properties" is an object 567 comprising name/value pairs whose values are strings, and "links" is 568 an array of objects that contain link relation information. 570 When processing a JRD, the client MUST ignore any unknown member and 571 not treat the presence of an unknown member as an error. 573 Below, each of these members of the JRD is described in more detail. 575 4.4.1. subject 577 The value of the "subject" member is a URI that identifies the entity 578 that the JRD describes. 580 The "subject" value returned by a WebFinger resource MAY differ from 581 the value of the "resource" parameter used in the client's request. 582 This might happen, for example, when the subject's identity changes 583 (e.g., a user moves his or her account to another service) or when 584 the resource prefers to express URIs in canonical form. 586 The "subject" member SHOULD be present in the JRD. 588 4.4.2. aliases 590 The "aliases" array is an array of zero or more URI strings that 591 identify the same entity as the "subject" URI. Each URI must be an 592 absolute URI. 594 The "aliases" array is OPTIONAL in the JRD. 596 4.4.3. properties 598 The "properties" object comprises zero or more name/value pairs whose 599 names are absolute URIs and whose values are strings or null. 600 Properties are used to convey additional information about the 601 subject of the JRD. As an example, consider this use of 602 "properties": 604 "properties" : { "http://webfinger.example/ns/name" : "Bob Smith" } 606 The "properties" member is OPTIONAL in the JRD. 608 4.4.4. links 610 The "links" array has any number of member objects, each of which 611 represents a link [4]. Each of these link objects can have the 612 following members: 614 o rel 615 o type 616 o href 617 o titles 618 o properties 620 The "rel" and "href" members are strings representing the link's 621 relation type and the target IRI, respectively. The context of the 622 link is the "subject" (see Section 4.4.1). 624 The "type" member is a string indicating what the media type of the 625 result of dereferencing the link ought to be. 627 The order of elements in the "links" array indicates an order of 628 preference. Thus, if there are two or more link relations having the 629 same "rel" value, the first link relation would indicate the user's 630 preferred link. 632 The "links" array is OPTIONAL in the JRD. 634 Below, each of the members of the objects found in the "links" array 635 is described in more detail. Each object in the "links" array, 636 referred to as a "link relation object", is completely independent 637 from any other object in the array; any requirement to include a 638 given member in the link relation object refers only to that 639 particular object. 641 4.4.4.1. rel 643 The value of the "rel" member is a string that is either an absolute 644 URI or a registered relation type [10] (see RFC 5988 [4]). The value 645 of the "rel" member MUST contain exactly one URI or registered 646 relation type. The URI or registered relation type identifies the 647 type of the link relation. 649 The other members of the object have meaning only once the type of 650 link relation is understood. In some instances, the link relation 651 will have associated semantics enabling the client to query for other 652 resources on the Internet. In other instances, the link relation 653 will have associated semantics enabling the client to utilize the 654 other members of the link relation object without fetching additional 655 external resources. 657 URI link relation type values are compared using the "Simple String 658 Comparison" algorithm of section 6.2.1 of RFC 3986 [6]. 660 The "rel" member MUST be present in the link relation object. 662 4.4.4.2. type 664 The value of the "type" member is a string that indicates the media 665 type [11] of the target resource (see RFC 6838 [12]). 667 The "type" member is OPTIONAL in the link relation object. 669 4.4.4.3. href 671 The value of the "href" member is a string that contains a URI 672 pointing to the target resource. 674 The "href" member is OPTIONAL in the link relation object. 676 4.4.4.4. titles 678 The "titles" object comprises zero or more name/value pairs whose 679 name is a language tag [13] or the string "und". The string is 680 human-readable and describes the link relation. More than one title 681 for the link relation MAY be provided for the benefit of users who 682 utilize the link relation and, if used, a language identifier SHOULD 683 be duly used as the name. If the language is unknown or unspecified, 684 then the name is "und". 686 A JRD SHOULD NOT include more than one title identified with the same 687 language tag (or "und") within the link relation object. Meaning is 688 undefined if a link relation object includes more than one title 689 named with the same language tag (or "und"), though this MUST NOT be 690 treated as an error. A client MAY select whichever title or titles 691 it wishes to utilize. 693 Here is an example of the titles object: 695 "titles" : 696 { 697 "en-us" : "The Magical World of Bob", 698 "fr" : "Le Monde Magique de Bob" 699 } 701 The "titles" member is OPTIONAL in the link relation object. 703 4.4.4.5. properties 705 The "properties" object within the link relation object comprises 706 zero or more name/value pairs whose names are absolute URIs and whose 707 values are strings or null. Properties are used to convey additional 708 information about the link relation. As an example, consider this 709 use of "properties": 711 "properties" : { "http://webfinger.example/mail/port" : "993" } 713 The "properties" member is OPTIONAL in the link relation object. 715 4.5. WebFinger and URIs 717 WebFinger requests include a "resource" parameter (see Section 4.1) 718 specifying the URI of an account, device, or other entity. WebFinger 719 is neutral regarding the scheme of such a URI: it could be an "acct" 720 URI [7], an "http" or "https" URI, a "mailto" URI [21], or some other 721 scheme. 723 To perform a WebFinger lookup on an account specific to the host 724 being queried, use of the "acct" URI scheme is recommended, since it 725 explicitly identifies a generic user account that is not necessarily 726 bound to a specific protocol. Further, the "acct" URI scheme is not 727 associated with other protocols as, by way of example, the "mailto" 728 URI scheme is associated with email. Since not every host offers 729 email service, using the "mailto" URI scheme is not ideal for 730 identifying user accounts on all hosts. That said, use of the 731 "mailto" URI scheme would be ideal for use with WebFinger to discover 732 mail server configuration information for a user. 734 5. Cross-Origin Resource Sharing (CORS) 736 WebFinger resources might not be accessible from a web browser due to 737 "Same-Origin" policies. The current best practice is to make 738 resources available to browsers through Cross-Origin Resource Sharing 739 (CORS) [9], and servers MUST include the Access-Control-Allow-Origin 740 HTTP header in responses. Servers SHOULD support the least 741 restrictive setting by allowing any domain access to the WebFinger 742 resource: 744 Access-Control-Allow-Origin: * 746 There are cases where defaulting to the least restrictive setting is 747 not appropriate, for example a server on an intranet that provides 748 sensitive company information SHOULD NOT allow CORS requests from any 749 domain, as that could allow leaking of that sensitive information. A 750 server that wishes to restrict access to information from external 751 entities SHOULD use a more restrictive Access-Control-Allow-Origin 752 header. 754 6. Access Control 756 As with all web resources, access to the WebFinger resource could 757 require authentication. Further, failure to provide required 758 credentials might result in the server forbidding access or providing 759 a different response than had the client authenticated with the 760 server. 762 Likewise, a WebFinger resource MAY provide different responses to 763 different clients based on other factors, such as whether the client 764 is inside or outside a corporate network. As a concrete example, a 765 query performed on the internal corporate network might return link 766 relations to employee pictures, whereas link relations for employee 767 pictures might not be provided to external entities. 769 Further, link relations provided in a WebFinger resource 770 representation might point to web resources that impose access 771 restrictions. For example, the aforementioned corporate server may 772 provide both internal and external entities with URIs to employee 773 pictures, but further authentication might be required in order for 774 the client to access the picture resources if the request comes from 775 outside the corporate network. 777 The decisions made with respect to what set of link relations a 778 WebFinger resource provides to one client versus another and what 779 resources require further authentication, as well as the specific 780 authentication mechanisms employed, are outside the scope of this 781 document. 783 7. Hosted WebFinger Services 785 As with most services provided on the Internet, it is possible for a 786 domain owner to utilize "hosted" WebFinger services. By way of 787 example, a domain owner might control most aspects of their domain, 788 but use a third-party hosting service for email. In the case of 789 email, MX records identify mail servers for a domain. An MX record 790 points to the mail server to which mail for the domain should be 791 delivered. It does not matter to the sending mail server whether 792 those MX records point to a server in the destination domain or a 793 different domain. 795 Likewise, a domain owner might utilize the services of a third party 796 to provide WebFinger services on behalf of its users. Just as a 797 domain owner was required to insert MX records into DNS to allow for 798 hosted email serves, the domain owner is required to redirect HTTP 799 queries to its domain to allow for hosted WebFinger services. 801 When a query is issued to the WebFinger resource, the web server MUST 802 return a response with a redirection status code that includes a 803 Location header pointing to the location of the hosted WebFinger 804 service URI. This WebFinger service URI does not need to point to 805 the well-known WebFinger location on the hosting service provider 806 server. 808 As an example, assume that example.com's WebFinger services are 809 hosted by wf.example.net. Suppose a client issues a query for 810 acct:alice@example.com like this: 812 GET /.well-known/webfinger? 813 resource=acct%3Aalice%40example.com HTTP/1.1 814 Host: example.com 816 The server might respond with this: 818 HTTP/1.1 307 Temporary Redirect 819 Access-Control-Allow-Origin: * 820 Location: https://wf.example.net/example.com/webfinger? 821 resource=acct%3Aalice%40example.com 823 The client can then follow the redirection, re-issuing the request to 824 the URI provided in the Location header. Note that the server will 825 include any required URI parameters in the Location header value, 826 which could be different than the URI parameters the client 827 originally used. 829 8. Security Considerations 831 8.1. Transport-Related Issues 833 Since this specification utilizes Cross-Origin Resource Sharing 834 (CORS) [9], all of the security considerations applicable to CORS are 835 also applicable to this specification. 837 The use of HTTPS is REQUIRED to ensure that information is not 838 modified during transit. It should be appreciated that in 839 environments where a web server is normally available, there exists 840 the possibility that a compromised network might have its WebFinger 841 resource operating on HTTPS replaced with one operating only over 842 HTTP. As such, clients MUST NOT issue queries over a non-secure 843 connection. 845 Clients MUST verify that the certificate used on an HTTPS connection 846 is valid (as defined in [14]) and accept a response only if the 847 certificate is valid. 849 8.2. User Privacy Considerations 851 Service providers and users should be aware that placing information 852 on the Internet means that any user can access that information and 853 WebFinger can be used to make it even easier to discover that 854 information. While WebFinger can be an extremely useful tool for 855 discovering one's avatar, blog, or other personal data, users should 856 understand the risks, too. 858 Systems or services that expose personal data via WebFinger MUST 859 provide an interface by which users can select which data elements 860 are exposed through the WebFinger interface. For example, social 861 networking sites might allow users to mark certain data as "public" 862 and then utilize that marking as a means of determining what 863 information to expose via WebFinger. The information published via 864 WebFinger would thus comprise only the information marked as public 865 by the user. Further, the user has the ability to remove information 866 from publication via WebFinger by removing this marking. 868 WebFinger MUST NOT be used to provide any personal data unless 869 publishing that data via WebFinger by the relevant service was 870 explicitly authorized by the person whose information is being 871 shared. Publishing one's personal data within an access-controlled 872 or otherwise limited environment on the Internet does not equate to 873 providing implicit authorization of further publication of that data 874 via WebFinger. 876 The privacy and security concerns with publishing personal data via 877 WebFinger are worth emphasizing again with respect to personal data 878 that might reveal a user's current context (e.g., the user's 879 location). The power of WebFinger comes from providing a single 880 place where others can find pointers to information about a person, 881 but service providers and users should be mindful of the nature of 882 that information shared and the fact that it might be available for 883 the entire world to see. Sharing location information, for example, 884 would potentially put a person in danger from any individual who 885 might seek to inflict harm on that person. 887 Users should be aware of how easily personal data one might publish 888 can be used in unintended ways. In one study relevant to WebFinger- 889 like services, Balduzzi et al. [22] took a large set of leaked email 890 addresses and demonstrated a number of potential privacy concerns, 891 including the ability to cross-correlate the same user's accounts 892 over multiple social networks. The authors also describe potential 893 mitigation strategies. 895 The easy access to user information via WebFinger was a design goal 896 of the protocol, not a limitation. If one wishes to limit access to 897 information available via WebFinger, such as WebFinger resources for 898 use inside a corporate network, the network administrator needs to 899 take necessary measures to limit access from outside the network. 900 Using standard methods for securing web resources, network 901 administrators do have the ability to control access to resources 902 that might return sensitive information. Further, a server can be 903 employed in such a way as to require authentication and prevent 904 disclosure of information to unauthorized entities. 906 8.3. Abuse Potential 908 Service providers should be mindful of the potential for abuse using 909 WebFinger. 911 As one example, one might query a WebFinger server only to discover 912 whether a given URI is valid or not. With such a query, the person 913 may deduce that an email identifier is valid, for example. Such an 914 approach could help spammers maintain a current list of known email 915 addresses and to discover new ones. 917 WebFinger could be used to associate a name or other personal data 918 with an email address, allowing spammers to craft more convincing 919 email messages. This might be of particular value in phishing 920 attempts. 922 It is RECOMMENDED that implementers of WebFinger server software take 923 steps to mitigate abuse, including malicious over-use of the server 924 and harvesting of user information. Although there is no mechanism 925 that can guarantee that publicly-accessible WebFinger databases won't 926 be harvested, rate-limiting by IP address will prevent or at least 927 dramatically slow harvest by private individuals without access to 928 botnets or other distributed systems. The reason these mitigation 929 strategies are not mandatory is that the correct choice of mitigation 930 strategy (if any) depends greatly on the context. Implementers 931 should not construe this as meaning that they do not need to consider 932 whether to use a mitigation strategy, and, if so, what strategy to 933 use. 935 WebFinger client developers should also be aware of potential abuse 936 by spammers or those phishing for information about users. As an 937 example, suppose a mail client was configured to automatically 938 perform a WebFinger query as discussed in the example in Section 3.1. 939 If a spammer sent an email using a unique identifier in the 'From' 940 header, then when the WF query was performed the spammer would be 941 able to associate the request with a particular user's email address. 942 This would provide information to the spammer, including the user's 943 IP address, the fact the user just checked email, what kind of 944 WebFinger client the user utilized, and so on. For this reason, it 945 is strongly advised that clients not perform WebFinger queries unless 946 authorized by the user to do so. 948 8.4. Information Reliability 950 A WebFinger resource has no means of ensuring that information 951 provided by a user is accurate. Likewise, neither the resource nor 952 the client can be absolutely guaranteed that information has not been 953 manipulated either at the server or along the communication path 954 between the client and server. Use of HTTPS helps to address some 955 concerns with manipulation of information along the communication 956 path, but it clearly cannot address issues where the resource 957 provided incorrect information, either due to being provided false 958 information or due to malicious behavior on the part of the server 959 administrator. As with any information service available on the 960 Internet, users should be wary of information received from untrusted 961 sources. 963 9. IANA Considerations 965 9.1. Well-Known URI 967 This specification registers the "webfinger" well-known URI in the 968 Well-Known URI Registry as defined by [3]. 970 URI suffix: webfinger 972 Change controller: IETF 974 Specification document(s): RFC XXXX 976 Related information: The query to the WebFinger resource will 977 include one or more parameters in the query string; see Section 4.1 978 of RFCXXXX. Resources at this location are able to return a JSON 979 Resource Descriptor (JRD) as described in Section 4.4 of RFCXXXX. 981 [RFC EDITOR: Please replace "XXXX" references in this section and the 982 following section with the number for this RFC.] 984 9.2. JSON Resource Descriptor (JRD) Media Type 986 This specification registers the media type application/jrd+json for 987 use with WebFinger in accordance with media type registration 988 procedures defined in [12]. 990 Type name: application 992 Subtype name: jrd+json 994 Required parameters: N/A 996 Optional parameters: N/A 998 In particular, because RFC 4627 already defines the character 999 encoding for JSON, no "charset" parameter is used. 1001 Encoding considerations: See RFC 6839, section 3.1. 1003 Security considerations: 1005 The JSON Resource Descriptor (JRD) is a JavaScript Object Notation 1006 (JSON) object. It is a text format that must be parsed by entities 1007 that wish to utilize the format. Depending on the language and 1008 mechanism used to parse a JSON object, it is possible for an 1009 attacker to inject behavior into a running program. Therefore, 1010 care must be taken to properly parse a received JRD to ensure that 1011 only a valid JSON object is present and that no JavaScript or other 1012 code is injected or executed unexpectedly. 1014 Interoperability considerations: 1016 This media type is a JavaScript Object Notation (JSON) object and 1017 can be consumed by any software application that can consume JSON 1018 objects. 1020 Published specification: RFC XXXX 1022 Applications that use this media type: 1024 The JSON Resource Descriptor (JRD) is used by the WebFinger 1025 protocol (RFC XXXX) to enable the exchange of information between a 1026 client and a WebFinger resource over HTTPS. 1028 Fragment identifier considerations: 1030 The syntax and semantics of fragment identifiers SHOULD be as 1031 specified for "application/json". (At publication of this 1032 document, there is no fragment identification syntax defined for 1033 "application/json".) 1035 Additional information: 1037 Deprecated alias names for this type: N/A 1039 Magic number(s): N/A 1041 File extension(s): jrd 1043 Macintosh file type code(s): N/A 1045 Person & email address to contact for further information: 1047 Paul E. Jones 1049 Intended usage: COMMON 1051 Restrictions on usage: N/A 1053 Author: Paul E. Jones 1055 Change controller: 1057 IESG has change control over this registration. 1059 Provisional registration? (standards tree only): N/A 1061 10. Acknowledgments 1063 This document has benefited from extensive discussion and review of 1064 many of the members of the APPSAWG working group. The authors would 1065 like to especially acknowledge the invaluable input of Eran Hammer- 1066 Lahav, Blaine Cook, Brad Fitzpatrick, Laurent-Walter Goix, Joe 1067 Clarke, Michael B. Jones, Peter Saint-Andre, Dick Hardt, Tim Bray, 1068 James Snell, Melvin Carvalho, Evan Prodromou, Mark Nottingham, Barry 1069 Leiba, Elf Pavlik, Bjoern Hoehrmann, SM, Joe Gregorio and others that 1070 we have undoubtedly, but inadvertently, missed. Special thanks go to 1071 the chairs of APPSAWG, especially Salvatore Loreto for his assistance 1072 in shepherding this document. 1074 11. References 1076 11.1. Normative References 1078 [1] Bradner, S., "Key words for use in RFCs to Indicate Requirement 1079 Levels", BCP 14, RFC 2119, March 1997. 1081 [2] Fielding, R., Gettys, J., Mogul, J., Frystyk, H., Masinter, L., 1082 Leach, P., and T. Berners-Lee, "Hypertext Transfer Protocol -- 1083 HTTP/1.1", RFC 2616, June 1999. 1085 [3] Nottingham, M., Hammer-Lahav, E., "Defining Well-Known Uniform 1086 Resource Identifiers (URIs)", RFC 5785, April 2010. 1088 [4] Nottingham, M., "Web Linking", RFC 5988, October 2010. 1090 [5] Crockford, D., "The application/json Media Type for JavaScript 1091 Object Notation (JSON)", RFC 4627, July 2006. 1093 [6] Berners-Lee, T., Fielding, R., and Masinter, L., "Uniform 1094 Resource Identifier (URI): Generic Syntax", STD 66, RFC 3986, 1095 January 2005. 1097 [7] Duerst, M., "Internationalized Resource Identifiers (IRIs)", 1098 RFC 3987, January 2005. 1100 [8] Saint-Andre, P., "The 'acct' URI Scheme", draft-ietf-appsawg- 1101 acct-uri-03, February 2013. 1103 [9] Van Kesteren, A., "Cross-Origin Resource Sharing", W3C CORS 1104 http://www.w3.org/TR/cors/, July 2010. 1106 [10] IANA, "Link Relations", http://www.iana.org/assignments/link- 1107 relations/. 1109 [11] IANA, "MIME Media Types", 1110 http://www.iana.org/assignments/media-types/index.html. 1112 [12] Freed, N., Klensin, J., Hansen, T., "Media Type Specifications 1113 and Registration Procedures", RFC 6838, January 2013. 1115 [13] Phillips, A., Davis, M., "Tags for Identifying Languages", RFC 1116 5646, January 2009. 1118 [14] Rescorla, E., "HTTP Over TLS", RFC 2818, May 2000. 1120 [15] Klyne, G., Newman, C., "Date and Time on the Internet: 1121 Timestamps", RFC 3339, July 2002. 1123 11.2. Informative References 1125 [16] Perreault, S., "vCard Format Specification", RFC 6350, August 1126 2011. 1128 [17] "Transport Independent, Printer/System Interface", IEEE Std 1129 1284.1-1997, 1997. 1131 [18] Sakimura, N., Bradley, J., Jones, M., de Medeiros, B., 1132 Mortimore, C., and E. Jay, "OpenID Connect Messages 1.0", 1133 January 2013, http://openid.net/specs/openid-connect-messages- 1134 1_0.html. 1136 [19] Hammer-Lahav, E. and Cook, B., "Web Host Metadata", RFC 6415, 1137 October 2011. 1139 [20] Hammer-Lahav, E. and W. Norris, "Extensible Resource Descriptor 1140 (XRD) Version 1.0", http://docs.oasis- 1141 open.org/xri/xrd/v1.0/xrd-1.0.html. 1143 [21] Duerst, M., Masinter, L., and J. Zawinski, "The 'mailto' URI 1144 Scheme", RFC 6068, October 2010. 1146 [22] Balduzzi, Marco, et al., "Abusing social networks for automated 1147 user profiling", Recent Advances in Intrusion Detection, 1148 Springer Berlin Heidelberg, 2010, 1149 https://www.eurecom.fr/en/publication/3042/download/rs-publi- 1150 3042_1.pdf. 1152 Author's Addresses 1154 Paul E. Jones 1155 Cisco Systems, Inc. 1156 7025 Kit Creek Rd. 1157 Research Triangle Park, NC 27709 1158 USA 1160 Phone: +1 919 476 2048 1161 Email: paulej@packetizer.com 1162 IM: xmpp:paulej@packetizer.com 1164 Gonzalo Salgueiro 1165 Cisco Systems, Inc. 1166 7025 Kit Creek Rd. 1167 Research Triangle Park, NC 27709 1168 USA 1170 Phone: +1 919 392 3266 1171 Email: gsalguei@cisco.com 1172 IM: xmpp:gsalguei@cisco.com 1174 Joseph Smarr 1175 Google 1177 Email: jsmarr@google.com