idnits 2.17.1
draft-jones-appsawg-webfinger-04.txt:
Checking boilerplate required by RFC 5378 and the IETF Trust (see
https://trustee.ietf.org/license-info):
----------------------------------------------------------------------------
No issues found here.
Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt:
----------------------------------------------------------------------------
No issues found here.
Checking nits according to https://www.ietf.org/id-info/checklist :
----------------------------------------------------------------------------
No issues found here.
Miscellaneous warnings:
----------------------------------------------------------------------------
== The copyright year in the IETF Trust and authors Copyright Line does not
match the current year
-- The document date (May 4, 2012) is 4346 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 5988 (ref. '3') (Obsoleted by RFC 8288)
** Obsolete normative reference: RFC 4627 (ref. '4') (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. '10'
-- Possible downref: Non-RFC (?) normative reference: ref. '11'
-- Obsolete informational reference (is this intentional?): RFC 4395 (ref.
'15') (Obsoleted by RFC 7595)
Summary: 3 errors (**), 0 flaws (~~), 1 warning (==), 6 comments (--).
Run idnits with the --verbose option for more detailed information about
the items above.
--------------------------------------------------------------------------------
2 Network Working Group Paul E. Jones
3 Internet Draft Gonzalo Salgueiro
4 Intended status: Standards Track Cisco Systems
5 Expires: November 4, 2012 Joseph Smarr
6 Google
7 May 4, 2012
9 WebFinger
10 draft-jones-appsawg-webfinger-04.txt
12 Abstract
14 This specification defines the WebFinger protocol. WebFinger may be
15 used to discover information about people on the Internet, such as a
16 person's personal profile address, identity service, telephone
17 number, or preferred avatar. WebFinger may also be used to learn
18 information about objects on the network, such as the amount of toner
19 in a printer or the physical location of a server.
21 Status of this Memo
23 This Internet-Draft is submitted in full conformance with the
24 provisions of BCP 78 and BCP 79.
26 Internet-Drafts are working documents of the Internet Engineering
27 Task Force (IETF). Note that other groups may also distribute
28 working documents as Internet-Drafts. The list of current Internet-
29 Drafts is at http://datatracker.ietf.org/drafts/current/.
31 Internet-Drafts are draft documents valid for a maximum of six months
32 and may be updated, replaced, or obsoleted by other documents at any
33 time. It is inappropriate to use Internet-Drafts as reference
34 material or to cite them other than as "work in progress."
36 This Internet-Draft will expire on November 4, 2012.
38 Copyright Notice
40 Copyright (c) 2012 IETF Trust and the persons identified as the
41 document authors. All rights reserved.
43 This document is subject to BCP 78 and the IETF Trust's Legal
44 Provisions Relating to IETF Documents
45 (http://trustee.ietf.org/license-info) in effect on the date of
46 publication of this document. Please review these documents
47 carefully, as they describe your rights and restrictions with respect
48 to this document. Code Components extracted from this document must
49 include Simplified BSD License text as described in Section 4.e of
50 the Trust Legal Provisions and are provided without warranty as
51 described in the Simplified BSD License.
53 Table of Contents
55 1. Introduction...................................................2
56 2. Terminology....................................................3
57 3. Example Uses of WebFinger......................................3
58 3.1. Locating a User's Blog....................................3
59 3.2. Retrieving a Person's Contact Information.................5
60 3.3. Simplifying the Login Process.............................6
61 3.4. Retrieving Device Information.............................7
62 4. WebFinger Protocol.............................................8
63 4.1. Performing a WebFinger Query..............................8
64 4.2. The Web Host Metadata "resource" Parameter................9
65 4.3. The Web Host Metadata "rel" Parameter....................11
66 5. The "acct" URI................................................12
67 5.1. Using the "acct" URI.....................................12
68 5.2. Syntax of "acct" URI.....................................13
69 6. The "acct" Link Relation......................................13
70 6.1. Purpose for the "acct" Link Relation.....................13
71 6.2. Example Message Exchange Using the "acct" Link Relation..14
72 7. Cross-Origin Resource Sharing (CORS)..........................15
73 8. Controlling Access to Information.............................15
74 9. Security Considerations.......................................16
75 10. IANA Considerations..........................................17
76 10.1. Registration of the "acct" URI scheme name..............17
77 10.2. Registration of the "acct" Link Relation Type...........17
78 11. Acknowledgments..............................................18
79 12. References...................................................18
80 12.1. Normative References....................................18
81 12.2. Informative References..................................19
82 Author's Addresses...............................................20
84 1. Introduction
86 There is a utility found on UNIX systems called "finger" [14] that
87 allows a person to access information about another person. The
88 information being queried might be on a computer anywhere in the
89 world. The information returned via "finger" is simply a plain text
90 file that contains unstructured information provided by the queried
91 user.
93 WebFinger borrows the concept of the legacy finger protocol, but
94 introduces a very different approach to sharing information. Rather
95 than returning a simple unstructured text file, Webfinger uses
96 structured documents that contain link relations. These link
97 relations point to information a user or entity on the Internet
98 wishes to expose. For a person, the kinds of information that might
99 be exposed include a personal profile address, identity service,
100 telephone number, or preferred avatar. WebFinger may also be used to
101 learn information about objects on the network, such as the amount of
102 toner in a printer or the physical location of a server.
104 Information returned via WebFinger might be for direct human
105 consumption (e.g., another user's phone number) or it might be used
106 by systems to help carry out some operation (e.g., facilitate logging
107 into a web site by determining a user's identification service).
109 2. Terminology
111 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
112 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this
113 document are to be interpreted as described in RFC 2119 [1].
115 WebFinger makes heavy use of "Link Relations". Briefly, a Link
116 Relation is an attribute and value pair used on the Internet wherein
117 the attribute identifies the type of link to which the associated
118 value refers. In Hypertext Transfer Protocol (HTTP) [2] and Web
119 Linking [3], the attribute is a "rel" and the value is an "href".
121 3. Example Uses of WebFinger
123 In this section, we describe just a few sample uses for WebFinger and
124 show what the protocol looks like. This is not an exhaustive list of
125 possible uses and the entire section should be considered non-
126 normative. The list of potential use cases is virtually unlimited
127 since a user can share any kind of machine-consumable information via
128 WebFinger.
130 3.1. Locating a User's Blog
132 Assume you receive an email from Bob and he refers to something he
133 posted on his blog, but you do not know where Bob's blog is located.
134 It would be simple to discover the address of Bob's blog if he makes
135 that information available via WebFinger.
137 Let's assume your email client discovers that blog automatically for
138 you. After receiving the message from Bob (bob@example.com), your
139 email client performs the following steps behind the scenes.
141 First, it tries to get the host metadata [9] information for the
142 domain example.com. It does this by issuing the following HTTPS
143 query to example.com:
145 GET /.well-known/host-meta HTTP/1.1
146 Host: example.com
148 The server replies with an XRD [8] document:
150 HTTP/1.1 200 OK
151 Access-Control-Allow-Origin: *
152 Content-Type: application/xrd+xml; charset=UTF-8
154
155
156
159
161 The client then processes the received XRD in accordance with the Web
162 Host Metadata [9] procedures. The client will see the LRDD link
163 relation and issue a query with the user's account URI [5]. (The
164 Account URI is discussed in Section 4.2.) The query might look like
165 this:
167 GET /lrdd/?uri=acct%3Abob%40example.com HTTP/1.1
168 Host: example.com
170 The server might then respond with a message like this:
172 HTTP/1.1 200 OK
173 Access-Control-Allow-Origin: *
174 Content-Type: application/xrd+xml; charset=UTF-8
176
177
178 2012-03-13T20:56:11Z
179 acct:bob@example.com
180
182
184
186
188 The email client might take note of the "blog" link relation in the
189 above XRD document that refers to Bob's blog. This URL would then be
190 presented to you so that you could then visit his blog.
192 The email client might also note that Bob has published an avatar
193 link relation and use that picture to represent Bob inside the email
194 client.
196 3.2. Retrieving a Person's Contact Information
198 Assume you have Alice in your address book, but her phone number
199 appears to be invalid. You could use WebFinger to find her current
200 phone number and update your address book.
202 Let's assume you have a web-based address book that you wish to
203 update. When you instruct the address book to pull Alice's current
204 contact information, the address book might issue a query like this
205 to get host metadata information for example.com:
207 GET /.well-known/host-meta.json HTTP/1.1
208 Host: example.com
210 Note the address book is looking for a JSON [4] representation,
211 whereas we used XML in the previous example.
213 The server might reply with something like this:
215 HTTP/1.1 200 OK
216 Access-Control-Allow-Origin: *
217 Content-Type: application/json; charset=UTF-8
219 {
220 "links" :
221 [
222 {
223 "rel" : "lrdd",
224 "type" : "application/json",
225 "template" :
226 "https://example.com/lrdd/?format=json&uri={uri}"
227 }
228 ]
229 }
231 The client processes the response as described in RFC 6415 [9]. It
232 will process the LRDD link relation using Alice's account URI by
233 issuing this query:
235 GET /lrdd/?format=json&uri=acct%3Aalice%40example.com HTTP/1.1
236 Host: example.com
238 The server might return a response like this:
240 HTTP/1.1 200 OK
241 Access-Control-Allow-Origin: *
242 Content-Type: application/json; charset=UTF-8
244 {
245 "expires" : "2012-03-13T20:56:11Z",
246 "subject" : "acct:alice@example.com",
247 "links" :
248 [
249 {
250 "rel" : "http://webfinger.net/rel/avatar",
251 "href" : "http://example.com/~alice/alice.jpg"
252 },
253 {
254 "rel" : "vcard",
255 "href" : "http://example.com/~alice/alice.vcf"
256 }
257 ]
258 }
260 With this response, the address book might see the vcard [16] link
261 relation and use that file to offer you updated contact information.
263 3.3. Simplifying the Login Process
265 OpenID (http://www.openid.net) is great for allowing users to log
266 into a web site, though one criticism is that it is challenging for
267 users to remember the URI they are assigned. WebFinger can help
268 address this issue by allowing users to use user@domain-style
269 addresses. Using a user's account URI, a web site can perform a
270 query to discover the associated OpenID identifier for a user.
272 Let's assume Carol is trying to use OpenID to log into a blog. The
273 blog server might issue the following query to get the host metadata
274 information:
276 GET /.well-known/host-meta.json HTTP/1.1
277 Host: example.com
279 The response that comes back is similar to the previous example:
281 HTTP/1.1 200 OK
282 Access-Control-Allow-Origin: *
283 Content-Type: application/json; charset=UTF-8
284 {
285 "expires" : "2012-03-13T20:56:11Z",
286 "links" :
287 [
288 {
289 "rel" : "lrdd",
290 "type" : "application/json",
291 "template" :
292 "https://example.com/lrdd/?format=json&uri={uri}"
293 }
295 ]
296 }
298 The blog server processes the response as described in RFC 6415. It
299 will process the LRDD link relation using Carol's account URI by
300 issuing this query:
302 GET /lrdd/?format=json&uri=acct%3Acarol%40example.com HTTP/1.1
304 The server might return a response like this:
306 HTTP/1.1 200 OK
307 Access-Control-Allow-Origin: *
308 Content-Type: application/json; charset=UTF-8
310 {
311 "subject" : "acct:carol@example.com",
312 "links" :
313 [
314 {
315 "rel" : "http://webfinger.net/rel/avatar",
316 "href" : "http://example.com/~alice/alice.jpg"
317 },
318 {
319 "rel" : "http://specs.openid.net/auth/2.0/provider",
320 "href" : "https://openid.example.com/carol"
321 }
322 ]
323 }
325 At this point, the blog server knows that Carol's OpenID identifier
326 is https://openid.example.com/carol and could then proceed with the
327 login process as usual.
329 3.4. Retrieving Device Information
331 While the examples thus far have been focused on information about
332 humans, WebFinger does not limit queries to only those that use the
333 account URI scheme. Any URI scheme that contains domain information
334 MAY be used with WebFinger. Let's suppose there are devices on the
335 network like printers and you would like to check the current toner
336 level for a particular printer identified via the URI like
337 device:p1.example.com. While the "device" URI scheme is not
338 presently specified, we use it here for illustrative purposes.
340 Following the procedures similar to those above, a query may be
341 issued to get link relations specific to this URI like this:
343 GET /lrdd/?format=json&uri=device%3Ap1.example.com HTTP/1.1
344 Host: example.com
346 The link relations that are returned may be quite different than
347 those for human users. Perhaps we may see a response like this:
349 HTTP/1.1 200 OK
350 Access-Control-Allow-Origin: *
351 Content-Type: application/json; charset=UTF-8
353 {
354 "subject" : "device:p1.example.com",
355 "links" :
356 [
357 {
358 "rel" : "tipsi",
359 "href" : "http://192.168.1.5/npap/"
360 }
361 ]
362 }
364 While this example is entirely fictitious, you can imagine that
365 perhaps the Transport Independent, Printer/System Interface [18] may
366 be enhanced with a web interface that allows a device that
367 understands the TIP/SI web interface specification to query the
368 printer for toner levels.
370 4. WebFinger Protocol
372 WebFinger does not actually introduce a new protocol, per se.
373 Rather, it builds upon the existing Web Host Metadata [9]
374 specification and leverages the Cross-Origin Resource Sharing (CORS)
375 [7] specification.
377 4.1. Performing a WebFinger Query
379 The first step a client must perform in executing a WebFinger query
380 is to query for the host metadata using HTTPS or HTTP. The
381 procedures are defined in the Web Host Metadata [9] specification.
383 WebFinger clients MUST locate the LRDD link relation, if present, and
384 perform a query for that link relation, if present. All other link
385 templates found must be processed to form a complete resource
386 descriptor. The processing rules in Section 4.2 of RFC 6415 MUST be
387 followed.
389 WebFinger servers MUST accept requests for both XRD [8] and JRD [9]
390 documents. The default representation returned by the server MUST be
391 an XRD document, but a JRD document MUST be returned if the client
392 explicitly requests it by using /.well-known/host-meta.json or
393 includes an Accept header in the HTTP request with a type of
394 "application/json" [4].
396 If the client requests a JRD document when querying for host
397 metadata, the WebFinger server can assume that the client will want a
398 JRD documents when querying the LRDD resource. As such, when the
399 WebFinger server returns a JRD document containing host metadata it
400 should include a URI for an LRDD resource that can return a JRD
401 document and MAY include a URI for an LRDD resource that will return
402 an XRD document.
404 If the client queries the LRDD resource and provides a URI for which
405 the server has no information, the server MUST return a 404 status
406 code. Likewise, any query to a URI in the resource descriptor that
407 is unknown to the server MUST result in the server returning a 404
408 status code.
410 WebFinger servers MAY include cache validators in a response to
411 enable conditional requests by clients and/or expiration times as per
412 RFC 2616 section 13.
414 4.2. The Web Host Metadata "resource" Parameter
416 In addition to the normal processing logic for processing host
417 metadata information, WebFinger defines the "resource" parameter for
418 querying for host metadata and returning all of the link relations
419 from LRDD and other resource-specific link templates in a single
420 query. This resource essentially pushes the work to the server to
421 form a complete resource descriptor for the specified resource.
423 WebFinger servers compliant with this specification MUST support for
424 the "resource" parameter as a means of improving performance and
425 reducing client complexity. Note that an RFC 6415-compliant server
426 might not implement the "resource" parameter, though the server would
427 respond to queries from the client as described in RFC 6415. Thus,
428 WebFinger clients need to check the server response to ensure that
429 the "resource" parameter is supported as explained below.
431 To utilize the host-meta "resource" parameter, a WebFinger client
432 issues a request to /.well-known/host-meta or /.well-known/host-
433 meta.json as usual, but then appends a "resource" parameter as shown
434 in this example:
436 GET /.well-known/host-meta.json?resource=\
437 acct%3Abob%40example.com HTTP/1.1
438 Host: example.com
440 Note that the "\" character shown above is to indicate that the line
441 breaks at this point and continues on the next line. This was shown
442 only to avoid line wrapping in this document and is not a part of the
443 HTTP protocol.
445 When processing this request, the WebFinger server MUST
447 * Return a 404 status code if the URI provided in the resource
448 parameter is unknown to the server; and
450 * Set the "Subject" returned in the response to the value of the
451 "resource" parameter if the URI provided in the resource
452 parameter is known to the server
454 The WebFinger client can verify support for the "resource" parameter
455 by checking the value of the Subject returned in the response. If
456 the Subject matches the value of the "resource" parameter, then the
457 "resource" parameter is supported by the server.
459 For illustrative purposes, the following is an example usage of the
460 "resource" parameter that aligns with the example in Section 1.1.1 of
461 RFC 6415. The WebFinger client would issue this request:
463 GET /.well-known/host-meta.json?resource=\
464 http%3A%2F%2Fexample.com%2Fxy HTTP/1.1
465 Host: example.com
467 The WebFinger server would reply with this response:
469 HTTP/1.1 200 OK
470 Access-Control-Allow-Origin: *
471 Content-Type: application/json; charset=UTF-8
473 {
474 "subject" : "http://example.com/xy",
475 "properties" :
476 {
477 "http://spec.example.net/color" : "red"
478 },
479 "links" :
480 [
481 {
482 "rel" : "hub",
483 "href" : "http://example.com/hub"
484 },
485 {
486 "rel" : "hub",
487 "href" : "http://example.com/another/hub"
488 },
489 {
490 "rel" : "author",
491 "href" : "http://example.com/john"
492 },
493 {
494 "rel" : "author",
495 "template" : "http://example.com/author?\
496 q=http%3A%2F%2Fexample.com%2Fxy"
497 }
498 ]
499 }
501 4.3. The Web Host Metadata "rel" Parameter
503 WebFinger also defines the "rel" parameter for use when querying for
504 host metadata. It is used to return a subset of the information that
505 would otherwise be returned without the "rel" parameter. When the
506 "rel" parameter is used, only the link relations that match the
507 space-separated list of link relations provided via "rel" are
508 included in the list of links returned in the resource descriptor.
509 All other information normally present in a resource descriptor is
510 present in the resource descriptor, even when "rel" is employed.
512 The purpose of the "rel" parameter is to return a subset of
513 resource's link relations. It is not intended to reduce the work
514 required of a server to produce a response. That said, use of the
515 parameter might reduce processing requirements on either the client
516 or server, and it might also reduce the bandwidth required to convey
517 the partial resource descriptor, especially if there are numerous
518 link relation values to convey for a given resource.
520 Support for the "rel" parameter is OPTIONAL, but support is
521 RECOMMENDED for both the host-meta resource and the LRDD resource.
523 For illustrative purposes, the following is an example usage of the
524 "rel" parameter that aligns with the example in Section 1.1.1 of RFC
525 6415. The WebFinger client would issue this request to receive links
526 that are of the type "hub" and "copyright":
528 GET /.well-known/host-meta.json?resource=\
529 http%3A%2F%2Fexample.com%2Fxy&rel=hub%20copyright HTTP/1.1
530 Host: example.com
532 The WebFinger server would reply with this response:
534 HTTP/1.1 200 OK
535 Access-Control-Allow-Origin: *
536 Content-Type: application/json; charset=UTF-8
537 {
538 "subject" : "http://example.com/xy",
539 "properties" :
540 {
541 "http://spec.example.net/color" : "red"
542 },
543 "links" :
544 [
545 {
546 "rel" : "hub",
547 "href" : "http://example.com/hub"
548 },
549 {
550 "rel" : "hub",
551 "href" : "http://example.com/another/hub"
552 }
553 ]
554 }
556 Note that in this example, the "author" links are removed, though all
557 other content is present. Since there were no "copyright" links,
558 none are returned.
560 In the event that a client requests links for link relations that are
561 not defined for the specified resource, a resource descriptor MUST be
562 returned, void of any links. When a JRD is returned, the "links"
563 array MAY be either absent or empty. The server MUST NOT return a
564 404 status code when a particular link relation specified via "rel"
565 is not defined for the resource, as a 404 status code is reserved for
566 indicating that the resource itself (e.g., as indicated via the
567 "resource" parameter) does not exist.
569 5. The "acct" URI
571 The Web Host Metadata specification [9] allows for any kind of
572 resource to be queried, as does WebFinger. However, a specific type
573 of resource is needed in order to query information about a human
574 user.
576 WebFinger uses the "acct" URI to refer to a human user's account on
577 the Internet. While other URI scheme MAY be used to query for
578 information related to a human user, other schemes are not explicitly
579 defined for that purpose.
581 5.1. Using the "acct" URI
583 The "acct" URI takes a familiar form in looking like an email
584 address. However, the account URI is not an email address and should
585 not be mistaken for one. Quite often, the account URI minus the
586 "acct:" scheme prefix may be exactly the same as the user's email
587 address.
589 A user MUST NOT be required to enter the "acct" URI scheme name along
590 with his account identifier into any WebFinger client. Rather, the
591 WebFinger client MUST accept identifiers that are void of the "acct:"
592 portion of the identifier. Composing a properly formatted "acct" URI
593 is the responsibility of the WebFinger client.
595 A user MAY provide a fully-specified "acct" URI.
597 5.2. Syntax of "acct" URI
599 The "acct" URI syntax is defined here in Augmented Backus-Naur Form
600 (ABNF) [6] and borrows syntax elements from RFC 3986 [5]:
602 acctURI = "acct:" userpart "@" domainpart
603 userpart = 1*( unreserved / pct-encoded )
604 domainpart = domainlabel 1*( "." domainlabel)
605 domainlabel = alphanum / alphanum *( alphanum / "-" ) alphanum
606 alphanum = ALPHA / DIGIT
608 The "acct" URI scheme allows any character from the Unicode [11]
609 character set encoded as a UTF-8 [19] string that is then percent-
610 encoded as necessary into valid ASCII [20]. Characters in the
611 domainpart must be encoded to support internationalized domain names
612 (IDNs) [12].
614 Characters in the userpart or domainpart that are not unreserved must
615 be percent-encoded when used in a protocol or document that only
616 supports or requires ASCII. When carried in a document (e.g., XRD or
617 JRD) or protocol that supports the Unicode character set (e.g., UTF-8
618 or UTF-16 [21]), the URI strings may appear in the protocol or
619 document's native encoding without percent-encoding. Such usage of a
620 URI is commonly referred to as an Internationalized Resource
621 Identifier (IRI). Conversion between an IRI and URI is described in
622 Section 3 of RFC 3987 [13].
624 6. The "acct" Link Relation
626 6.1. Purpose for the "acct" Link Relation
628 Users of some services might have an "acct" URI that looks
629 significantly different from his or her email address, perhaps using
630 an entirely different domain name. It is also possible for a user
631 have multiple accounts that a user wants to advertise and that a
632 WebFinger client may want to query. To address both of these needs,
633 this specification defines the "acct" link relation.
635 Since an account may make a reference to one or more different
636 accounts, WebFinger clients MUST take steps to avoid loops wherein
637 two accounts, directly or indirectly, refer the client to each other.
639 There are no limits on the number of "acct" link relations that might
640 be returned in a WebFinger query.
642 An "acct" link relation used within the context of a WebFinger query
643 for a user's account MUST NOT return "acct" link relations for
644 another individual.
646 The "acct" link relation also makes it possible to use the link
647 relation in HTML documents or in HTTP headers as described in the Web
648 Linking specification [3]. This would allow, by way of example, for
649 a user to advertise his or her account identifier in a blog, article,
650 or other content located on a server that is unrelated to his user
651 account. Since there may be multiple contributors to an article,
652 there may be more than one "acct" link relation in an HTML document
653 or in HTTP headers. It is RECOMMENDED that no more than one "acct"
654 link relation is advertised per author of a given web page, as a
655 client may otherwise not understand that the multiple link relations
656 are for the same person; references to other accounts should be done
657 from within a user's account, as described in the preceding
658 paragraphs.
660 6.2. Example Message Exchange Using the "acct" Link Relation
662 Consider the following non-normative example.
664 Suppose Alice receives an email from bob@example.net. While Bob's
665 email identifier might be in the example.net domain, he holds his
666 account with an "acct" URI in the example.com domain. His email
667 provider may provide WebFinger services to enable redirecting Alice
668 when she queries for acct:bob@example.net.
670 Suppose Alice's client issues the following request:
672 GET /.well-known/host-meta.json?resource=\
673 acct%3Abob%40example.net HTTP/1.1
674 Host: example.net
676 The response that Alice's client receives back might be:
678 HTTP/1.1 200 OK
679 Access-Control-Allow-Origin: *
680 Content-Type: application/json; charset=UTF-8
682 {
683 "subject" : "acct:bob@example.net",
684 "links" :
685 [
686 {
687 "rel" : "acct",
688 "href" : "acct:bob@example.com"
689 },
690 {
691 "rel" : "acct",
692 "href" : "acct:bob@example.org"
693 }
694 ]
695 }
697 Alice's WebFinger client could then perform queries against the URIs
698 acct:bob@example.com and acct:bob@example.org in order to get the
699 information Alice is seeking.
701 7. Cross-Origin Resource Sharing (CORS)
703 WebFinger is most useful when it is accessible without restrictions
704 on the Internet, and that includes web browsers. Therefore,
705 WebFinger servers MUST support Cross-Origin Resource Sharing (CORS)
706 [7]. Specifically, all queries to /.well-known/host-meta, /.well-
707 known/host-meta.json, and to the LRDD URI must include the following
708 HTTP header in the response:
710 Access-Control-Allow-Origin: *
712 8. Controlling Access to Information
714 As with all web resources, access to the Host Metadata resource and
715 the LRDD resource MAY require authentication. Further, failure to
716 provide required credentials MAY result in the server forbidding
717 access or providing a different response than had the client
718 authenticated with the server.
720 Likewise, a server MAY provide different responses to different
721 clients based on other factors, such as whether the client is inside
722 or outside a corporate network. As a concrete example, a query
723 performed on the internal corporate network might return link
724 relations to employee pictures whereas link relations for employee
725 pictures might not be provided to external entities.
727 Further, link relations provided in a WebFinger server response MAY
728 point to web resources that impose access restrictions. For example,
729 it is possible that the aforementioned corporate server may provide
730 both internal and external entities with URIs to employee pictures,
731 but further authentication MAY be required in order for the WebFinger
732 client to access those resources if the request comes from outside
733 the corporate network.
735 The decisions made with respect to what set of link relations a
736 WebFinger server provides to one client versus another and what
737 resources require further authentication, as well as the specific
738 authentication mechanisms employed, are outside the scope of this
739 document.
741 9. Security Considerations
743 All of the security considerations applicable to Web Host Metadata
744 [9] and Cross-Origin Resource Sharing [7] are also applicable to this
745 specification. Of particular importance is the recommended use of
746 HTTPS to ensure that information is not modified during transit.
747 Clients should verify that the certificate used on an HTTPS
748 connection is valid.
750 When using HTTP to request an XRD document, WebFinger clients SHOULD
751 verify the XRD document's signature, if present, to ensure that the
752 XRD document has not been modified. WebFinger servers SHOULD include
753 a signature for XRD documents.
755 Service providers and users should be aware that placing information
756 on the Internet accessible through WebFinger means that any user can
757 access that information. While WebFinger can be an extremely useful
758 tool for allowing quick and easy access to one's avatar, blog, or
759 other personal information, users should understand the risks, too.
760 If one does not wish to share certain information with the world, do
761 not allow that information to be freely accessible through WebFinger.
763 The aforementioned word of caution is perhaps worth emphasizing again
764 with respect to dynamic information one might wish to share, such as
765 the current location of a user. WebFinger can be a powerful tool
766 used to assemble information about a person all in one place, but
767 service providers and users should be mindful of the nature of that
768 information shared and the fact that it might be available for the
769 entire world to see. Sharing location information, for example,
770 would potentially put a person in danger from any individual who
771 might seek to inflict harm on that person.
773 The easy access to user information via WebFinger was a design goal
774 of the protocol, not a limitation. If one wishes to limit access to
775 information available via WebFinger, such as a WebFinger server for
776 use inside a corporate network, the network administrator must take
777 measures necessary to limit access from outside the network. Using
778 standard methods for securing web resources, network administrators
779 do have the ability to control access to resources that might return
780 sensitive information. Further, WebFinger servers can be employed in
781 such a way as to require authentication and prevent disclosure of
782 information to unauthorized entities.
784 10. IANA Considerations
786 RFC Editor: Please replace QQQQ in the following two sub-sections
787 with a reference to this RFC.
789 10.1. Registration of the "acct" URI scheme name
791 This specification requests IANA to register the "acct" URI scheme in
792 the "Permanent URI Schemes" sub-registry in the "Uniform Resource
793 Identifier (URI) Schemes" IANA registry [17]. This registration
794 follows the URI Scheme Registration Template detailed in Section 5.4
795 of RFC 4395 [15].
797 URI scheme name: acct
799 Status: Permanent
801 URI scheme syntax: see Section 4.1 of RFC QQQQ
803 URI scheme semantics: see Section 4.1 of RFC QQQQ
805 Encoding considerations: The "acct" URI scheme allows any character
806 from the Unicode character set encoded as a UTF-8 string that is
807 then percent-encoded as necessary to result in an internal
808 representation in US-ASCII [10]
810 Applications/protocols that use this URI scheme name: WebFinger
812 Security considerations: see Section 7 of RFC QQQQ
814 Contact: Gonzalo Salgueiro
816 Author/Change controller: IETF
818 References: See Section 10 of RFC QQQQ
820 10.2. Registration of the "acct" Link Relation Type
822 Relation Name: acct
824 Description: A link relation that refers to a user's WebFinger
825 account identifier.
827 Reference: RFC QQQQ
829 Notes:
831 Application Data:
833 11. Acknowledgments
835 The authors would like to acknowledge Eran Hammer-Lahav, Blaine Cook,
836 Brad Fitzpatrick, Laurent-Walter Goix, and Joe Clarke for their
837 invaluable input.
839 12. References
841 12.1. Normative References
843 [1] Bradner, S., "Key words for use in RFCs to Indicate Requirement
844 Levels", BCP 14, RFC 2119, March 1997.
846 [2] Fielding, R., Gettys, J., Mogul, J., Frystyk, H.,
847 Masinter, L., Leach, P., and T. Berners-Lee, "Hypertext
848 Transfer Protocol -- HTTP/1.1", RFC 2616, June 1999.
850 [3] Nottingham, M., "Web Linking", RFC 5988, October 2010.
852 [4] Crockford, D., "The application/json Media Type for
853 JavaScript Object Notation (JSON)", RFC 4627, July 2006.
855 [5] Berners-Lee, T., Fielding, R., and Masinter, L., "Uniform
856 Resource Identifier (URI): Generic Syntax", STD 66, RFC 3986,
857 January 2005.
859 [6] Crocker, D. and P. Overell, "Augmented BNF for Syntax
860 Specifications: ABNF", STD 68, RFC 5234, January 2008.
862 [7] Van Kesteren, A., "Cross-Origin Resource Sharing", W3C CORS
863 http://www.w3.org/TR/cors/, July 2010.
865 [8] Hammer-Lahav, E. and W. Norris, "Extensible Resource Descriptor
866 (XRD) Version 1.0", http://docs.oasis-
867 open.org/xri/xrd/v1.0/xrd-1.0.html.
869 [9] Hammer-Lahav, E. and Cook, B., "Web Host Metadata", RFC 6415,
870 October 2011.
872 [10] American National Standards Institute, "Coded Character Set -
873 7-bit American Standard Code for Information Interchange", ANSI
874 X3.4, 1986.
876 [11] The Unicode Consortium. The Unicode Standard, Version 6.1.0,
877 (Mountain View, CA: The Unicode Consortium, 2012. ISBN 978-1-
878 936213-02-3) http://www.unicode.org/versions/Unicode6.1.0/.
880 [12] Klensin, J., "Internationalized Domain Names in Applications
881 (IDNA): Protocol", RFC 5891, August 2010.
883 [13] Duerst, M., "Internationalized Resource Identifiers (IRIs)",
884 RFC 3987, January 2005.
886 12.2. Informative References
888 [14] Zimmerman, D., "The Finger User Information Protocol", RFC
889 1288, December 1991.
891 [15] Hansen, T., Hardie, T., and L. Masinter, "Guidelines and
892 Registration Procedures for New URI Schemes", BCP 35, RFC 4395,
893 February 2006.
895 [16] Perreault, S., "vCard Format Specification", RFC 6350, August
896 2011.
898 [17] Internet Assigned Numbers Authority (IANA) Registry, "Uniform
899 Resource Identifier (URI) Schemes",
900 .
902 [18] "Transport Independent, Printer/System Interface", IEEE Std
903 1284.1-1997, 1997.
905 [19] Yergeau, F., "UTF-8, a transformation format of ISO 10646", RFC
906 3629, November 2003.
908 [20] Information Systems -- Coded Character Sets 7-Bit American
909 National Standard Code for Information Interchange (7-Bit
910 ASCII), ANSI X3.4-1986, December 30, 1986.
912 [21] Hoffman, P., Yergeau, F., "UTF-16, an encoding of ISO 10646",
913 RFC 2781, February 2000.
915 Author's Addresses
917 Paul E. Jones
918 Cisco Systems, Inc.
919 7025 Kit Creek Rd.
920 Research Triangle Park, NC 27709
921 USA
923 Phone: +1 919 476 2048
924 Email: paulej@packetizer.com
925 IM: xmpp:paulej@packetizer.com
927 Gonzalo Salgueiro
928 Cisco Systems, Inc.
929 7025 Kit Creek Rd.
930 Research Triangle Park, NC 27709
931 USA
933 Phone: +1 919 392 3266
934 Email: gsalguei@cisco.com
935 IM: xmpp:gsalguei@cisco.com
937 Joseph Smarr
938 Google
940 Email: jsmarr@google.com
942 Change Log (To Be Deleted Before Publication)
943 =============================================
945 -04 Draft
947 * Added text that makes the "resource" parameter required
949 * Added a new section 8 that discusses controlling access to information
951 * Added a little more to the security considerations section to briefly
952 cover what was more fully explained in the new section 8
954 -03 Draft
956 * Changed the name from Webfinger to WebFinger (common usage)
958 * Added a new paragraph to Section 4.1 to remind readers that WebFinger
959 benefits from all of the existing HTTP caching functionality
961 * Added the "rel" parameter to allow filtering the results of a
962 WebFinger query to include Links of the specified type(s)
964 * Corrected a reference to an obsoleted RFC
966 * Removed extraneous text from the terminology section
968 -02 Draft
970 * Minor editorial changes
972 * Added to the XML example to highlight that this element
973 exists, since some may not be aware
975 * Changed some of the link relation values, particularly for those that
976 are not yet standardized
978 * Added a note about "device:" not being standard
980 * Overhauled the "acct" link relation text, breaking the normative and
981 non-normative pieces apart
983 * Added additional text to the security considerations section related
984 to dynamic information (e.g., geographic information)