idnits 2.17.1 draft-ietf-appsawg-webfinger-16.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 (July 15, 2013) is 3930 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) ** 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) -- Possible downref: Non-RFC (?) normative reference: ref. '8' -- Possible downref: Non-RFC (?) normative reference: ref. '9' -- Possible downref: Non-RFC (?) normative reference: ref. '10' ** Obsolete normative reference: RFC 2818 (ref. '13') (Obsoleted by RFC 9110) == Outdated reference: A later version (-07) exists of draft-ietf-appsawg-acct-uri-06 Summary: 5 errors (**), 0 flaws (~~), 2 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: January 15, 2014 Joseph Smarr 6 Google 7 July 15, 2013 9 WebFinger 10 draft-ietf-appsawg-webfinger-16.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 January 15, 2014. 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. Identity Provider Discovery for OpenID Connect............3 58 3.2. Getting Author and Copyright Information for a Web Page...4 59 4. WebFinger Protocol.............................................5 60 4.1. Constructing the Query Component of the Request URI.......6 61 4.2. Performing a WebFinger Query..............................7 62 4.3. The "rel" Parameter.......................................8 63 4.4. The JSON Resource Descriptor (JRD)........................9 64 4.4.1. subject.............................................10 65 4.4.2. aliases.............................................10 66 4.4.3. properties..........................................10 67 4.4.4. links...............................................10 68 4.5. WebFinger and URIs.......................................12 69 5. Cross-Origin Resource Sharing (CORS)..........................12 70 6. Access Control................................................13 71 7. Hosted WebFinger Services.....................................13 72 8. Security Considerations.......................................14 73 8.1. Transport-Related Issues.................................14 74 8.2. User Privacy Considerations..............................15 75 8.3. Abuse Potential..........................................16 76 8.4. Information Reliability..................................17 77 9. IANA Considerations...........................................17 78 9.1. Well-Known URI...........................................17 79 9.2. JSON Resource Descriptor (JRD) Media Type................17 80 10. Acknowledgments..............................................19 81 11. References...................................................19 82 11.1. Normative References....................................19 83 11.2. Informative References..................................20 84 Author's Addresses...............................................21 86 1. Introduction 88 WebFinger is used to discover information about people or other 89 entities on the Internet that are identified by a URI [6] or IRI [7] 90 using standard Hypertext Transfer Protocol (HTTP) [2] methods over a 91 secure transport [13]. A WebFinger resource returns a JavaScript 92 Object Notation (JSON) [5] object describing the entity that is 93 queried. The JSON object is referred to as the JSON Resource 94 Descriptor (JRD). 96 For a person, the kinds of information that might be discoverable via 97 WebFinger include a personal profile address, identity service, 98 telephone number, or preferred avatar. For other entities on the 99 Internet, a WebFinger resource might return JRDs containing link 100 relations [9] that enable a client to discover, for example, the that 101 a printer can print in color on A4 paper, the physical location of a 102 server, or other static information. 104 Information returned via WebFinger might be for direct human 105 consumption (e.g., looking up someone's phone number), or it might be 106 used by systems to help carry out some operation (e.g., facilitate, 107 with additional security mechanisms, logging into a web site by 108 determining a user's identity service). The information is intended 109 to be static in nature and, as such, WebFinger is not intended to be 110 used to return dynamic information like the temperature of a CPU or 111 the current toner level in a laser printer. 113 The WebFinger protocol is designed to be used across many 114 applications. Applications that wish to utilize WebFinger will need 115 to specify properties, titles, and link relation types that are 116 appropriate for the application. Further, applications will need to 117 define the appropriate URI scheme to utilize for the query target. 119 Use of WebFinger is illustrated in the examples in Section 3 and 120 described more formally in Section 4. 122 2. Terminology 124 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 125 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 126 document are to be interpreted as described in RFC 2119 [1]. 128 WebFinger makes heavy use of "Link Relations". A Link Relation is an 129 attribute-and-value pair in which the attribute identifies the type 130 of relationship between the linked entity or resource and the 131 information specified in the value. In Web Linking [4], the link 132 relation is represented using an HTTP entity-header of "Link", where 133 the "rel" attribute specifies the type of relationship and the "href" 134 attribute specifies the information that is linked to the entity or 135 resource. In WebFinger, the same concept is represented using a JSON 136 array of "links" objects, where each member named "rel" specifies the 137 type of relationship and each member named "href" specifies the 138 information that is linked to the entity or resource. Note that 139 WebFinger narrows the scope of a link relation beyond what is defined 140 for Web Linking by stipulating that the value of the "rel" member 141 needs to be either a single IANA-registered link relation type [9] or 142 a URI [6]. 144 3. Example Uses of WebFinger 146 This non-normative section shows a few sample uses of WebFinger. 148 3.1. Identity Provider Discovery for OpenID Connect 150 Suppose Carol wishes to authenticate with a web site she visits using 151 OpenID Connect [15]. She would provide the web site with her OpenID 152 Connect identifier, say carol@example.com. The visited web site 153 would perform a WebFinger query looking for the OpenID Connect 154 Provider. Since the site is interested in only one particular link 155 relation, the WebFinger resource might utilize the "rel" parameter as 156 described in Section 4.3: 158 GET /.well-known/webfinger? 159 resource=acct%3Acarol%40example.com& 160 rel=http%3A%2F%2Fopenid.net%2Fspecs%2Fconnect%2F1.0%2Fissuer 161 HTTP/1.1 162 Host: example.com 164 The server might respond like this: 166 HTTP/1.1 200 OK 167 Access-Control-Allow-Origin: * 168 Content-Type: application/jrd+json 170 { 171 "subject" : "acct:carol@example.com", 172 "links" : 173 [ 174 { 175 "rel" : "http://openid.net/specs/connect/1.0/issuer", 176 "href" : "https://openid.example.com" 177 } 178 ] 179 } 181 Since the "rel" parameter only serves to filter the link relations 182 returned by the resource, other name/value pairs in the response, 183 including any aliases or properties, would be returned. Also, since 184 support for the "rel" parameter is not guaranteed, the client must 185 not assume the "links" array will contain only the requested link 186 relation. 188 3.2. Getting Author and Copyright Information for a Web Page 190 Suppose an application would like to retrieve metadata information 191 about a web page URL, such as author and copyright information. To 192 do that, the application can utilize WebFinger to issue a query for 193 the specific URL. Suppose the URL of interest is 194 http://blog.example.com/article/id/314. The application would issue 195 a query similar to the following: 197 GET /.well-known/webfinger? 198 resource=http%3A%2F%2Fblog.example.com%2Farticle%2Fid%2F314 199 HTTP/1.1 200 Host: example.com 202 The server might then reply in this way: 204 HTTP/1.1 200 OK 205 Access-Control-Allow-Origin: * 206 Content-Type: application/jrd+json 207 { 208 "subject" : "http://blog.example.com/article/id/314", 209 "aliases" : 210 [ 211 "http://blog.example.com/cool_new_thing", 212 "http://blog.example.com/steve/article/7" 213 ], 214 "properties" : 215 { 216 "http://blgx.example.net/ns/version" : 1.3, 217 "http://blgx.example.net/ns/ext" : null 218 }, 219 "links" : 220 [ 221 { 222 "rel" : "copyright", 223 "href" : "http://www.example.com/copyright" 224 }, 225 { 226 "rel" : "author", 227 "href" : "http://blog.example.com/author/steve", 228 "titles" : 229 { 230 "en-us" : "The Magical World of Steve", 231 "fr" : "Le Monde Magique de Steve" 232 }, 233 "properties" : 234 { 235 "http://example.com/role" : "editor" 236 } 237 } 238 ] 239 } 241 In the above example, we see that the server returned a list of 242 aliases, properties, and links related to the subject URL. The links 243 contain references to information for each link relation type. For 244 the author link, the server provided a reference to the author's 245 blog, along with a title for the blog in two languages. The server 246 also returned a single property related to the author, indicating the 247 author's role as editor of the blog. 249 It is worth noting that, while the server returned just two links in 250 the links array in this example, a server might return any number of 251 links when queried. 253 4. WebFinger Protocol 255 The WebFinger protocol is used to request information about an entity 256 identified by a query target (a URI). The client can optionally 257 specify one or more link relation types for which it would like to 258 receive information. 260 A WebFinger request is an HTTPS request to a WebFinger resource. A 261 WebFinger resource is a well-known URI [3] using the HTTPS scheme, 262 constructed along with the required query target and optional link 263 relation types. WebFinger resources MUST NOT be served with any 264 other URI scheme (such as HTTP). 266 A WebFinger resource is always given a query target, which is another 267 URI that identifies the entity whose information is sought. GET 268 requests to a WebFinger resource convey the query target in the 269 "resource" parameter in the WebFinger URI's query string; see Section 270 4.1 for details. 272 The host to which a WebFinger query is issued is significant. If the 273 query target contains a "host" portion (Section 3.2.2 of RFC 3986), 274 then the host to which the WebFinger query is issued MUST be the same 275 as the "host" portion of the query target, unless the client receives 276 instructions through some out-of-band mechanism to send the query to 277 another host. If the query target does not contain a "host" portion, 278 then the client chooses a host to which it directs the query using 279 additional information it has. 281 The path component of a WebFinger URI MUST be the well-known path 282 "/.well-known/webfinger". A WebFinger URI MUST contain a query 283 component that encodes the query target and optional link relation 284 types as specified in Section 4.1. 286 The WebFinger resource returns a JSON Resource Descriptor (JRD) as 287 the resource representation to convey information about an entity on 288 the Internet. Also, the Cross-Origin Resource Sharing (CORS) [8] 289 specification is utilized to facilitate queries made via a web 290 browser. 292 4.1. Constructing the Query Component of the Request URI 294 A WebFinger URI MUST contain a query component (see Section 3.4 of 295 RFC 3986). The query component MUST contain a "resource" parameter 296 and MAY contain one or more "rel" parameters. The "resource" 297 parameter MUST contain the query target (URI) and the "rel" 298 parameters MUST contain encoded link relation types according to the 299 encoding described in this section. 301 To construct the query component, the client performs the following 302 steps. First, each parameter value is percent-encoded, as per 303 Section 2.1 of RFC 3986. The encoding is done to conform to the 304 query production in Section 3.4 of that specification, with the 305 addition that any instances of the "=" and "&" characters within the 306 parameter values are also percent-encoded. Next, the client 307 constructs a string to be placed in the query component by 308 concatenating the name of the first parameter together with an equal 309 sign ("=") and the percent-encoded parameter value. For any 310 subsequent parameters, the client appends an ampersand ("&") to the 311 string, the name of the next parameter, an equal sign, and the 312 parameter value. The client MUST NOT insert any spaces while 313 constructing the string. The order in which the client places each 314 attribute-and-value pair within the query component does not matter 315 in the interpretation of the query component. 317 4.2. Performing a WebFinger Query 319 A WebFinger client issues a query using the GET method to the well- 320 known [3] resource identified by the URI whose path component is 321 "/.well-known/webfinger" and whose query component MUST include the 322 "resource" parameter exactly once and set to the value of the URI for 323 which information is being sought. 325 If the "resource" parameter is absent or malformed, the WebFinger 326 resource MUST indicate that the request is bad as per Section 10.4.1 327 of RFC 2616 [2]. 329 If the "resource" parameter is a value for which the server has no 330 information, the server MUST indicate that it was unable to match the 331 request as per Section 10.4.5 of RFC 2616. 333 A client MUST query the WebFinger resource using HTTPS only. If the 334 client determines that the resource has an invalid certificate, the 335 resource returns a 4xx or 5xx status code, or the HTTPS connection 336 cannot be established for any reason, then the client MUST accept 337 that the WebFinger query has failed and MUST NOT attempt to reissue 338 the WebFinger request using HTTP over a non-secure connection. 340 A WebFinger resource MUST return a JRD as the representation for the 341 resource if the client requests no other supported format explicitly 342 via the HTTP "Accept" header. The client MAY include the "Accept" 343 header to indicate a desired representation; representations other 344 than JRD might be defined in future specifications. The WebFinger 345 resource MUST silently ignore any requested representations that it 346 does not understand and support. The media type used for the JSON 347 Resource Descriptor (JRD) is "application/jrd+json" (see Section 348 9.2). 350 The properties, titles, and link relation types returned by the 351 server in a JRD might be varied and numerous. For example, the 352 server might return information about a person's blog, vCard [14], 353 avatar, OpenID Connect provider, RSS or ATOM feed, and so forth in a 354 reply. Likewise, if a server has no information to provide it might 355 return a JRD with an empty links array or no links array. 357 A WebFinger resource MAY redirect the client; if it does, the 358 redirection MUST only be to an "https" URI and the client MUST 359 perform certificate validation again when redirected. 361 A WebFinger resource can include cache validators in a response to 362 enable conditional requests by the client and/or expiration times as 363 per Section 13 of RFC 2616. 365 4.3. The "rel" Parameter 367 When issuing a request to a WebFinger resource, the client MAY 368 utilize the "rel" parameter to request only a subset of the 369 information that would otherwise be returned without the "rel" 370 parameter. When the "rel" parameter is used and accepted, only the 371 link relation types that match the link relation types provided via 372 the "rel" parameter are included in the array of links returned in 373 the JRD. If there are no matching link relation types defined for 374 the resource, the "links" array in the JRD will either be absent or 375 empty. All other information present in a resource descriptor 376 remains present, even when "rel" is employed. 378 The "rel" parameter MAY be included multiple times in order to 379 request multiple link relation types. 381 The purpose of the "rel" parameter is to return a subset of "link 382 relation objects" (see Section 4.4.4) that would otherwise be 383 returned in the resource descriptor. Use of the parameter might 384 reduce processing requirements on either the client or server, and it 385 might also reduce the bandwidth required to convey the partial 386 resource descriptor, especially if there are numerous link relation 387 values to convey for a given "resource" value. Note that if a client 388 requests a particular link relation type for which the server has no 389 information, the server MAY return a JRD with an empty links array or 390 no links array. 392 WebFinger resources SHOULD support the "rel" parameter. If the 393 resource does not support the "rel" parameter, it MUST ignore the 394 parameter and process the request as if no "rel" parameter values 395 were present. 397 The following example uses the "rel" parameter to request links for 398 two link relation types: 400 GET /.well-known/webfinger? 401 resource=acct%3Abob%40example.com& 402 rel=http%3A%2F%2Fwebfinger.example%2Frel%2Fprofile-page& 403 rel=http://webfinger.example/rel/businesscard HTTP/1.1 404 Host: example.com 406 In this example, the client requests the link relations of type 407 "http://webfinger.example/rel/profile-page" and 408 "http://webfinger.example/rel/businesscard". The server then 409 responds with a message like this: 411 HTTP/1.1 200 OK 412 Access-Control-Allow-Origin: * 413 Content-Type: application/jrd+json 415 { 416 "subject" : "acct:bob@example.com", 417 "aliases" : 418 [ 419 "https://www.example.com/~bob/" 420 ], 421 "properties" : 422 { 423 "http://example.com/ns/role/" : "employee" 424 }, 425 "links" : 426 [ 427 { 428 "rel" : "http://webfinger.example/rel/profile-page", 429 "href" : "https://www.example.com/~bob/" 430 }, 431 { 432 "rel" : "http://webfinger.example/rel/businesscard", 433 "href" : "https://www.example.com/~bob/bob.vcf" 434 } 435 ] 436 } 438 As you can see in the response, the resource representation contains 439 only the links of the types requested by the client and for which the 440 server had information, but the other parts of the JRD are still 441 present. Note also in the above example that the links returned in 442 the links array all use HTTPS, which is important if the data 443 indirectly obtained via WebFinger needs to returned securely. 445 4.4. The JSON Resource Descriptor (JRD) 447 The JSON Resource Descriptor (JRD), originally introduced in RFC 6415 448 [16] and based on the Extensible Resource Descriptor (XRD) format 449 [17], is a JSON object that comprises the following name/value pairs: 451 o subject 452 o aliases 453 o properties 454 o links 456 The member "subject" is a name/value pair whose value is a string, 457 "aliases" is an array of strings, "properties" is an object 458 comprising name/value pairs whose values are strings, and "links" is 459 an array of objects that contain link relation information. 461 When processing a JRD, the client MUST ignore any unknown member and 462 not treat the presence of an unknown member as an error. 464 Below, each of these members of the JRD is described in more detail. 466 4.4.1. subject 468 The value of the "subject" member is a URI that identifies the entity 469 that the JRD describes. 471 The "subject" value returned by a WebFinger resource MAY differ from 472 the value of the "resource" parameter used in the client's request. 473 This might happen, for example, when the subject's identity changes 474 (e.g., a user moves his or her account to another service) or when 475 the resource prefers to express URIs in canonical form. 477 The "subject" member SHOULD be present in the JRD. 479 4.4.2. aliases 481 The "aliases" array is an array of zero or more URI strings that 482 identify the same entity as the "subject" URI. Each URI must be an 483 absolute URI. 485 The "aliases" array is OPTIONAL in the JRD. 487 4.4.3. properties 489 The "properties" object comprises zero or more name/value pairs whose 490 names are absolute URIs and whose values are strings or null. 491 Properties are used to convey additional information about the 492 subject of the JRD. As an example, consider this use of 493 "properties": 495 "properties" : { "http://webfinger.example/ns/name" : "Bob Smith" } 497 The "properties" member is OPTIONAL in the JRD. 499 4.4.4. links 501 The "links" array has any number of member objects, each of which 502 represents a link [4]. Each of these link objects can have the 503 following members: 505 o rel 506 o type 507 o href 508 o titles 509 o properties 511 The "rel" and "href" members are strings representing the link's 512 relation type and the target IRI, respectively. The context of the 513 link is the "subject" (see Section 4.4.1). 515 The "type" member is a string indicating what the media type of the 516 result of dereferencing the link ought to be. 518 The order of elements in the "links" array indicates an order of 519 preference. Thus, if there are two or more link relations having the 520 same "rel" value, the first link relation would indicate the user's 521 preferred link. 523 The "links" array is OPTIONAL in the JRD. 525 Below, each of the members of the objects found in the "links" array 526 is described in more detail. Each object in the "links" array, 527 referred to as a "link relation object", is completely independent 528 from any other object in the array; any requirement to include a 529 given member in the link relation object refers only to that 530 particular object. 532 4.4.4.1. rel 534 The value of the "rel" member is a string that is either an absolute 535 URI or a registered relation type [9] (see RFC 5988 [4]). The value 536 of the "rel" member MUST contain exactly one URI or registered 537 relation type. The URI or registered relation type identifies the 538 type of the link relation. 540 The other members of the object have meaning only once the type of 541 link relation is understood. In some instances, the link relation 542 will have associated semantics enabling the client to query for other 543 resources on the Internet. In other instances, the link relation 544 will have associated semantics enabling the client to utilize the 545 other members of the link relation object without fetching additional 546 external resources. 548 URI link relation type values are compared using the "Simple String 549 Comparison" algorithm of section 6.2.1 of RFC 3986 [6]. 551 The "rel" member MUST be present in the link relation object. 553 4.4.4.2. type 555 The value of the "type" member is a string that indicates the media 556 type [10] of the target resource (see RFC 6838 [11]). 558 The "type" member is OPTIONAL in the link relation object. 560 4.4.4.3. href 562 The value of the "href" member is a string that contains a URI 563 pointing to the target resource. 565 The "href" member is OPTIONAL in the link relation object. 567 4.4.4.4. titles 569 The "titles" object comprises zero or more name/value pairs whose 570 name is a language tag [12] or the string "und". The string is 571 human-readable and describes the link relation. More than one title 572 for the link relation MAY be provided for the benefit of users who 573 utilize the link relation and, if used, a language identifier SHOULD 574 be duly used as the name. If the language is unknown or unspecified, 575 then the name is "und". 577 A JRD SHOULD NOT include more than one title identified with the same 578 language tag (or "und") within the link relation object. Meaning is 579 undefined if a link relation object includes more than one title 580 named with the same language tag (or "und"), though this MUST NOT be 581 treated as an error. A client MAY select whichever title or titles 582 it wishes to utilize. 584 Here is an example of the titles object: 586 "titles" : 587 { 588 "en-us" : "The Magical World of Steve", 589 "fr" : "Le Monde Magique de Steve" 590 } 592 The "titles" member is OPTIONAL in the link relation object. 594 4.4.4.5. properties 596 The "properties" object within the link relation object comprises 597 zero or more name/value pairs whose names are absolute URIs and whose 598 values are strings or null. Properties are used to convey additional 599 information about the link relation. As an example, consider this 600 use of "properties": 602 "properties" : { "http://webfinger.example/mail/port" : "993" } 604 The "properties" member is OPTIONAL in the link relation object. 606 4.5. WebFinger and URIs 608 WebFinger requests include a "resource" parameter (see Section 4.1) 609 specifying the URI for which the client requests information. 610 WebFinger is neutral regarding the scheme of such a URI: it could be 611 an "acct" URI [18], an "http" or "https" URI, a "mailto" URI [19], or 612 some other scheme. 614 5. Cross-Origin Resource Sharing (CORS) 616 WebFinger resources might not be accessible from a web browser due to 617 "Same-Origin" policies. The current best practice is to make 618 resources available to browsers through Cross-Origin Resource Sharing 619 (CORS) [8], and servers MUST include the Access-Control-Allow-Origin 620 HTTP header in responses. Servers SHOULD support the least 621 restrictive setting by allowing any domain access to the WebFinger 622 resource: 624 Access-Control-Allow-Origin: * 626 There are cases where defaulting to the least restrictive setting is 627 not appropriate, for example a server on an intranet that provides 628 sensitive company information SHOULD NOT allow CORS requests from any 629 domain, as that could allow leaking of that sensitive information. A 630 server that wishes to restrict access to information from external 631 entities SHOULD use a more restrictive Access-Control-Allow-Origin 632 header. 634 6. Access Control 636 As with all web resources, access to the WebFinger resource could 637 require authentication. Further, failure to provide required 638 credentials might result in the server forbidding access or providing 639 a different response than had the client authenticated with the 640 server. 642 Likewise, a WebFinger resource MAY provide different responses to 643 different clients based on other factors, such as whether the client 644 is inside or outside a corporate network. As a concrete example, a 645 query performed on the internal corporate network might return link 646 relations to employee pictures, whereas link relations for employee 647 pictures might not be provided to external entities. 649 Further, link relations provided in a WebFinger resource 650 representation might point to web resources that impose access 651 restrictions. For example, the aforementioned corporate server may 652 provide both internal and external entities with URIs to employee 653 pictures, but further authentication might be required in order for 654 the client to access the picture resources if the request comes from 655 outside the corporate network. 657 The decisions made with respect to what set of link relations a 658 WebFinger resource provides to one client versus another and what 659 resources require further authentication, as well as the specific 660 authentication mechanisms employed, are outside the scope of this 661 document. 663 7. Hosted WebFinger Services 665 As with most services provided on the Internet, it is possible for a 666 domain owner to utilize "hosted" WebFinger services. By way of 667 example, a domain owner might control most aspects of their domain, 668 but use a third-party hosting service for email. In the case of 669 email, MX records identify mail servers for a domain. An MX record 670 points to the mail server to which mail for the domain should be 671 delivered. It does not matter to the sending mail server whether 672 those MX records point to a server in the destination domain or a 673 different domain. 675 Likewise, a domain owner might utilize the services of a third party 676 to provide WebFinger services on behalf of its users. Just as a 677 domain owner was required to insert MX records into DNS to allow for 678 hosted email serves, the domain owner is required to redirect HTTP 679 queries to its domain to allow for hosted WebFinger services. 681 When a query is issued to the WebFinger resource, the web server MUST 682 return a response with a redirection status code that includes a 683 Location header pointing to the location of the hosted WebFinger 684 service URI. This WebFinger service URI does not need to point to 685 the well-known WebFinger location on the hosting service provider 686 server. 688 As an example, assume that example.com's WebFinger services are 689 hosted by wf.example.net. Suppose a client issues a query for 690 acct:alice@example.com like this: 692 GET /.well-known/webfinger? 693 resource=acct%3Aalice%40example.com HTTP/1.1 694 Host: example.com 696 The server might respond with this: 698 HTTP/1.1 307 Temporary Redirect 699 Access-Control-Allow-Origin: * 700 Location: https://wf.example.net/example.com/webfinger? 701 resource=acct%3Aalice%40example.com 703 The client can then follow the redirection, re-issuing the request to 704 the URI provided in the Location header. Note that the server will 705 include any required URI parameters in the Location header value, 706 which could be different than the URI parameters the client 707 originally used. 709 8. Security Considerations 711 8.1. Transport-Related Issues 713 Since this specification utilizes Cross-Origin Resource Sharing 714 (CORS) [8], all of the security considerations applicable to CORS are 715 also applicable to this specification. 717 The use of HTTPS is REQUIRED to ensure that information is not 718 modified during transit. It should be appreciated that in 719 environments where a web server is normally available, there exists 720 the possibility that a compromised network might have its WebFinger 721 resource operating on HTTPS replaced with one operating only over 722 HTTP. As such, clients MUST NOT issue queries over a non-secure 723 connection. 725 Clients MUST verify that the certificate used on an HTTPS connection 726 is valid (as defined in [13]) and accept a response only if the 727 certificate is valid. 729 8.2. User Privacy Considerations 731 Service providers and users should be aware that placing information 732 on the Internet means that any user can access that information and 733 WebFinger can be used to make it even easier to discover that 734 information. While WebFinger can be an extremely useful tool for 735 discovering one's avatar, blog, or other personal data, users should 736 understand the risks, too. 738 Systems or services that expose personal data via WebFinger MUST 739 provide an interface by which users can select which data elements 740 are exposed through the WebFinger interface. For example, social 741 networking sites might allow users to mark certain data as "public" 742 and then utilize that marking as a means of determining what 743 information to expose via WebFinger. The information published via 744 WebFinger would thus comprise only the information marked as public 745 by the user. Further, the user has the ability to remove information 746 from publication via WebFinger by removing this marking. 748 WebFinger MUST NOT be used to provide any personal data unless 749 publishing that data via WebFinger by the relevant service was 750 explicitly authorized by the person whose information is being 751 shared. Publishing one's personal data within an access-controlled 752 or otherwise limited environment on the Internet does not equate to 753 providing implicit authorization of further publication of that data 754 via WebFinger. 756 The privacy and security concerns with publishing personal data via 757 WebFinger are worth emphasizing again with respect to personal data 758 that might reveal a user's current context (e.g., the user's 759 location). The power of WebFinger comes from providing a single 760 place where others can find pointers to information about a person, 761 but service providers and users should be mindful of the nature of 762 that information shared and the fact that it might be available for 763 the entire world to see. Sharing location information, for example, 764 would potentially put a person in danger from any individual who 765 might seek to inflict harm on that person. 767 Users should be aware of how easily personal data one might publish 768 can be used in unintended ways. In one study relevant to WebFinger- 769 like services, Balduzzi et al. [20] took a large set of leaked email 770 addresses and demonstrated a number of potential privacy concerns, 771 including the ability to cross-correlate the same user's accounts 772 over multiple social networks. The authors also describe potential 773 mitigation strategies. 775 The easy access to user information via WebFinger was a design goal 776 of the protocol, not a limitation. If one wishes to limit access to 777 information available via WebFinger, such as WebFinger resources for 778 use inside a corporate network, the network administrator needs to 779 take necessary measures to limit access from outside the network. 780 Using standard methods for securing web resources, network 781 administrators do have the ability to control access to resources 782 that might return sensitive information. Further, a server can be 783 employed in such a way as to require authentication and prevent 784 disclosure of information to unauthorized entities. 786 8.3. Abuse Potential 788 Service providers should be mindful of the potential for abuse using 789 WebFinger. 791 As one example, one might query a WebFinger server only to discover 792 whether a given URI is valid or not. With such a query, the person 793 may deduce that an email identifier is valid, for example. Such an 794 approach could help spammers maintain a current list of known email 795 addresses and to discover new ones. 797 WebFinger could be used to associate a name or other personal data 798 with an email address, allowing spammers to craft more convincing 799 email messages. This might be of particular value in phishing 800 attempts. 802 It is RECOMMENDED that implementers of WebFinger server software take 803 steps to mitigate abuse, including malicious over-use of the server 804 and harvesting of user information. Although there is no mechanism 805 that can guarantee that publicly-accessible WebFinger databases won't 806 be harvested, rate-limiting by IP address will prevent or at least 807 dramatically slow harvest by private individuals without access to 808 botnets or other distributed systems. The reason these mitigation 809 strategies are not mandatory is that the correct choice of mitigation 810 strategy (if any) depends greatly on the context. Implementers 811 should not construe this as meaning that they do not need to consider 812 whether to use a mitigation strategy, and, if so, what strategy to 813 use. 815 WebFinger client developers should also be aware of potential abuse 816 by spammers or those phishing for information about users. As an 817 example, suppose a mail client was configured to automatically 818 perform a WebFinger query on the sender of each received mail 819 message. If a spammer sent an email using a unique identifier in the 820 'From' header, then when the WF query was performed the spammer would 821 be able to associate the request with a particular user's email 822 address. This would provide information to the spammer, including 823 the user's IP address, the fact the user just checked email, what 824 kind of WebFinger client the user utilized, and so on. For this 825 reason, it is strongly advised that clients not perform WebFinger 826 queries unless authorized by the user to do so. 828 8.4. Information Reliability 830 A WebFinger resource has no means of ensuring that information 831 provided by a user is accurate. Likewise, neither the resource nor 832 the client can be absolutely guaranteed that information has not been 833 manipulated either at the server or along the communication path 834 between the client and server. Use of HTTPS helps to address some 835 concerns with manipulation of information along the communication 836 path, but it clearly cannot address issues where the resource 837 provided incorrect information, either due to being provided false 838 information or due to malicious behavior on the part of the server 839 administrator. As with any information service available on the 840 Internet, users should be wary of information received from untrusted 841 sources. 843 9. IANA Considerations 845 9.1. Well-Known URI 847 This specification registers the "webfinger" well-known URI in the 848 Well-Known URI Registry as defined by [3]. 850 URI suffix: webfinger 852 Change controller: IETF 854 Specification document(s): RFC XXXX 856 Related information: The query to the WebFinger resource will 857 include one or more parameters in the query string; see Section 4.1 858 of RFCXXXX. Resources at this location are able to return a JSON 859 Resource Descriptor (JRD) as described in Section 4.4 of RFCXXXX. 861 [RFC EDITOR: Please replace "XXXX" references in this section and the 862 following section with the number for this RFC.] 864 9.2. JSON Resource Descriptor (JRD) Media Type 866 This specification registers the media type application/jrd+json for 867 use with WebFinger in accordance with media type registration 868 procedures defined in [11]. 870 Type name: application 872 Subtype name: jrd+json 874 Required parameters: N/A 876 Optional parameters: N/A 878 In particular, because RFC 4627 already defines the character 879 encoding for JSON, no "charset" parameter is used. 881 Encoding considerations: See RFC 6839, section 3.1. 883 Security considerations: 885 The JSON Resource Descriptor (JRD) is a JavaScript Object Notation 886 (JSON) object. It is a text format that must be parsed by entities 887 that wish to utilize the format. Depending on the language and 888 mechanism used to parse a JSON object, it is possible for an 889 attacker to inject behavior into a running program. Therefore, 890 care must be taken to properly parse a received JRD to ensure that 891 only a valid JSON object is present and that no JavaScript or other 892 code is injected or executed unexpectedly. 894 Interoperability considerations: 896 This media type is a JavaScript Object Notation (JSON) object and 897 can be consumed by any software application that can consume JSON 898 objects. 900 Published specification: RFC XXXX 902 Applications that use this media type: 904 The JSON Resource Descriptor (JRD) is used by the WebFinger 905 protocol (RFC XXXX) to enable the exchange of information between a 906 client and a WebFinger resource over HTTPS. 908 Fragment identifier considerations: 910 The syntax and semantics of fragment identifiers SHOULD be as 911 specified for "application/json". (At publication of this 912 document, there is no fragment identification syntax defined for 913 "application/json".) 915 Additional information: 917 Deprecated alias names for this type: N/A 919 Magic number(s): N/A 921 File extension(s): jrd 923 Macintosh file type code(s): N/A 925 Person & email address to contact for further information: 927 Paul E. Jones 929 Intended usage: COMMON 931 Restrictions on usage: N/A 932 Author: Paul E. Jones 934 Change controller: 936 IESG has change control over this registration. 938 Provisional registration? (standards tree only): N/A 940 10. Acknowledgments 942 This document has benefited from extensive discussion and review of 943 many of the members of the APPSAWG working group. The authors would 944 like to especially acknowledge the invaluable input of Eran Hammer- 945 Lahav, Blaine Cook, Brad Fitzpatrick, Laurent-Walter Goix, Joe 946 Clarke, Michael B. Jones, Peter Saint-Andre, Dick Hardt, Tim Bray, 947 James Snell, Melvin Carvalho, Evan Prodromou, Mark Nottingham, Barry 948 Leiba, Elf Pavlik, Bjoern Hoehrmann, Subramanian Moonesamy, Joe 949 Gregorio and others that we have undoubtedly, but inadvertently, 950 missed. Special thanks go to the chairs of APPSAWG, especially 951 Salvatore Loreto for his assistance in shepherding this document. 953 11. References 955 11.1. Normative References 957 [1] Bradner, S., "Key words for use in RFCs to Indicate Requirement 958 Levels", BCP 14, RFC 2119, March 1997. 960 [2] Fielding, R., Gettys, J., Mogul, J., Frystyk, H., Masinter, L., 961 Leach, P., and T. Berners-Lee, "Hypertext Transfer Protocol -- 962 HTTP/1.1", RFC 2616, June 1999. 964 [3] Nottingham, M., Hammer-Lahav, E., "Defining Well-Known Uniform 965 Resource Identifiers (URIs)", RFC 5785, April 2010. 967 [4] Nottingham, M., "Web Linking", RFC 5988, October 2010. 969 [5] Crockford, D., "The application/json Media Type for JavaScript 970 Object Notation (JSON)", RFC 4627, July 2006. 972 [6] Berners-Lee, T., Fielding, R., and Masinter, L., "Uniform 973 Resource Identifier (URI): Generic Syntax", STD 66, RFC 3986, 974 January 2005. 976 [7] Duerst, M., "Internationalized Resource Identifiers (IRIs)", 977 RFC 3987, January 2005. 979 [8] Van Kesteren, A., "Cross-Origin Resource Sharing", W3C CORS 980 http://www.w3.org/TR/cors/, July 2010. 982 [9] IANA, "Link Relations", http://www.iana.org/assignments/link- 983 relations/. 985 [10] IANA, "MIME Media Types", 986 http://www.iana.org/assignments/media-types/index.html. 988 [11] Freed, N., Klensin, J., Hansen, T., "Media Type Specifications 989 and Registration Procedures", RFC 6838, January 2013. 991 [12] Phillips, A., Davis, M., "Tags for Identifying Languages", RFC 992 5646, January 2009. 994 [13] Rescorla, E., "HTTP Over TLS", RFC 2818, May 2000. 996 11.2. Informative References 998 [14] Perreault, S., "vCard Format Specification", RFC 6350, August 999 2011. 1001 [15] Sakimura, N., Bradley, J., Jones, M., de Medeiros, B., 1002 Mortimore, C., and E. Jay, "OpenID Connect Messages 1.0", 1003 January 2013, http://openid.net/specs/openid-connect-messages- 1004 1_0.html. 1006 [16] Hammer-Lahav, E. and Cook, B., "Web Host Metadata", RFC 6415, 1007 October 2011. 1009 [17] Hammer-Lahav, E. and W. Norris, "Extensible Resource Descriptor 1010 (XRD) Version 1.0", http://docs.oasis- 1011 open.org/xri/xrd/v1.0/xrd-1.0.html. 1013 [18] Saint-Andre, P., "The 'acct' URI Scheme", draft-ietf-appsawg- 1014 acct-uri-06, July 2013. 1016 [19] Duerst, M., Masinter, L., and J. Zawinski, "The 'mailto' URI 1017 Scheme", RFC 6068, October 2010. 1019 [20] Balduzzi, Marco, et al., "Abusing social networks for automated 1020 user profiling", Recent Advances in Intrusion Detection, 1021 Springer Berlin Heidelberg, 2010, 1022 https://www.eurecom.fr/en/publication/3042/download/rs-publi- 1023 3042_1.pdf. 1025 Author's Addresses 1027 Paul E. Jones 1028 Cisco Systems, Inc. 1029 7025 Kit Creek Rd. 1030 Research Triangle Park, NC 27709 1031 USA 1033 Phone: +1 919 476 2048 1034 Email: paulej@packetizer.com 1035 IM: xmpp:paulej@packetizer.com 1037 Gonzalo Salgueiro 1038 Cisco Systems, Inc. 1039 7025 Kit Creek Rd. 1040 Research Triangle Park, NC 27709 1041 USA 1043 Phone: +1 919 392 3266 1044 Email: gsalguei@cisco.com 1045 IM: xmpp:gsalguei@cisco.com 1047 Joseph Smarr 1048 Google 1050 Email: jsmarr@google.com