idnits 2.17.1 draft-ietf-appsawg-webfinger-11.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 8, 2013) is 4061 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 996, 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 8, 2013 Joseph Smarr 6 Google 7 March 8, 2013 9 WebFinger 10 draft-ietf-appsawg-webfinger-11.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 8, 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......................8 63 4.2. Performing a WebFinger Query..............................9 64 4.3. The "rel" Parameter.......................................9 65 4.4. The JSON Resource Descriptor (JRD).......................11 66 4.4.1. subject.............................................11 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 9. IANA Considerations...........................................18 76 9.1. Well-Known URI...........................................18 77 9.2. JSON Resource Descriptor (JRD) Media Type................18 78 10. Acknowledgments..............................................20 79 11. References...................................................20 80 11.1. Normative References....................................20 81 11.2. Informative References..................................21 82 Author's Addresses...............................................22 84 1. Introduction 86 WebFinger is used to discover information about people or other 87 entities on the Internet that are identified by a URI [6] or IRI [7] 88 using standard Hypertext Transfer Protocol (HTTP) [2] methods over a 89 secure transport [14]. A WebFinger resource returns a JavaScript 90 Object Notation (JSON) [5] object describing the entity that is 91 queried. The JSON object is referred to as the JSON Resource 92 Descriptor (JRD). 94 For a person, the kinds of information that might be discoverable via 95 WebFinger include a personal profile address, identity service, 96 telephone number, or preferred avatar. For other entities on the 97 Internet, a WebFinger resource might return JRDs containing link 98 relations [10] that enable a client to discover, for example, the 99 amount of toner in a printer or the physical location of a server. 101 Information returned via WebFinger might be for direct human 102 consumption (e.g., looking up someone's phone number), or it might be 103 used by systems to help carry out some operation (e.g., facilitate 104 logging into a web site by determining a user's identity service). 106 Use of WebFinger is illustrated in the examples in Section 3 and 107 described more formally in Section 4. 109 2. Terminology 111 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 112 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 113 document are to be interpreted as described in RFC 2119 [1]. 115 WebFinger makes heavy use of "Link Relations". A Link Relation is an 116 attribute-and-value pair in which the attribute identifies the type 117 of relationship between the linked entity or resource and the 118 information specified in the value. In Web Linking [4], the link 119 relation is represented using an HTTP entity-header of "Link", where 120 the "rel" attribute specifies the type of relationship and the "href" 121 attribute specifies the information that is linked to the entity or 122 resource. In WebFinger, the same concept is represented using a JSON 123 array of "links" objects, where each member named "rel" specifies the 124 type of relationship and each member named "href" specifies the 125 information that is linked to the entity or resource. Note that 126 WebFinger narrows the scope of a link relation beyond what is defined 127 for Web Linking by stipulating that the value of the "rel" member 128 needs to be either a single IANA-registered link relation type [10] 129 or a URI [6]. 131 3. Example Uses of WebFinger 133 This non-normative section shows a few sample uses of WebFinger. 135 3.1. Locating a User's Blog 137 Assume you receive an email from Bob and he refers to something he 138 posted on his blog, but you do not know where Bob's blog is located. 139 It would be simple to discover the address of Bob's blog if he made 140 that information available via WebFinger. 142 Assume your email client can discover the blog for you. After 143 receiving the message from Bob (bob@example.com), your email client 144 performs a WebFinger query either automatically or at your command. 145 It does so by issuing the following HTTPS [14] query to example.com: 147 GET /.well-known/webfinger? 148 resource=acct%3Abob%40example.com HTTP/1.1 149 Host: example.com 151 The server might then respond with a message like this: 153 HTTP/1.1 200 OK 154 Access-Control-Allow-Origin: * 155 Content-Type: application/jrd+json 157 { 158 "subject" : "acct:bob@example.com", 159 "aliases" : 160 [ 161 "http://www.example.com/~bob/" 162 ], 163 "properties" : 164 { 165 "http://example.com/ns/role/" : "employee" 166 }, 167 "links" : 168 [ 169 { 170 "rel" : "http://webfinger.example/rel/avatar", 171 "type" : "image/jpeg", 172 "href" : "http://www.example.com/~bob/bob.jpg" 173 }, 174 { 175 "rel" : "http://webfinger.example/rel/profile-page", 176 "href" : "http://www.example.com/~bob/" 177 }, 178 { 179 "rel" : "http://webfinger.example/rel/blog", 180 "type" : "text/html", 181 "href" : "http://blogs.example.com/bob/", 182 "titles" : 183 { 184 "en-us" : "The Magical World of Bob", 185 "fr" : "Le Monde Magique de Bob" 186 } 187 }, 188 { 189 "rel" : "http://webfinger.example/rel/businesscard", 190 "href" : "https://www.example.com/~bob/bob.vcf" 191 } 192 ] 193 } 195 The email client would take note of the link relation in the above 196 JRD that refers to Bob's blog. The blog's URI would then be 197 presented to you so that you could then visit his blog. The email 198 client might also note that Bob has published an avatar link relation 199 and use that picture to represent Bob inside the email client. 200 Lastly, the client might automatically retrieve the data located at 201 the URI specified by the "businesscard" link relation (which might be 202 a vcard [16]) to update the information about Bob in its internal 203 address book. 205 In the above example, an "acct" URI [8] is used in the query, though 206 any valid alias for the user might also be used. See Section 4.5 for 207 more information on WebFinger and URIs. 209 An alias is a URI that is different from the "subject" URI, yet 210 identifies the same entity. In the above example, there is one 211 "http" alias returned, though there might have been more than one. 212 Had the "http:" URI shown as an alias been used to query for 213 information about Bob, the query would have appeared as: 215 GET /.well-known/webfinger? 216 resource=http%3A%2F%2Fwww.example.com%2F~bob%2F HTTP/1.1 217 Host: www.example.com 219 Note that the host queried in this example is different than for the 220 acct URI example, since the URI refers to a different host. Either 221 this host would provide a response, or it would redirect the client 222 to another host (e.g., redirect back to example.com). Either way, 223 the response would have been substantially the same, with the subject 224 and alias information changed as necessary. 226 3.2. Identity Provider Discovery for OpenID Connect 228 Suppose Carol wishes to authenticate with a web site she visits using 229 OpenID Connect [18]. She would provide the web site with her OpenID 230 Connect identifier, say carol@example.com. The visited web site 231 would perform a WebFinger query looking for the OpenID Connect 232 Provider. Since the site is interested in only one particular link 233 relation, the WebFinger resource might utilize the "rel" parameter as 234 described in Section 4.3: 236 GET /.well-known/webfinger? 237 resource=acct%3Acarol%40example.com& 238 rel=http%3A%2F%2Fopenid.net%2Fspecs%2Fconnect%2F1.0%2Fissuer 239 HTTP/1.1 240 Host: example.com 242 The server might respond like this: 244 HTTP/1.1 200 OK 245 Access-Control-Allow-Origin: * 246 Content-Type: application/jrd+json 248 { 249 "subject" : "acct:carol@example.com", 250 "links" : 251 [ 252 { 253 "rel" : "http://openid.net/specs/connect/1.0/issuer", 254 "href" : "https://openid.example.com" 255 } 256 ] 257 } 259 Since the "rel" parameter only serves to filter the link relations 260 returned by the resource, other name/value pairs in the response, 261 including any aliases or properties, would be returned. Also, since 262 support for the "rel" parameter is not guaranteed, the client must 263 not assume the "links" array will contain only the requested link 264 relation. 266 3.3. Auto-Configuration of Email Clients 268 WebFinger could be used to auto-provision an email client with basic 269 configuration data. Suppose that sue@example.com wants to configure 270 her email client. Her email client might issue the following query: 272 GET /.well-known/webfinger? 273 resource=mailto%3Asue%40example.com HTTP/1.1 274 Host: example.com 276 The returned resource representation would contain entries for the 277 various protocols, transport options, and security options. If there 278 are multiple options, the resource representation might include a 279 link relation for each of the valid options, and the client or Sue 280 might select which option to choose. Since JRDs list link relations 281 in a specific order, then the most-preferred choices could be 282 presented first. Consider this response: 284 HTTP/1.1 200 OK 285 Access-Control-Allow-Origin: * 286 Content-Type: application/jrd+json 288 { 289 "subject" : "mailto:sue@example.com", 290 "links" : 291 [ 292 { 293 "rel" : "http://webfinger.example/rel/smtp-server", 294 "properties" : 295 { 296 "http://webfinger.example/email/host" : "smtp.example.com", 297 "http://webfinger.example/email/port" : "587", 298 "http://webfinger.example/email/login-required" : "yes", 299 "http://webfinger.example/email/transport" : "starttls" 300 } 301 }, 302 { 303 "rel" : "http://webfinger.example/rel/imap-server", 304 "properties" : 305 { 306 "http://webfinger.example/email/host" : "imap.example.com", 307 "http://webfinger.example/email/port" : "993", 308 "http://webfinger.example/email/transport" : "ssl" 309 } 310 } 311 ] 312 } 314 In this example, you can see that the WebFinger resource 315 representation advertises an SMTP service and an IMAP service. In 316 this example, the "href" entries associated with the link relation 317 are absent. This is valid when there is no additional reference that 318 needs to be made. 320 3.4. Retrieving Device Information 322 As another example, suppose there are printers on the network and you 323 would like to check the current toner level for a particular printer 324 identified via the URI device:p1.example.com. While the "device" URI 325 scheme is not presently specified, we use it here for illustrative 326 purposes. 328 Following the procedures similar to those above, a query may be 329 issued to get link relations specific to this URI like this: 331 GET /.well-known/webfinger? 332 resource=device%3Ap1.example.com HTTP/1.1 333 Host: p1.example.com 335 The link relations that are returned for a device may be quite 336 different than those for user accounts. Perhaps we may see a 337 response like this: 339 HTTP/1.1 200 OK 340 Access-Control-Allow-Origin: * 341 Content-Type: application/jrd+json 342 { 343 "subject" : "device:p1.example.com", 344 "links" : 345 [ 346 { 347 "rel" : "http://webfinger.example/rel/tipsi", 348 "href" : "http://192.168.1.5/npap/" 349 } 350 ] 351 } 353 While this example is fictitious, you can imagine that perhaps the 354 Transport Independent, Printer/System Interface [17] may be enhanced 355 with a web interface enabling a device that understands the TIP/SI 356 web interface specification to query the printer for toner levels. 358 4. WebFinger Protocol 360 A WebFinger resource is a well-known URI [3] using the HTTPS scheme. 361 WebFinger resources MUST NOT be served with any other URI scheme 362 (such as HTTP). 364 A WebFinger resource is always given a query target, which is another 365 URI that identifies the entity whose information is sought. GET 366 requests to a WebFinger resource convey the query target in the 367 "resource" parameter in the WebFinger URI's query string; see Section 368 4.1 for details. 370 The WebFinger resource returns a JSON Resource Descriptor (JRD) as 371 the resource representation to convey information about an entity on 372 the Internet. Also, the Cross-Origin Resource Sharing (CORS) [9] 373 specification is utilized to facilitate queries made via a web 374 browser. 376 4.1. Constructing a WebFinger Request URI 378 This specification defines parameters that can be passed from the 379 client to the WebFinger resource when issuing a request. These 380 parameters, "resource" and "rel", and the parameter values are 381 included in the query component of the URI (see Section 3.4 of RFC 382 3986). To construct the query component, the client performs the 383 following steps. First, each parameter value is percent-encoded, as 384 per Section 2.1 of RFC 3986. The encoding is done to conform to the 385 query production in Section 3.4 of that specification, with the 386 addition that any instances of the "=" and "&" characters within the 387 parameter values are also percent-encoded. Next, the client 388 constructs a string to be placed in the query component by 389 concatenating the name of the first parameter together with an equal 390 sign ("=") and the percent-encoded parameter value. For any 391 subsequent parameters, the client appends an ampersand ("&") to the 392 string, the name of the next parameter, an equal sign, and the 393 parameter value. The client MUST NOT insert any spaces while 394 constructing the string. The order in which the client places each 395 attribute-and-value pair within the query component does not matter 396 in the interpretation of the query component. 398 4.2. Performing a WebFinger Query 400 A WebFinger client issues a query to the well-known [3] resource 401 identified by the URI whose path component begins with "/.well- 402 known/webfinger" and whose query component MUST include the 403 "resource" parameter exactly once and set to the value of the URI for 404 which information is being sought. If the "resource" parameter is 405 absent or malformed, the WebFinger resource MUST indicate that the 406 request is bad as per Section 10.4.1 of RFC 2616 [2]. 408 A client MUST query the WebFinger resource using HTTPS only. If the 409 client determines that the resource has an invalid certificate, the 410 resource returns a 4xx or 5xx status code, or the HTTPS connection 411 cannot be established for any reason, then the client MUST accept 412 that the WebFinger query has failed and MUST NOT attempt to reissue 413 the WebFinger request using HTTP over a non-secure connection. 415 A WebFinger resource MUST return a JRD as the representation for the 416 resource if the client requests no other supported format explicitly 417 via the HTTP "Accept" header. The client MAY include the "Accept" 418 header to indicate a desired representation; representations other 419 than JRD might be defined in future specifications. The WebFinger 420 resource MUST silently ignore any requested representations that it 421 does not understand and support. The media type used for the JSON 422 Resource Descriptor (JRD) is "application/jrd+json" (see Section 423 9.2). 425 A WebFinger resource MAY redirect the client; if it does, the 426 redirection MUST only be to an "https" URI. 428 A WebFinger resource can include cache validators in a response to 429 enable conditional requests by the client and/or expiration times as 430 per Section 13 of RFC 2616. 432 4.3. The "rel" Parameter 434 When issuing a request to a WebFinger resource, the client MAY 435 utilize the "rel" parameter to request only a subset of the 436 information that would otherwise be returned without the "rel" 437 parameter. When the "rel" parameter is used and accepted, only the 438 link relation types that match the link relation types provided via 439 the "rel" parameter are included in the array of links returned in 440 the JRD. If there are no matching link relation types defined for 441 the resource, the "links" array in the JRD will either be absent or 442 empty. All other information present in a resource descriptor 443 remains present, even when "rel" is employed. 445 The "rel" parameter MAY be included multiple times in order to 446 request multiple link relation types. 448 The purpose of the "rel" parameter is to return a subset of "link 449 relation objects" (see Section 4.4.4) that would otherwise be 450 returned in the resource descriptor. Use of the parameter might 451 reduce processing requirements on either the client or server, and it 452 might also reduce the bandwidth required to convey the partial 453 resource descriptor, especially if there are numerous link relation 454 values to convey for a given "resource" value. 456 WebFinger resources SHOULD support the "rel" parameter. If the 457 resource does not support the "rel" parameter, it MUST ignore the 458 parameter and process the request as if no "rel" parameter values 459 were present. 461 The following example presents the same example as found in Section 462 3.1, but uses the "rel" parameter to select two link relations: 464 GET /.well-known/webfinger? 465 resource=acct%3Abob%40example.com& 466 rel=http%3A%2F%2Fwebfinger.example%2Frel%2Fprofile-page& 467 rel=http://webfinger.example/rel/businesscard HTTP/1.1 468 Host: example.com 470 In this example, the client requests the link relations of type 471 "http://webfinger.example/rel/profile-page" and 472 "http://webfinger.example/rel/businesscard". The server then 473 responds with a message like this: 475 HTTP/1.1 200 OK 476 Access-Control-Allow-Origin: * 477 Content-Type: application/jrd+json 479 { 480 "subject" : "acct:bob@example.com", 481 "aliases" : 482 [ 483 "http://www.example.com/~bob/" 484 ], 485 "properties" : 486 { 487 "http://example.com/ns/role/" : "employee" 489 }, 490 "links" : 491 [ 492 { 493 "rel" : "http://webfinger.example/rel/profile-page", 494 "href" : "http://www.example.com/~bob/" 495 }, 496 { 497 "rel" : "http://webfinger.example/rel/businesscard", 498 "href" : "http://www.example.com/~bob/bob.vcf" 499 } 500 ] 501 } 503 As you can see in the response, the resource representation contains 504 only the link relations requested by the client, but the other parts 505 of the JRD are still present. 507 4.4. The JSON Resource Descriptor (JRD) 509 The JSON Resource Descriptor (JRD), originally introduced in RFC 6415 510 [19] and based on the Extensible Resource Descriptor (XRD) format 511 [20], is a JSON object that comprises the following name/value pairs: 513 o subject 514 o aliases 515 o properties 516 o links 518 The member "subject" is a name/value pair whose value is a string, 519 "aliases" is an array of strings, "properties" is an object 520 comprising name/value pairs whose values are strings, and "links" is 521 an array of objects that contain link relation information. 523 When processing a JRD, the client MUST ignore any unknown member and 524 not treat the presence of an unknown member as an error. 526 Below, each of these members of the JRD is described in more detail. 528 4.4.1. subject 530 The value of the "subject" member is a URI that identifies the entity 531 that the JRD describes. 533 The "subject" value returned by a WebFinger resource MAY differ from 534 the value of the "resource" parameter used in the client's request. 535 This might happen, for example, when the subject's identity changes 536 (e.g., a user moves his or her account to another service) or when 537 the resource prefers to express URIs in canonical form. 539 The "subject" member MUST be present in the JRD. 541 4.4.2. aliases 543 The "aliases" array is an array of zero or more URI strings that 544 identify the same entity as the "subject" URI. Each URI must be an 545 absolute URI. 547 The "aliases" array is OPTIONAL in the JRD. 549 4.4.3. properties 551 The "properties" object comprises zero or more name/value pairs whose 552 names are absolute URIs and whose values are strings or null. 553 Properties are used to convey additional information about the 554 subject of the JRD. As an example, consider this use of 555 "properties": 557 "properties" : { "http://webfinger.example/ns/name" : "Bob Smith" } 559 The "properties" member is OPTIONAL in the JRD. 561 4.4.4. links 563 The "links" array has any number of member objects, each of which 564 represents a link [4]. Each of these link objects can have the 565 following members: 567 o rel 568 o type 569 o href 570 o titles 571 o properties 573 The "rel" and "href" members are strings representing the link's 574 relation type and the target IRI, respectively. The context of the 575 link is the "subject" (see Section 4.4.1). 577 The "type" member is a string indicating what the media type of the 578 result of dereferencing the link ought to be. 580 The order of elements in the "links" array indicates an order of 581 preference. Thus, if there are two or more link relations having the 582 same "rel" value, the first link relation would indicate the user's 583 preferred link. 585 The "links" array is OPTIONAL in the JRD. 587 Below, each of the members of the objects found in the "links" array 588 is described in more detail. Each object in the "links" array, 589 referred to as a "link relation object", is completely independent 590 from any other object in the array; any requirement to include a 591 given member in the link relation object refers only to that 592 particular object. 594 4.4.4.1. rel 596 The value of the "rel" member is a string that is either an absolute 597 URI or a registered relation type [10] (see RFC 5988 [4]). The value 598 of the "rel" member MUST contain exactly one URI or registered 599 relation type. The URI or registered relation type identifies the 600 type of the link relation. The other members of the object have 601 meaning only once the type of link relation is understood. In some 602 instances, the link relation will have associated semantics enabling 603 the client to query for other resources on the Internet. In other 604 instances, the link relation will have associated semantics enabling 605 the client to utilize the other members of the link relation object 606 without fetching additional external resources. 608 The "rel" member MUST be present in the link relation object. 610 4.4.4.2. type 612 The value of the "type" member is a string that indicates the media 613 type [11] of the target resource (see RFC 6838 [12]). 615 The "type" member is OPTIONAL in the link relation object. 617 4.4.4.3. href 619 The value of the "href" member is a string that contains a URI 620 pointing to the target resource. 622 The "href" member is OPTIONAL in the link relation object. 624 4.4.4.4. titles 626 The "titles" object comprises zero or more name/value pairs whose 627 name is a language tag [13] or the string "default". The string is 628 human-readable and describes the link relation. More than one title 629 for the link relation MAY be provided for the benefit of users who 630 utilize the link relation and, if used, a language identifier SHOULD 631 be duly used as the name. If the language is unknown or unspecified, 632 then the name is "default". 634 A JRD SHOULD NOT include more than one title identified with the same 635 language tag (or "default") within the link relation object. Meaning 636 is undefined if a link relation object includes more than one title 637 named with the same language tag (or "default"), though this MUST NOT 638 be treated as an error. A client MAY select whichever title or 639 titles it wishes to utilize. 641 Here is an example of the titles object: 643 "titles" : 644 { 645 "en-us" : "The Magical World of Bob", 646 "fr" : "Le Monde Magique de Bob" 647 } 649 The "titles" member is OPTIONAL in the link relation object. 651 4.4.4.5. properties 653 The "properties" object within the link relation object comprises 654 zero or more name/value pairs whose names are absolute URIs and whose 655 values are strings or null. Properties are used to convey additional 656 information about the link relation. As an example, consider this 657 use of "properties": 659 "properties" : { "http://webfinger.example/mail/port" : "993" } 661 The "properties" member is OPTIONAL in the link relation object. 663 4.5. WebFinger and URIs 665 WebFinger requests include a "resource" parameter (see Section 4.1) 666 specifying the URI of an account, device, or other entity. WebFinger 667 is neutral regarding the scheme of such a URI: it could be an "acct" 668 URI [7], an "http" or "https" URI, a "mailto" URI [21], or some other 669 scheme. 671 To perform a WebFinger lookup on an account specific to the host 672 being queried, use of the "acct" URI scheme is recommended, since it 673 explicitly identifies an account accessible via WebFinger. Further, 674 the "acct" URI scheme is not associated with other protocols as, by 675 way of example, the "mailto" URI scheme is associated with email. 676 Since not every host offers email service, using the "mailto" URI 677 scheme is not ideal for identifying user accounts on all hosts. That 678 said, use of the "mailto" URI scheme would be ideal for use with 679 WebFinger to discover mail server configuration information for a 680 user. 682 5. Cross-Origin Resource Sharing (CORS) 684 WebFinger resources might not be accessible from a web browser due to 685 "Same-Origin" policies. The current best practice is to make 686 resources available to browsers through Cross-Origin Resource Sharing 687 (CORS) [9], and servers MUST include the Access-Control-Allow-Origin 688 HTTP header in responses. Servers SHOULD support the least 689 restrictive setting by allowing any domain access to the WebFinger 690 resource: 692 Access-Control-Allow-Origin: * 694 There are cases where defaulting to the least restrictive setting is 695 not appropriate, for example a server on an intranet that provides 696 sensitive company information SHOULD NOT allow CORS requests from any 697 domain, as that could allow leaking of that sensitive information. A 698 server that wishes to restrict access to information from external 699 entities SHOULD use a more restrictive Access-Control-Allow-Origin 700 header. 702 6. Access Control 704 As with all web resources, access to the WebFinger resource could 705 require authentication. Further, failure to provide required 706 credentials might result in the server forbidding access or providing 707 a different response than had the client authenticated with the 708 server. 710 Likewise, a WebFinger resource MAY provide different responses to 711 different clients based on other factors, such as whether the client 712 is inside or outside a corporate network. As a concrete example, a 713 query performed on the internal corporate network might return link 714 relations to employee pictures, whereas link relations for employee 715 pictures might not be provided to external entities. 717 Further, link relations provided in a WebFinger resource 718 representation might point to web resources that impose access 719 restrictions. For example, the aforementioned corporate server may 720 provide both internal and external entities with URIs to employee 721 pictures, but further authentication might be required in order for 722 the client to access the picture resources if the request comes from 723 outside the corporate network. 725 The decisions made with respect to what set of link relations a 726 WebFinger resource provides to one client versus another and what 727 resources require further authentication, as well as the specific 728 authentication mechanisms employed, are outside the scope of this 729 document. 731 7. Hosted WebFinger Services 733 As with most services provided on the Internet, it is possible for a 734 domain owner to utilize "hosted" WebFinger services. By way of 735 example, a domain owner might control most aspects of their domain, 736 but use a third-party hosting service for email. In the case of 737 email, MX records identify mail servers for a domain. An MX record 738 points to the mail server to which mail for the domain should be 739 delivered. It does not matter to the sending mail server whether 740 those MX records point to a server in the destination domain or a 741 different domain. 743 Likewise, a domain owner might utilize the services of a third party 744 to provide WebFinger services on behalf of its users. Just as a 745 domain owner was required to insert MX records into DNS to allow for 746 hosted email serves, the domain owner is required to redirect HTTP 747 queries to its domain to allow for hosted WebFinger services. 749 When a query is issued to the WebFinger resource, the web server MUST 750 return a response with a redirection status code that includes a 751 Location header pointing to the location of the hosted WebFinger 752 service URI. This WebFinger service URI does not need to point to 753 the well-known WebFinger location on the hosting service provider 754 server. 756 As an example, assume that example.com's WebFinger services are 757 hosted by wf.example.net. Suppose a client issues a query for 758 acct:alice@example.com like this: 760 GET /.well-known/webfinger? 761 resource=acct%3Aalice%40example.com HTTP/1.1 762 Host: example.com 764 The server might respond with this: 766 HTTP/1.1 307 Temporary Redirect 767 Access-Control-Allow-Origin: * 768 Location: https://wf.example.net/example.com/webfinger? 769 resource=acct%3Aalice%40example.com 771 The client can then follow the redirection, re-issuing the request to 772 the URI provided in the Location header. Note that the server will 773 include any required URI parameters in the Location header value, 774 which could be different than the URI parameters the client 775 originally used. 777 8. Security Considerations 779 Since this specification utilizes Cross-Origin Resource Sharing 780 (CORS) [9], all of the security considerations applicable to CORS are 781 also applicable to this specification. 783 The use of HTTPS is REQUIRED to ensure that information is not 784 modified during transit. It should be appreciated that in 785 environments where a web server is normally available, there exists 786 the possibility that a compromised network might have its WebFinger 787 resource operating on HTTPS replaced with one operating only over 788 HTTP. As such, clients MUST NOT issue queries over a non-secure 789 connection. 791 Clients MUST verify that the certificate used on an HTTPS connection 792 is valid (as defined in [14]) and accept a response only if the 793 certificate is valid. 795 Service providers and users should be aware that placing information 796 on the Internet means that any user can access that information and 797 WebFinger can be used to make it even easier to discover that 798 information. While WebFinger can be an extremely useful tool for 799 discovering one's avatar, blog, or other personal information, users 800 should understand the risks, too. If one does not wish to share 801 certain information with the world, do not allow that information to 802 be freely accessible on the Internet or discoverable via WebFinger. 803 Further, WebFinger MUST NOT be used to provide any personal 804 information to any party unless explicitly or implicitly authorized 805 by the person whose information is being shared. 807 The aforementioned word of caution is perhaps worth emphasizing again 808 with respect to information that might reveal a user's current 809 context (e.g., the user's location). The power of WebFinger comes 810 from providing a single place where others can find pointers to 811 information about a person, but service providers and users should be 812 mindful of the nature of that information shared and the fact that it 813 might be available for the entire world to see. Sharing location 814 information, for example, would potentially put a person in danger 815 from any individual who might seek to inflict harm on that person. 817 The easy access to user information via WebFinger was a design goal 818 of the protocol, not a limitation. If one wishes to limit access to 819 information available via WebFinger, such as WebFinger resources for 820 use inside a corporate network, the network administrator needs to 821 take necessary measures to limit access from outside the network. 822 Using standard methods for securing web resources, network 823 administrators do have the ability to control access to resources 824 that might return sensitive information. Further, a server can be 825 employed in such a way as to require authentication and prevent 826 disclosure of information to unauthorized entities. 828 Finally, a WebFinger resource has no means of ensuring that 829 information provided by a user is accurate. Likewise, neither the 830 resource nor the client can be absolutely guaranteed that information 831 has not been manipulated either at the server or along the 832 communication path between the client and server. Use of HTTPS helps 833 to address some concerns with manipulation of information along the 834 communication path, but it clearly cannot address issues where the 835 resource provided incorrect information, either due to being provided 836 false information or due to malicious behavior on the part of the 837 server administrator. As with any information service available on 838 the Internet, users should be wary of information received from 839 untrusted sources. 841 9. IANA Considerations 843 9.1. Well-Known URI 845 This specification registers the "webfinger" well-known URI in the 846 Well-Known URI Registry as defined by [3]. 848 URI suffix: webfinger 850 Change controller: IETF 852 Specification document(s): RFC XXXX 854 Related information: The response representation returned by a 855 WebFinger resource will be a JSON Resource Descriptor (JRD) as 856 described in Section 4.4 of RFC XXXX. 858 [RFC EDITOR: Please replace "XXXX" references in this section and the 859 following section with the number for this RFC.] 861 9.2. JSON Resource Descriptor (JRD) Media Type 863 This specification registers the media type application/jrd+json for 864 use with WebFinger in accordance with media type registration 865 procedures defined in [12]. 867 Type name: application 869 Subtype name: jrd+json 871 Required parameters: N/A 873 Optional parameters: N/A 874 In particular, because RFC 4627 already defines the character 875 encoding for JSON, no "charset" parameter is used. 877 Encoding considerations: See RFC 6839, section 3.1. 879 Security considerations: 881 The JSON Resource Descriptor (JRD) is a JavaScript Object Notation 882 (JSON) object. It is a text format that must be parsed by entities 883 that wish to utilize the format. Depending on the language and 884 mechanism used to parse a JSON object, it is possible for an 885 attacker to inject behavior into a running program. Therefore, 886 care must be taken to properly parse a received JRD to ensure that 887 only a valid JSON object is present and that no JavaScript or other 888 code is injected or executed unexpectedly. 890 Interoperability considerations: 892 This media type is a JavaScript Object Notation (JSON) object and 893 can be consumed by any software application that can consume JSON 894 objects. 896 Published specification: RFC XXXX 898 Applications that use this media type: 900 The JSON Resource Descriptor (JRD) is used by the WebFinger 901 protocol (RFC XXXX) to enable the exchange of information between a 902 client and a WebFinger resource over HTTPS. 904 Fragment identifier considerations: 906 The syntax and semantics of fragment identifiers SHOULD be as 907 specified for "application/json". (At publication of this 908 document, there is no fragment identification syntax defined for 909 "application/json".) 911 Additional information: 913 Deprecated alias names for this type: N/A 915 Magic number(s): N/A 917 File extension(s): jrd 919 Macintosh file type code(s): N/A 921 Person & email address to contact for further information: 923 Paul E. Jones 925 Intended usage: COMMON 927 Restrictions on usage: N/A 929 Author: Paul E. Jones 931 Change controller: 933 IESG has change control over this registration. 935 Provisional registration? (standards tree only): N/A 937 10. Acknowledgments 939 This document has benefited from extensive discussion and review of 940 many of the members of the APPSAWG working group. The authors would 941 like to especially acknowledge the invaluable input of Eran Hammer- 942 Lahav, Blaine Cook, Brad Fitzpatrick, Laurent-Walter Goix, Joe 943 Clarke, Michael B. Jones, Peter Saint-Andre, Dick Hardt, Tim Bray, 944 James Snell, Melvin Carvalho, Evan Prodromou, Mark Nottingham, Barry 945 Leiba, Elf Pavlik, Bjoern Hoehrmann, SM, Joe Gregorio and others that 946 we have undoubtedly, but inadvertently, missed. Special thanks go to 947 the chairs of APPSAWG, especially Salvatore Loreto for his assistance 948 in shepherding this document. 950 11. References 952 11.1. Normative References 954 [1] Bradner, S., "Key words for use in RFCs to Indicate Requirement 955 Levels", BCP 14, RFC 2119, March 1997. 957 [2] Fielding, R., Gettys, J., Mogul, J., Frystyk, H., Masinter, L., 958 Leach, P., and T. Berners-Lee, "Hypertext Transfer Protocol -- 959 HTTP/1.1", RFC 2616, June 1999. 961 [3] Nottingham, M., Hammer-Lahav, E., "Defining Well-Known Uniform 962 Resource Identifiers (URIs)", RFC 5785, April 2010. 964 [4] Nottingham, M., "Web Linking", RFC 5988, October 2010. 966 [5] Crockford, D., "The application/json Media Type for JavaScript 967 Object Notation (JSON)", RFC 4627, July 2006. 969 [6] Berners-Lee, T., Fielding, R., and Masinter, L., "Uniform 970 Resource Identifier (URI): Generic Syntax", STD 66, RFC 3986, 971 January 2005. 973 [7] Duerst, M., "Internationalized Resource Identifiers (IRIs)", 974 RFC 3987, January 2005. 976 [8] Saint-Andre, P., "The 'acct' URI Scheme", draft-ietf-appsawg- 977 acct-uri-03, February 2013. 979 [9] Van Kesteren, A., "Cross-Origin Resource Sharing", W3C CORS 980 http://www.w3.org/TR/cors/, July 2010. 982 [10] IANA, "Link Relations", http://www.iana.org/assignments/link- 983 relations/. 985 [11] IANA, "MIME Media Types", 986 http://www.iana.org/assignments/media-types/index.html. 988 [12] Freed, N., Klensin, J., Hansen, T., "Media Type Specifications 989 and Registration Procedures", RFC 6838, January 2013. 991 [13] Phillips, A., Davis, M., "Tags for Identifying Languages", RFC 992 5646, January 2001. 994 [14] Rescorla, E., "HTTP Over TLS", RFC 2818, May 2000. 996 [15] Klyne, G., Newman, C., "Date and Time on the Internet: 997 Timestamps", RFC 3339, July 2002. 999 11.2. Informative References 1001 [16] Perreault, S., "vCard Format Specification", RFC 6350, August 1002 2011. 1004 [17] "Transport Independent, Printer/System Interface", IEEE Std 1005 1284.1-1997, 1997. 1007 [18] Sakimura, N., Bradley, J., Jones, M., de Medeiros, B., 1008 Mortimore, C., and E. Jay, "OpenID Connect Messages 1.0", 1009 January 2013, http://openid.net/specs/openid-connect-messages- 1010 1_0.html. 1012 [19] Hammer-Lahav, E. and Cook, B., "Web Host Metadata", RFC 6415, 1013 October 2011. 1015 [20] Hammer-Lahav, E. and W. Norris, "Extensible Resource Descriptor 1016 (XRD) Version 1.0", http://docs.oasis- 1017 open.org/xri/xrd/v1.0/xrd-1.0.html. 1019 [21] Duerst, M., Masinter, L., and J. Zawinski, "The 'mailto' URI 1020 Scheme", RFC 6068, October 2010. 1022 Author's Addresses 1024 Paul E. Jones 1025 Cisco Systems, Inc. 1026 7025 Kit Creek Rd. 1027 Research Triangle Park, NC 27709 1028 USA 1030 Phone: +1 919 476 2048 1031 Email: paulej@packetizer.com 1032 IM: xmpp:paulej@packetizer.com 1034 Gonzalo Salgueiro 1035 Cisco Systems, Inc. 1036 7025 Kit Creek Rd. 1037 Research Triangle Park, NC 27709 1038 USA 1040 Phone: +1 919 392 3266 1041 Email: gsalguei@cisco.com 1042 IM: xmpp:gsalguei@cisco.com 1044 Joseph Smarr 1045 Google 1047 Email: jsmarr@google.com