idnits 2.17.1 draft-ietf-appsawg-webfinger-17.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 (August 9, 2013) is 3914 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. '7' -- Possible downref: Non-RFC (?) normative reference: ref. '8' -- Possible downref: Non-RFC (?) normative reference: ref. '9' ** Obsolete normative reference: RFC 2818 (ref. '12') (Obsoleted by RFC 9110) ** Obsolete normative reference: RFC 5226 (ref. '13') (Obsoleted by RFC 8126) == Outdated reference: A later version (-07) exists of draft-ietf-appsawg-acct-uri-06 Summary: 6 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: February 9, 2014 Joseph Smarr 6 Google 7 August 9, 2013 9 WebFinger 10 draft-ietf-appsawg-webfinger-17.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 February 9, 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......................................4 57 3.1. Identity Provider Discovery for OpenID Connect............4 58 3.2. Getting Author and Copyright Information for a Web Page...5 59 4. WebFinger Protocol.............................................6 60 4.1. Constructing the Query Component of the Request URI.......7 61 4.2. Performing a WebFinger Query..............................7 62 4.3. The "rel" Parameter.......................................8 63 4.4. The JSON Resource Descriptor (JRD).......................10 64 4.4.1. subject.............................................10 65 4.4.2. aliases.............................................10 66 4.4.3. properties..........................................10 67 4.4.4. links...............................................11 68 4.5. WebFinger and URIs.......................................13 69 5. Cross-Origin Resource Sharing (CORS)..........................13 70 6. Access Control................................................13 71 7. Hosted WebFinger Services.....................................14 72 8. Definition of WebFinger Applications..........................15 73 8.1. Specification of the URI Scheme and URI..................15 74 8.2. Host Resolution..........................................15 75 8.3. Specification of Properties..............................16 76 8.4. Specification of Links...................................16 77 8.5. One URI, Multiple Applications...........................16 78 8.6. Registration of Link Relation Types and Properties.......17 79 9. Security Considerations.......................................17 80 9.1. Transport-Related Issues.................................17 81 9.2. User Privacy Considerations..............................17 82 9.3. Abuse Potential..........................................18 83 9.4. Information Reliability..................................19 84 10. IANA Considerations..........................................20 85 10.1. Well-Known URI..........................................20 86 10.2. JSON Resource Descriptor (JRD) Media Type...............20 87 10.3. Registering Link Relation Types.........................21 88 10.4. Establishment of the WebFinger Properties Registry......22 89 10.4.1. The Registration Template..........................22 90 10.4.2. The Registration Procedures........................22 91 11. Acknowledgments..............................................23 92 12. References...................................................23 93 12.1. Normative References....................................23 94 12.2. Informative References..................................24 95 Author's Addresses...............................................25 97 1. Introduction 99 WebFinger is used to discover information about people or other 100 entities on the Internet that are identified by a URI [6] using 101 standard Hypertext Transfer Protocol (HTTP) [2] methods over a secure 102 transport [12]. A WebFinger resource returns a JavaScript Object 103 Notation (JSON) [5] object describing the entity that is queried. 104 The JSON object is referred to as the JSON Resource Descriptor (JRD). 106 For a person, the kinds of information that might be discoverable via 107 WebFinger include a personal profile address, identity service, 108 telephone number, or preferred avatar. For other entities on the 109 Internet, a WebFinger resource might return JRDs containing link 110 relations [8] that enable a client to discover, for example, the that 111 a printer can print in color on A4 paper, the physical location of a 112 server, or other static information. 114 Information returned via WebFinger might be for direct human 115 consumption (e.g., looking up someone's phone number), or it might be 116 used by systems to help carry out some operation (e.g., facilitate, 117 with additional security mechanisms, logging into a web site by 118 determining a user's identity service). The information is intended 119 to be static in nature and, as such, WebFinger is not intended to be 120 used to return dynamic information like the temperature of a CPU or 121 the current toner level in a laser printer. 123 The WebFinger protocol is designed to be used across many 124 applications. Applications that wish to utilize WebFinger will need 125 to specify properties, titles, and link relation types that are 126 appropriate for the application. Further, applications will need to 127 define the appropriate URI scheme to utilize for the query target. 129 Use of WebFinger is illustrated in the examples in Section 3 and 130 described more formally in Section 4. 132 2. Terminology 134 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 135 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 136 document are to be interpreted as described in RFC 2119 [1]. 138 WebFinger makes heavy use of "Link Relations". A Link Relation is an 139 attribute-and-value pair in which the attribute identifies the type 140 of relationship between the linked entity or resource and the 141 information specified in the value. In Web Linking [4], the link 142 relation is represented using an HTTP entity-header of "Link", where 143 the "rel" attribute specifies the type of relationship and the "href" 144 attribute specifies the information that is linked to the entity or 145 resource. In WebFinger, the same concept is represented using a JSON 146 array of "links" objects, where each member named "rel" specifies the 147 type of relationship and each member named "href" specifies the 148 information that is linked to the entity or resource. Note that 149 WebFinger narrows the scope of a link relation beyond what is defined 150 for Web Linking by stipulating that the value of the "rel" member 151 needs to be either a single IANA-registered link relation type [8] or 152 a URI [6]. 154 The use of URIs throughout this document refers to URIs following the 155 syntax specified in Section 3 of RFC 3986 [6]. Relative URIs, having 156 syntax following that of Section 4.2 or RFC 3986, are not used with 157 WebFinger. 159 3. Example Uses of WebFinger 161 This non-normative section shows a few sample uses of WebFinger. 163 3.1. Identity Provider Discovery for OpenID Connect 165 Suppose Carol wishes to authenticate with a web site she visits using 166 OpenID Connect [15]. She would provide the web site with her OpenID 167 Connect identifier, say carol@example.com. The visited web site 168 would perform a WebFinger query looking for the OpenID Connect 169 Provider. Since the site is interested in only one particular link 170 relation, the WebFinger resource might utilize the "rel" parameter as 171 described in Section 4.3: 173 GET /.well-known/webfinger? 174 resource=acct%3Acarol%40example.com& 175 rel=http%3A%2F%2Fopenid.net%2Fspecs%2Fconnect%2F1.0%2Fissuer 176 HTTP/1.1 177 Host: example.com 179 The server might respond like this: 181 HTTP/1.1 200 OK 182 Access-Control-Allow-Origin: * 183 Content-Type: application/jrd+json 185 { 186 "subject" : "acct:carol@example.com", 187 "links" : 188 [ 189 { 190 "rel" : "http://openid.net/specs/connect/1.0/issuer", 191 "href" : "https://openid.example.com" 192 } 193 ] 194 } 196 Since the "rel" parameter only serves to filter the link relations 197 returned by the resource, other name/value pairs in the response, 198 including any aliases or properties, would be returned. Also, since 199 support for the "rel" parameter is not guaranteed, the client must 200 not assume the "links" array will contain only the requested link 201 relation. 203 3.2. Getting Author and Copyright Information for a Web Page 205 Suppose an application would like to retrieve metadata information 206 about a web page URL, such as author and copyright information. To 207 do that, the application can utilize WebFinger to issue a query for 208 the specific URL. Suppose the URL of interest is 209 http://blog.example.com/article/id/314. The application would issue 210 a query similar to the following: 212 GET /.well-known/webfinger? 213 resource=http%3A%2F%2Fblog.example.com%2Farticle%2Fid%2F314 214 HTTP/1.1 215 Host: blog.example.com 217 The server might then reply in this way: 219 HTTP/1.1 200 OK 220 Access-Control-Allow-Origin: * 221 Content-Type: application/jrd+json 223 { 224 "subject" : "http://blog.example.com/article/id/314", 225 "aliases" : 226 [ 227 "http://blog.example.com/cool_new_thing", 228 "http://blog.example.com/steve/article/7" 229 ], 230 "properties" : 231 { 232 "http://blgx.example.net/ns/version" : "1.3", 233 "http://blgx.example.net/ns/ext" : null 234 }, 235 "links" : 236 [ 237 { 238 "rel" : "copyright", 239 "href" : "http://www.example.com/copyright" 240 }, 241 { 242 "rel" : "author", 243 "href" : "http://blog.example.com/author/steve", 244 "titles" : 245 { 246 "en-us" : "The Magical World of Steve", 247 "fr" : "Le Monde Magique de Steve" 248 }, 249 "properties" : 250 { 251 "http://example.com/role" : "editor" 252 } 253 } 255 ] 256 } 258 In the above example, we see that the server returned a list of 259 aliases, properties, and links related to the subject URL. The links 260 contain references to information for each link relation type. For 261 the author link, the server provided a reference to the author's 262 blog, along with a title for the blog in two languages. The server 263 also returned a single property related to the author, indicating the 264 author's role as editor of the blog. 266 It is worth noting that, while the server returned just two links in 267 the links array in this example, a server might return any number of 268 links when queried. 270 4. WebFinger Protocol 272 The WebFinger protocol is used to request information about an entity 273 identified by a query target (a URI). The client can optionally 274 specify one or more link relation types for which it would like to 275 receive information. 277 A WebFinger request is an HTTPS request to a WebFinger resource. A 278 WebFinger resource is a well-known URI [3] using the HTTPS scheme, 279 constructed along with the required query target and optional link 280 relation types. WebFinger resources MUST NOT be served with any 281 other URI scheme (such as HTTP). 283 A WebFinger resource is always given a query target, which is another 284 URI that identifies the entity whose information is sought. GET 285 requests to a WebFinger resource convey the query target in the 286 "resource" parameter in the WebFinger URI's query string; see Section 287 4.1 for details. 289 The host to which a WebFinger query is issued is significant. If the 290 query target contains a "host" portion (Section 3.2.2 of RFC 3986), 291 then the host to which the WebFinger query is issued MUST be the same 292 as the "host" portion of the query target, unless the client receives 293 instructions through some out-of-band mechanism to send the query to 294 another host. If the query target does not contain a "host" portion, 295 then the client chooses a host to which it directs the query using 296 additional information it has. 298 The path component of a WebFinger URI MUST be the well-known path 299 "/.well-known/webfinger". A WebFinger URI MUST contain a query 300 component that encodes the query target and optional link relation 301 types as specified in Section 4.1. 303 The WebFinger resource returns a JSON Resource Descriptor (JRD) as 304 the resource representation to convey information about an entity on 305 the Internet. Also, the Cross-Origin Resource Sharing (CORS) [7] 306 specification is utilized to facilitate queries made via a web 307 browser. 309 4.1. Constructing the Query Component of the Request URI 311 A WebFinger URI MUST contain a query component (see Section 3.4 of 312 RFC 3986). The query component MUST contain a "resource" parameter 313 and MAY contain one or more "rel" parameters. The "resource" 314 parameter MUST contain the query target (URI) and the "rel" 315 parameters MUST contain encoded link relation types according to the 316 encoding described in this section. 318 To construct the query component, the client performs the following 319 steps. First, each parameter value is percent-encoded, as per 320 Section 2.1 of RFC 3986. The encoding is done to conform to the 321 query production in Section 3.4 of that specification, with the 322 addition that any instances of the "=" and "&" characters within the 323 parameter values are also percent-encoded. Next, the client 324 constructs a string to be placed in the query component by 325 concatenating the name of the first parameter together with an equal 326 sign ("=") and the percent-encoded parameter value. For any 327 subsequent parameters, the client appends an ampersand ("&") to the 328 string, the name of the next parameter, an equal sign, and the 329 parameter value. The client MUST NOT insert any spaces while 330 constructing the string. The order in which the client places each 331 attribute-and-value pair within the query component does not matter 332 in the interpretation of the query component. 334 4.2. Performing a WebFinger Query 336 A WebFinger client issues a query using the GET method to the well- 337 known [3] resource identified by the URI whose path component is 338 "/.well-known/webfinger" and whose query component MUST include the 339 "resource" parameter exactly once and set to the value of the URI for 340 which information is being sought. 342 If the "resource" parameter is absent or malformed, the WebFinger 343 resource MUST indicate that the request is bad as per Section 10.4.1 344 of RFC 2616 [2]. 346 If the "resource" parameter is a value for which the server has no 347 information, the server MUST indicate that it was unable to match the 348 request as per Section 10.4.5 of RFC 2616. 350 A client MUST query the WebFinger resource using HTTPS only. If the 351 client determines that the resource has an invalid certificate, the 352 resource returns a 4xx or 5xx status code, or the HTTPS connection 353 cannot be established for any reason, then the client MUST accept 354 that the WebFinger query has failed and MUST NOT attempt to reissue 355 the WebFinger request using HTTP over a non-secure connection. 357 A WebFinger resource MUST return a JRD as the representation for the 358 resource if the client requests no other supported format explicitly 359 via the HTTP "Accept" header. The client MAY include the "Accept" 360 header to indicate a desired representation; representations other 361 than JRD might be defined in future specifications. The WebFinger 362 resource MUST silently ignore any requested representations that it 363 does not understand and support. The media type used for the JSON 364 Resource Descriptor (JRD) is "application/jrd+json" (see Section 365 9.2). 367 The properties, titles, and link relation types returned by the 368 server in a JRD might be varied and numerous. For example, the 369 server might return information about a person's blog, vCard [14], 370 avatar, OpenID Connect provider, RSS or ATOM feed, and so forth in a 371 reply. Likewise, if a server has no information to provide it might 372 return a JRD with an empty links array or no links array. 374 A WebFinger resource MAY redirect the client; if it does, the 375 redirection MUST only be to an "https" URI and the client MUST 376 perform certificate validation again when redirected. 378 A WebFinger resource can include cache validators in a response to 379 enable conditional requests by the client and/or expiration times as 380 per Section 13 of RFC 2616. 382 4.3. The "rel" Parameter 384 When issuing a request to a WebFinger resource, the client MAY 385 utilize the "rel" parameter to request only a subset of the 386 information that would otherwise be returned without the "rel" 387 parameter. When the "rel" parameter is used and accepted, only the 388 link relation types that match the link relation types provided via 389 the "rel" parameter are included in the array of links returned in 390 the JRD. If there are no matching link relation types defined for 391 the resource, the "links" array in the JRD will either be absent or 392 empty. All other information present in a resource descriptor 393 remains present, even when "rel" is employed. 395 The "rel" parameter MAY be included multiple times in order to 396 request multiple link relation types. 398 The purpose of the "rel" parameter is to return a subset of "link 399 relation objects" (see Section 4.4.4) that would otherwise be 400 returned in the resource descriptor. Use of the parameter might 401 reduce processing requirements on either the client or server, and it 402 might also reduce the bandwidth required to convey the partial 403 resource descriptor, especially if there are numerous link relation 404 values to convey for a given "resource" value. Note that if a client 405 requests a particular link relation type for which the server has no 406 information, the server MAY return a JRD with an empty links array or 407 no links array. 409 WebFinger resources SHOULD support the "rel" parameter. If the 410 resource does not support the "rel" parameter, it MUST ignore the 411 parameter and process the request as if no "rel" parameter values 412 were present. 414 The following example uses the "rel" parameter to request links for 415 two link relation types: 417 GET /.well-known/webfinger? 418 resource=acct%3Abob%40example.com& 419 rel=http%3A%2F%2Fwebfinger.example%2Frel%2Fprofile-page& 420 rel=http://webfinger.example/rel/businesscard HTTP/1.1 421 Host: example.com 423 In this example, the client requests the link relations of type 424 "http://webfinger.example/rel/profile-page" and 425 "http://webfinger.example/rel/businesscard". The server then 426 responds with a message like this: 428 HTTP/1.1 200 OK 429 Access-Control-Allow-Origin: * 430 Content-Type: application/jrd+json 432 { 433 "subject" : "acct:bob@example.com", 434 "aliases" : 435 [ 436 "https://www.example.com/~bob/" 437 ], 438 "properties" : 439 { 440 "http://example.com/ns/role/" : "employee" 441 }, 442 "links" : 443 [ 444 { 445 "rel" : "http://webfinger.example/rel/profile-page", 446 "href" : "https://www.example.com/~bob/" 447 }, 448 { 449 "rel" : "http://webfinger.example/rel/businesscard", 450 "href" : "https://www.example.com/~bob/bob.vcf" 451 } 452 ] 453 } 455 As you can see in the response, the resource representation contains 456 only the links of the types requested by the client and for which the 457 server had information, but the other parts of the JRD are still 458 present. Note also in the above example that the links returned in 459 the links array all use HTTPS, which is important if the data 460 indirectly obtained via WebFinger needs to returned securely. 462 4.4. The JSON Resource Descriptor (JRD) 464 The JSON Resource Descriptor (JRD), originally introduced in RFC 6415 465 [16] and based on the Extensible Resource Descriptor (XRD) format 466 [17], is a JSON object that comprises the following name/value pairs: 468 o subject 469 o aliases 470 o properties 471 o links 473 The member "subject" is a name/value pair whose value is a string, 474 "aliases" is an array of strings, "properties" is an object 475 comprising name/value pairs whose values are strings, and "links" is 476 an array of objects that contain link relation information. 478 When processing a JRD, the client MUST ignore any unknown member and 479 not treat the presence of an unknown member as an error. 481 Below, each of these members of the JRD is described in more detail. 483 4.4.1. subject 485 The value of the "subject" member is a URI that identifies the entity 486 that the JRD describes. 488 The "subject" value returned by a WebFinger resource MAY differ from 489 the value of the "resource" parameter used in the client's request. 490 This might happen, for example, when the subject's identity changes 491 (e.g., a user moves his or her account to another service) or when 492 the resource prefers to express URIs in canonical form. 494 The "subject" member SHOULD be present in the JRD. 496 4.4.2. aliases 498 The "aliases" array is an array of zero or more URI strings that 499 identify the same entity as the "subject" URI. 501 The "aliases" array is OPTIONAL in the JRD. 503 4.4.3. properties 505 The "properties" object comprises zero or more name/value pairs whose 506 names are URIs and whose values are strings or null. Properties are 507 used to convey additional information about the subject of the JRD. 508 As an example, consider this use of "properties": 510 "properties" : { "http://webfinger.example/ns/name" : "Bob Smith" } 512 The "properties" member is OPTIONAL in the JRD. 514 4.4.4. links 516 The "links" array has any number of member objects, each of which 517 represents a link [4]. Each of these link objects can have the 518 following members: 520 o rel 521 o type 522 o href 523 o titles 524 o properties 526 The "rel" and "href" members are strings representing the link's 527 relation type and the target URI, respectively. The context of the 528 link is the "subject" (see Section 4.4.1). 530 The "type" member is a string indicating what the media type of the 531 result of dereferencing the link ought to be. 533 The order of elements in the "links" array indicates an order of 534 preference. Thus, if there are two or more link relations having the 535 same "rel" value, the first link relation would indicate the user's 536 preferred link. 538 The "links" array is OPTIONAL in the JRD. 540 Below, each of the members of the objects found in the "links" array 541 is described in more detail. Each object in the "links" array, 542 referred to as a "link relation object", is completely independent 543 from any other object in the array; any requirement to include a 544 given member in the link relation object refers only to that 545 particular object. 547 4.4.4.1. rel 549 The value of the "rel" member is a string that is either a URI or a 550 registered relation type [8] (see RFC 5988 [4]). The value of the 551 "rel" member MUST contain exactly one URI or registered relation 552 type. The URI or registered relation type identifies the type of the 553 link relation. 555 The other members of the object have meaning only once the type of 556 link relation is understood. In some instances, the link relation 557 will have associated semantics enabling the client to query for other 558 resources on the Internet. In other instances, the link relation 559 will have associated semantics enabling the client to utilize the 560 other members of the link relation object without fetching additional 561 external resources. 563 URI link relation type values are compared using the "Simple String 564 Comparison" algorithm of section 6.2.1 of RFC 3986. 566 The "rel" member MUST be present in the link relation object. 568 4.4.4.2. type 570 The value of the "type" member is a string that indicates the media 571 type [9] of the target resource (see RFC 6838 [10]). 573 The "type" member is OPTIONAL in the link relation object. 575 4.4.4.3. href 577 The value of the "href" member is a string that contains a URI 578 pointing to the target resource. 580 The "href" member is OPTIONAL in the link relation object. 582 4.4.4.4. titles 584 The "titles" object comprises zero or more name/value pairs whose 585 name is a language tag [11] or the string "und". The string is 586 human-readable and describes the link relation. More than one title 587 for the link relation MAY be provided for the benefit of users who 588 utilize the link relation and, if used, a language identifier SHOULD 589 be duly used as the name. If the language is unknown or unspecified, 590 then the name is "und". 592 A JRD SHOULD NOT include more than one title identified with the same 593 language tag (or "und") within the link relation object. Meaning is 594 undefined if a link relation object includes more than one title 595 named with the same language tag (or "und"), though this MUST NOT be 596 treated as an error. A client MAY select whichever title or titles 597 it wishes to utilize. 599 Here is an example of the titles object: 601 "titles" : 602 { 603 "en-us" : "The Magical World of Steve", 604 "fr" : "Le Monde Magique de Steve" 605 } 607 The "titles" member is OPTIONAL in the link relation object. 609 4.4.4.5. properties 611 The "properties" object within the link relation object comprises 612 zero or more name/value pairs whose names are URIs and whose values 613 are strings or null. Properties are used to convey additional 614 information about the link relation. As an example, consider this 615 use of "properties": 617 "properties" : { "http://webfinger.example/mail/port" : "993" } 619 The "properties" member is OPTIONAL in the link relation object. 621 4.5. WebFinger and URIs 623 WebFinger requests include a "resource" parameter (see Section 4.1) 624 specifying the query target (URI) for which the client requests 625 information. WebFinger is neutral regarding the scheme of such a 626 URI: it could be an "acct" URI [18], an "http" or "https" URI, a 627 "mailto" URI [19], or some other scheme. 629 5. Cross-Origin Resource Sharing (CORS) 631 WebFinger resources might not be accessible from a web browser due to 632 "Same-Origin" policies. The current best practice is to make 633 resources available to browsers through Cross-Origin Resource Sharing 634 (CORS) [7], and servers MUST include the Access-Control-Allow-Origin 635 HTTP header in responses. Servers SHOULD support the least 636 restrictive setting by allowing any domain access to the WebFinger 637 resource: 639 Access-Control-Allow-Origin: * 641 There are cases where defaulting to the least restrictive setting is 642 not appropriate, for example a server on an intranet that provides 643 sensitive company information SHOULD NOT allow CORS requests from any 644 domain, as that could allow leaking of that sensitive information. A 645 server that wishes to restrict access to information from external 646 entities SHOULD use a more restrictive Access-Control-Allow-Origin 647 header. 649 6. Access Control 651 As with all web resources, access to the WebFinger resource could 652 require authentication. Further, failure to provide required 653 credentials might result in the server forbidding access or providing 654 a different response than had the client authenticated with the 655 server. 657 Likewise, a WebFinger resource MAY provide different responses to 658 different clients based on other factors, such as whether the client 659 is inside or outside a corporate network. As a concrete example, a 660 query performed on the internal corporate network might return link 661 relations to employee pictures, whereas link relations for employee 662 pictures might not be provided to external entities. 664 Further, link relations provided in a WebFinger resource 665 representation might point to web resources that impose access 666 restrictions. For example, the aforementioned corporate server may 667 provide both internal and external entities with URIs to employee 668 pictures, but further authentication might be required in order for 669 the client to access the picture resources if the request comes from 670 outside the corporate network. 672 The decisions made with respect to what set of link relations a 673 WebFinger resource provides to one client versus another and what 674 resources require further authentication, as well as the specific 675 authentication mechanisms employed, are outside the scope of this 676 document. 678 7. Hosted WebFinger Services 680 As with most services provided on the Internet, it is possible for a 681 domain owner to utilize "hosted" WebFinger services. By way of 682 example, a domain owner might control most aspects of their domain, 683 but use a third-party hosting service for email. In the case of 684 email, MX records identify mail servers for a domain. An MX record 685 points to the mail server to which mail for the domain should be 686 delivered. It does not matter to the sending mail server whether 687 those MX records point to a server in the destination domain or a 688 different domain. 690 Likewise, a domain owner might utilize the services of a third party 691 to provide WebFinger services on behalf of its users. Just as a 692 domain owner was required to insert MX records into DNS to allow for 693 hosted email serves, the domain owner is required to redirect HTTP 694 queries to its domain to allow for hosted WebFinger services. 696 When a query is issued to the WebFinger resource, the web server MUST 697 return a response with a redirection status code that includes a 698 Location header pointing to the location of the hosted WebFinger 699 service URI. This WebFinger service URI does not need to point to 700 the well-known WebFinger location on the hosting service provider 701 server. 703 As an example, assume that example.com's WebFinger services are 704 hosted by wf.example.net. Suppose a client issues a query for 705 acct:alice@example.com like this: 707 GET /.well-known/webfinger? 708 resource=acct%3Aalice%40example.com HTTP/1.1 709 Host: example.com 711 The server might respond with this: 713 HTTP/1.1 307 Temporary Redirect 714 Access-Control-Allow-Origin: * 715 Location: https://wf.example.net/example.com/webfinger? 716 resource=acct%3Aalice%40example.com 718 The client can then follow the redirection, re-issuing the request to 719 the URI provided in the Location header. Note that the server will 720 include any required URI parameters in the Location header value, 721 which could be different than the URI parameters the client 722 originally used. 724 8. Definition of WebFinger Applications 726 This specification details the protocol syntax used to query a domain 727 for information about a URI, the syntax of the JSON Resource 728 Descriptor (JRD) that is returned in response to that query, security 729 requirements and considerations, hosted WebFinger services, various 730 expected HTTP status codes, and so forth. However, this 731 specification does not enumerate the various possible properties or 732 link relation types that might be used in conjunction with WebFinger 733 for a particular application, nor does it define what properties or 734 link relation types one might expect to see in response to querying 735 for a particular URI or URI scheme. Nonetheless, all of these 736 unspecified elements are important in order to implement an 737 interoperable application that utilizes the WebFinger protocol and 738 MUST be specified in the relevant document(s) defining the particular 739 application making use of the WebFinger protocol according to the 740 procedures described in this section. 742 8.1. Specification of the URI Scheme and URI 744 Any application that uses WebFinger MUST specify the URI scheme(s) 745 and, to the extent appropriate, what forms the URI(s) might take. 746 For example, when querying for information about a user's account at 747 some domain, it might make sense to specify the use of the acct URI 748 scheme [18]. When trying to obtain the copyright information for a 749 web page, it makes sense to specify the use of the web page URI 750 (either http or https). 752 The examples in Sections 3.1 and 3.2 illustrate the use of different 753 URI schemes with WebFinger applications. In the example in Section 754 3.1, WebFinger is used to retrieve information pertinent to OpenID 755 Connect. In the example in Section 3.2, WebFinger is used to 756 discover metadata information about a web page, including author and 757 copyright information. Each of these applications of WebFinger needs 758 to be fully specified to ensure interoperability. 760 8.2. Host Resolution 762 As explained in Section 4, the host to which a WebFinger query is 763 issued is significant. In general, WebFinger applications would 764 adhere to the procedures described in Section 4 in order to properly 765 direct a WebFinger query. 767 However, some URI schemes do not have host portions and there might 768 be some applications of WebFinger for which the host portion of a URI 769 cannot or should not be utilized. In such instances, the application 770 specification MUST clearly define the host resolution procedures, 771 which might include provisioning a "default" host within the client 772 to which queries are directed. 774 8.3. Specification of Properties 776 WebFinger defines both subject-specific properties (i.e., properties 777 related to the URI that for which information is queried) and link- 778 specific properties. This section refers to subject-specific 779 properties. 781 Properties are name/value pairs whose names are URIs and whose values 782 are strings or null. Applications that utilize subject-specific 783 properties MUST define the URIs used in identifying those properties, 784 along with valid property values. 786 Consider this portion of the JRD found in the example in Section 3.2. 788 "properties" : 789 { 790 "http://blgx.example.net/ns/version" : "1.3", 791 "http://blgx.example.net/ns/ext" : null 792 } 794 Here, two properties are returned in the WebFinger response. Each of 795 these would be defined in a WebFinger application specification. 796 These two properties might be defined in the same WebFinger 797 application specification or separately in different specifications. 798 Since the latter is possible, it is important that WebFinger clients 799 not assume that one property has any specific relationship with 800 another property unless some relationship is explicitly defined in 801 the particular WebFinger application specification. 803 8.4. Specification of Links 805 The links returned in a WebFinger response are each comprised of 806 several pieces of information, some of which are optional (refer to 807 Section 4.4.4). The WebFinger application specification MUST define 808 each link and any values associated with a link, including the link 809 relation type ("rel"), the expected media type ("type"), properties, 810 and titles. 812 The target URI to which the link refers (i.e., the "href"), if 813 present, would not normally be specified in an application 814 specification. However, the URI scheme or any special 815 characteristics of the URI would usually be specified. If a 816 particular link does not require an external reference, then all of 817 the semantics related to the use of that link MUST be defined within 818 the application specification. Such links might rely only on 819 properties or titles in the link to convey meaning. 821 8.5. One URI, Multiple Applications 823 It is important to be mindful of the fact that different WebFinger 824 applications might specify the use of the same URI scheme and, in 825 effect, the same URI for different purposes. That should not be a 826 problem, since each of property identifier and link relation type 827 would be uniquely defined for a specific application. 829 It should be noted that when a client requests information about a 830 particular URI and receives a response with a number of different 831 property identifiers or link relation types that the response is 832 providing information about the URI without any particular semantics. 833 How the client interprets the information SHOULD be in accordance 834 with the particular application specification or set of 835 specifications the client implements. 837 Any syntactically valid properties or links the client receives and 838 that are not fully understood SHOULD be ignored and MUST NOT cause 839 the client to report an error. 841 8.6. Registration of Link Relation Types and Properties 843 Application specifications MAY define a simple token as a link 844 relation type for a link. In that case, the link relation type MUST 845 be registered with IANA as specified in Sections 10.3. 847 Further, any defined properties MUST be registered with IANA as 848 described in Section 10.4. 850 9. Security Considerations 852 9.1. Transport-Related Issues 854 Since this specification utilizes Cross-Origin Resource Sharing 855 (CORS) [7], all of the security considerations applicable to CORS are 856 also applicable to this specification. 858 The use of HTTPS is REQUIRED to ensure that information is not 859 modified during transit. It should be appreciated that in 860 environments where a web server is normally available, there exists 861 the possibility that a compromised network might have its WebFinger 862 resource operating on HTTPS replaced with one operating only over 863 HTTP. As such, clients MUST NOT issue queries over a non-secure 864 connection. 866 Clients MUST verify that the certificate used on an HTTPS connection 867 is valid (as defined in [12]) and accept a response only if the 868 certificate is valid. 870 9.2. User Privacy Considerations 872 Service providers and users should be aware that placing information 873 on the Internet means that any user can access that information and 874 WebFinger can be used to make it even easier to discover that 875 information. While WebFinger can be an extremely useful tool for 876 discovering one's avatar, blog, or other personal data, users should 877 understand the risks, too. 879 Systems or services that expose personal data via WebFinger MUST 880 provide an interface by which users can select which data elements 881 are exposed through the WebFinger interface. For example, social 882 networking sites might allow users to mark certain data as "public" 883 and then utilize that marking as a means of determining what 884 information to expose via WebFinger. The information published via 885 WebFinger would thus comprise only the information marked as public 886 by the user. Further, the user has the ability to remove information 887 from publication via WebFinger by removing this marking. 889 WebFinger MUST NOT be used to provide any personal data unless 890 publishing that data via WebFinger by the relevant service was 891 explicitly authorized by the person whose information is being 892 shared. Publishing one's personal data within an access-controlled 893 or otherwise limited environment on the Internet does not equate to 894 providing implicit authorization of further publication of that data 895 via WebFinger. 897 The privacy and security concerns with publishing personal data via 898 WebFinger are worth emphasizing again with respect to personal data 899 that might reveal a user's current context (e.g., the user's 900 location). The power of WebFinger comes from providing a single 901 place where others can find pointers to information about a person, 902 but service providers and users should be mindful of the nature of 903 that information shared and the fact that it might be available for 904 the entire world to see. Sharing location information, for example, 905 would potentially put a person in danger from any individual who 906 might seek to inflict harm on that person. 908 Users should be aware of how easily personal data one might publish 909 can be used in unintended ways. In one study relevant to WebFinger- 910 like services, Balduzzi et al. [20] took a large set of leaked email 911 addresses and demonstrated a number of potential privacy concerns, 912 including the ability to cross-correlate the same user's accounts 913 over multiple social networks. The authors also describe potential 914 mitigation strategies. 916 The easy access to user information via WebFinger was a design goal 917 of the protocol, not a limitation. If one wishes to limit access to 918 information available via WebFinger, such as WebFinger resources for 919 use inside a corporate network, the network administrator needs to 920 take necessary measures to limit access from outside the network. 921 Using standard methods for securing web resources, network 922 administrators do have the ability to control access to resources 923 that might return sensitive information. Further, a server can be 924 employed in such a way as to require authentication and prevent 925 disclosure of information to unauthorized entities. 927 9.3. Abuse Potential 929 Service providers should be mindful of the potential for abuse using 930 WebFinger. 932 As one example, one might query a WebFinger server only to discover 933 whether a given URI is valid or not. With such a query, the person 934 may deduce that an email identifier is valid, for example. Such an 935 approach could help spammers maintain a current list of known email 936 addresses and to discover new ones. 938 WebFinger could be used to associate a name or other personal data 939 with an email address, allowing spammers to craft more convincing 940 email messages. This might be of particular value in phishing 941 attempts. 943 It is RECOMMENDED that implementers of WebFinger server software take 944 steps to mitigate abuse, including malicious over-use of the server 945 and harvesting of user information. Although there is no mechanism 946 that can guarantee that publicly-accessible WebFinger databases won't 947 be harvested, rate-limiting by IP address will prevent or at least 948 dramatically slow harvest by private individuals without access to 949 botnets or other distributed systems. The reason these mitigation 950 strategies are not mandatory is that the correct choice of mitigation 951 strategy (if any) depends greatly on the context. Implementers 952 should not construe this as meaning that they do not need to consider 953 whether to use a mitigation strategy, and, if so, what strategy to 954 use. 956 WebFinger client developers should also be aware of potential abuse 957 by spammers or those phishing for information about users. As an 958 example, suppose a mail client was configured to automatically 959 perform a WebFinger query on the sender of each received mail 960 message. If a spammer sent an email using a unique identifier in the 961 'From' header, then when the WF query was performed the spammer would 962 be able to associate the request with a particular user's email 963 address. This would provide information to the spammer, including 964 the user's IP address, the fact the user just checked email, what 965 kind of WebFinger client the user utilized, and so on. For this 966 reason, it is strongly advised that clients not perform WebFinger 967 queries unless authorized by the user to do so. 969 9.4. Information Reliability 971 A WebFinger resource has no means of ensuring that information 972 provided by a user is accurate. Likewise, neither the resource nor 973 the client can be absolutely guaranteed that information has not been 974 manipulated either at the server or along the communication path 975 between the client and server. Use of HTTPS helps to address some 976 concerns with manipulation of information along the communication 977 path, but it clearly cannot address issues where the resource 978 provided incorrect information, either due to being provided false 979 information or due to malicious behavior on the part of the server 980 administrator. As with any information service available on the 981 Internet, users should be wary of information received from untrusted 982 sources. 984 10. IANA Considerations 986 10.1. Well-Known URI 988 This specification registers the "webfinger" well-known URI in the 989 Well-Known URI Registry as defined by [3]. 991 URI suffix: webfinger 993 Change controller: IETF 995 Specification document(s): RFC XXXX 997 Related information: The query to the WebFinger resource will 998 include one or more parameters in the query string; see Section 4.1 999 of RFCXXXX. Resources at this location are able to return a JSON 1000 Resource Descriptor (JRD) as described in Section 4.4 of RFCXXXX. 1002 [RFC EDITOR: Please replace "XXXX" references in this section and the 1003 following section with the number for this RFC.] 1005 10.2. JSON Resource Descriptor (JRD) Media Type 1007 This specification registers the media type application/jrd+json for 1008 use with WebFinger in accordance with media type registration 1009 procedures defined in [10]. 1011 Type name: application 1013 Subtype name: jrd+json 1015 Required parameters: N/A 1017 Optional parameters: N/A 1019 In particular, because RFC 4627 already defines the character 1020 encoding for JSON, no "charset" parameter is used. 1022 Encoding considerations: See RFC 6839, section 3.1. 1024 Security considerations: 1026 The JSON Resource Descriptor (JRD) is a JavaScript Object Notation 1027 (JSON) object. It is a text format that must be parsed by entities 1028 that wish to utilize the format. Depending on the language and 1029 mechanism used to parse a JSON object, it is possible for an 1030 attacker to inject behavior into a running program. Therefore, 1031 care must be taken to properly parse a received JRD to ensure that 1032 only a valid JSON object is present and that no JavaScript or other 1033 code is injected or executed unexpectedly. 1035 Interoperability considerations: 1037 This media type is a JavaScript Object Notation (JSON) object and 1038 can be consumed by any software application that can consume JSON 1039 objects. 1041 Published specification: RFC XXXX 1043 Applications that use this media type: 1045 The JSON Resource Descriptor (JRD) is used by the WebFinger 1046 protocol (RFC XXXX) to enable the exchange of information between a 1047 client and a WebFinger resource over HTTPS. 1049 Fragment identifier considerations: 1051 The syntax and semantics of fragment identifiers SHOULD be as 1052 specified for "application/json". (At publication of this 1053 document, there is no fragment identification syntax defined for 1054 "application/json".) 1056 Additional information: 1058 Deprecated alias names for this type: N/A 1060 Magic number(s): N/A 1062 File extension(s): jrd 1064 Macintosh file type code(s): N/A 1066 Person & email address to contact for further information: 1068 Paul E. Jones 1070 Intended usage: COMMON 1072 Restrictions on usage: N/A 1074 Author: Paul E. Jones 1076 Change controller: 1078 IESG has change control over this registration. 1080 Provisional registration? (standards tree only): N/A 1082 10.3. Registering Link Relation Types 1084 RFC 5988 established a Link Relation Type Registry that is re-used by 1085 WebFinger applications. 1087 Link relation types used by WebFinger applications are registered in 1088 the Link Relations Type Registry as per the procedures of Section 1089 6.2.1 of RFC 5988. The "Notes" entry for the registration SHOULD 1090 indicate if property values associated with the link relation type 1091 are registered in the WebFinger Properties registry with a link to 1092 the registry. 1094 10.4. Establishment of the WebFinger Properties Registry 1096 WebFinger utilizes URIs to identify properties of a subject or link 1097 and the associated values (see Section 8.3 and Section 8.6). This 1098 specification establishes a new "WebFinger Properties" registry to 1099 record property identifiers. 1101 10.4.1. The Registration Template 1103 The registration template for WebFinger properties is: 1105 o Property URI: 1107 o Link Type: 1109 o Description: 1111 o Reference: 1113 o Notes: [optional] 1115 The "Property URI" must be a URI that identifies the property being 1116 registered. 1118 The "Link Type" contains the name of a Link Relation Type with which 1119 this property identifier is used. If the property is a subject- 1120 specific property, then this field is specified as "N/A". 1122 The "Description" is intended to explaining the purpose of the 1123 property. 1125 The "Reference" field points to the specification that defines the 1126 registered property. 1128 The optional "Notes" field is for conveying any useful information 1129 about the property that might be of value to implementers. 1131 10.4.2. The Registration Procedures 1133 The IETF has created a mailing list, webfinger@ietf.org, which can be 1134 used for public discussion of the WebFinger protocol and any 1135 applications that use it. Prior to registration of a WebFinger 1136 property, discussion on the mailing list is strongly encouraged. The 1137 IESG has appointed Designated Experts who will monitor the 1138 webfinger@ietf.org mailing list and review registrations. 1140 A WebFinger property is registered with a Specification Required (see 1141 RFC 5226 [13]) after a two-week review period by the Designated 1142 Expert(s). However, the Designated Expert(s) may approve a 1143 registration prior to publication of a specification once the 1144 Designated Expert(s) are satisfied that such a specification will be 1145 published. In evaluating registration requests, the Designated 1146 Expert(s) should make an effort to avoid registering two different 1147 properties that have the same meaning. Where a proposed property is 1148 similar to an already-defined property, Designated Expert(s) should 1149 insist that enough text be included in the description or notes 1150 section of the template to sufficiently differentiate the new 1151 property from an existing one. 1153 The registration procedure begins when a completed registration 1154 template (as defined above) sent to webfinger@ietf.org and 1155 iana@iana.org. IANA will track the review process and communicate 1156 the results to the registrant. The WebFinger mailing list provides 1157 an opportunity for community discussion and input, and the Designated 1158 Expert(s) may use that input to inform their review. Denials should 1159 include an explanation and, if applicable, suggestions as to how to 1160 make the request successful if re-submitted. 1162 The specification registering the WebFinger property MUST include the 1163 completed registration template shown above. Once the registration 1164 procedure concludes successfully, IANA creates or modifies the 1165 corresponding record in the "WebFinger Properties" registry. 1167 11. Acknowledgments 1169 This document has benefited from extensive discussion and review of 1170 many of the members of the APPSAWG working group. The authors would 1171 like to especially acknowledge the invaluable input of Eran Hammer- 1172 Lahav, Blaine Cook, Brad Fitzpatrick, Laurent-Walter Goix, Joe 1173 Clarke, Michael B. Jones, Peter Saint-Andre, Dick Hardt, Tim Bray, 1174 James Snell, Melvin Carvalho, Evan Prodromou, Mark Nottingham, Barry 1175 Leiba, Elf Pavlik, Bjoern Hoehrmann, Subramanian Moonesamy, Joe 1176 Gregorio, John Bradley, Pete Resnick and others that we have 1177 undoubtedly, but inadvertently, missed. Special thanks go to the 1178 chairs of APPSAWG, especially Salvatore Loreto for his assistance in 1179 shepherding this document. 1181 12. References 1183 12.1. Normative References 1185 [1] Bradner, S., "Key words for use in RFCs to Indicate Requirement 1186 Levels", BCP 14, RFC 2119, March 1997. 1188 [2] Fielding, R., Gettys, J., Mogul, J., Frystyk, H., Masinter, L., 1189 Leach, P., and T. Berners-Lee, "Hypertext Transfer Protocol -- 1190 HTTP/1.1", RFC 2616, June 1999. 1192 [3] Nottingham, M., Hammer-Lahav, E., "Defining Well-Known Uniform 1193 Resource Identifiers (URIs)", RFC 5785, April 2010. 1195 [4] Nottingham, M., "Web Linking", RFC 5988, October 2010. 1197 [5] Crockford, D., "The application/json Media Type for JavaScript 1198 Object Notation (JSON)", RFC 4627, July 2006. 1200 [6] Berners-Lee, T., Fielding, R., and Masinter, L., "Uniform 1201 Resource Identifier (URI): Generic Syntax", STD 66, RFC 3986, 1202 January 2005. 1204 [7] Van Kesteren, A., "Cross-Origin Resource Sharing", W3C CORS 1205 http://www.w3.org/TR/cors/, July 2010. 1207 [8] IANA, "Link Relations", http://www.iana.org/assignments/link- 1208 relations/. 1210 [9] IANA, "MIME Media Types", 1211 http://www.iana.org/assignments/media-types/index.html. 1213 [10] Freed, N., Klensin, J., Hansen, T., "Media Type Specifications 1214 and Registration Procedures", RFC 6838, January 2013. 1216 [11] Phillips, A., Davis, M., "Tags for Identifying Languages", RFC 1217 5646, January 2009. 1219 [12] Rescorla, E., "HTTP Over TLS", RFC 2818, May 2000. 1221 [13] Narten, T. and H. Alvestrand, "Guidelines for Writing an, IANA 1222 Considerations Section in RFCs", BCP 26, RFC 5226, May 2008. 1224 12.2. Informative References 1226 [14] Perreault, S., "vCard Format Specification", RFC 6350, August 1227 2011. 1229 [15] Sakimura, N., Bradley, J., Jones, M., de Medeiros, B., 1230 Mortimore, C., and E. Jay, "OpenID Connect Messages 1.0", 1231 January 2013, http://openid.net/specs/openid-connect-messages- 1232 1_0.html. 1234 [16] Hammer-Lahav, E. and Cook, B., "Web Host Metadata", RFC 6415, 1235 October 2011. 1237 [17] Hammer-Lahav, E. and W. Norris, "Extensible Resource Descriptor 1238 (XRD) Version 1.0", http://docs.oasis- 1239 open.org/xri/xrd/v1.0/xrd-1.0.html. 1241 [18] Saint-Andre, P., "The 'acct' URI Scheme", draft-ietf-appsawg- 1242 acct-uri-06, July 2013. 1244 [19] Duerst, M., Masinter, L., and J. Zawinski, "The 'mailto' URI 1245 Scheme", RFC 6068, October 2010. 1247 [20] Balduzzi, Marco, et al., "Abusing social networks for automated 1248 user profiling", Recent Advances in Intrusion Detection, 1249 Springer Berlin Heidelberg, 2010, 1250 https://www.eurecom.fr/en/publication/3042/download/rs-publi- 1251 3042_1.pdf. 1253 Author's Addresses 1255 Paul E. Jones 1256 Cisco Systems, Inc. 1257 7025 Kit Creek Rd. 1258 Research Triangle Park, NC 27709 1259 USA 1261 Phone: +1 919 476 2048 1262 Email: paulej@packetizer.com 1263 IM: xmpp:paulej@packetizer.com 1265 Gonzalo Salgueiro 1266 Cisco Systems, Inc. 1267 7025 Kit Creek Rd. 1268 Research Triangle Park, NC 27709 1269 USA 1271 Phone: +1 919 392 3266 1272 Email: gsalguei@cisco.com 1273 IM: xmpp:gsalguei@cisco.com 1275 Joseph Smarr 1276 Google 1278 Email: jsmarr@google.com