idnits 2.17.1
draft-jones-appsawg-webfinger-03.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 (April 9, 2012) is 4398 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: October 9, 2012 Joseph Smarr
6 Google
7 April 9, 2012
9 WebFinger
10 draft-jones-appsawg-webfinger-03.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 October 9, 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. Security Considerations.......................................15
74 9. IANA Considerations...........................................16
75 9.1. Registration of the "acct" URI scheme name...............16
76 9.2. Registration of the "acct" Link Relation Type............16
77 10. Acknowledgments..............................................17
78 11. References...................................................17
79 11.1. Normative References....................................17
80 11.2. Informative References..................................18
81 Author's Addresses...............................................19
83 1. Introduction
85 There is a utility found on UNIX systems called "finger" [14] that
86 allows a person to access information about another person. The
87 information being queried might be on a computer anywhere in the
88 world. The information returned via "finger" is simply a plain text
89 file that contains unstructured information provided by the queried
90 user.
92 WebFinger borrows the concept of the legacy finger protocol, but
93 introduces a very different approach to sharing information. Rather
94 than returning a simple unstructured text file, Webfinger uses
95 structured documents that contain link relations. These link
96 relations point to information a user or entity on the Internet
97 wishes to expose. For a person, the kinds of information that might
98 be exposed include a personal profile address, identity service,
99 telephone number, or preferred avatar. WebFinger may also be used to
100 learn information about objects on the network, such as the amount of
101 toner in a printer or the physical location of a server.
103 Information returned via WebFinger might be for direct human
104 consumption (e.g., another user's phone number) or it might be used
105 by systems to help carry out some operation (e.g., facilitate logging
106 into a web site by determining a user's identification service).
108 2. Terminology
110 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
111 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this
112 document are to be interpreted as described in RFC 2119 [1].
114 WebFinger makes heavy use of "Link Relations". Briefly, a Link
115 Relation is an attribute and value pair used on the Internet wherein
116 the attribute identifies the type of link to which the associated
117 value refers. In Hypertext Transfer Protocol (HTTP) [2] and Web
118 Linking [3], the attribute is a "rel" and the value is an "href".
120 3. Example Uses of WebFinger
122 In this section, we describe just a few sample uses for WebFinger and
123 show what the protocol looks like. This is not an exhaustive list of
124 possible uses and the entire section should be considered non-
125 normative. The list of potential use cases is virtually unlimited
126 since a user can share any kind of machine-consumable information via
127 WebFinger.
129 3.1. Locating a User's Blog
131 Assume you receive an email from Bob and he refers to something he
132 posted on his blog, but you do not know where Bob's blog is located.
133 It would be simple to discover the address of Bob's blog if he makes
134 that information available via WebFinger.
136 Let's assume your email client discovers that blog automatically for
137 you. After receiving the message from Bob (bob@example.com), your
138 email client performs the following steps behind the scenes.
140 First, it tries to get the host metadata [9] information for the
141 domain example.com. It does this by issuing the following HTTPS
142 query to example.com:
144 GET /.well-known/host-meta HTTP/1.1
145 Host: example.com
147 The server replies with an XRD [8] document:
149 HTTP/1.1 200 OK
150 Access-Control-Allow-Origin: *
151 Content-Type: application/xrd+xml; charset=UTF-8
153
154
155
158
160 The client then processes the received XRD in accordance with the Web
161 Host Metadata [9] procedures. The client will see the LRDD link
162 relation and issue a query with the user's account URI [5]. (The
163 Account URI is discussed in Section 4.2.) The query might look like
164 this:
166 GET /lrdd/?uri=acct%3Abob%40example.com HTTP/1.1
167 Host: example.com
169 The server might then respond with a message like this:
171 HTTP/1.1 200 OK
172 Access-Control-Allow-Origin: *
173 Content-Type: application/xrd+xml; charset=UTF-8
175
176
177 2012-03-13T20:56:11Z
178 acct:bob@example.com
179
181
183
185
187 The email client might take note of the "blog" link relation in the
188 above XRD document that refers to Bob's blog. This URL would then be
189 presented to you so that you could then visit his blog.
191 The email client might also note that Bob has published an avatar
192 link relation and use that picture to represent Bob inside the email
193 client.
195 3.2. Retrieving a Person's Contact Information
197 Assume you have Alice in your address book, but her phone number
198 appears to be invalid. You could use WebFinger to find her current
199 phone number and update your address book.
201 Let's assume you have a web-based address book that you wish to
202 update. When you instruct the address book to pull Alice's current
203 contact information, the address book might issue a query like this
204 to get host metadata information for example.com:
206 GET /.well-known/host-meta.json HTTP/1.1
207 Host: example.com
209 Note the address book is looking for a JSON [4] representation,
210 whereas we used XML in the previous example.
212 The server might reply with something like this:
214 HTTP/1.1 200 OK
215 Access-Control-Allow-Origin: *
216 Content-Type: application/json; charset=UTF-8
218 {
219 "links" :
220 [
221 {
222 "rel" : "lrdd",
223 "type" : "application/json",
224 "template" :
225 "https://example.com/lrdd/?format=json&uri={uri}"
226 }
227 ]
228 }
230 The client processes the response as described in RFC 6415 [9]. It
231 will process the LRDD link relation using Alice's account URI by
232 issuing this query:
234 GET /lrdd/?format=json&uri=acct%3Aalice%40example.com HTTP/1.1
235 Host: example.com
237 The server might return a response like this:
239 HTTP/1.1 200 OK
240 Access-Control-Allow-Origin: *
241 Content-Type: application/json; charset=UTF-8
243 {
244 "expires" : "2012-03-13T20:56:11Z",
245 "subject" : "acct:alice@example.com",
246 "links" :
247 [
248 {
249 "rel" : "http://webfinger.net/rel/avatar",
250 "href" : "http://example.com/~alice/alice.jpg"
251 },
252 {
253 "rel" : "vcard",
254 "href" : "http://example.com/~alice/alice.vcf"
255 }
256 ]
257 }
259 With this response, the address book might see the vcard [16] link
260 relation and use that file to offer you updated contact information.
262 3.3. Simplifying the Login Process
264 OpenID (http://www.openid.net) is great for allowing users to log
265 into a web site, though one criticism is that it is challenging for
266 users to remember the URI they are assigned. WebFinger can help
267 address this issue by allowing users to use user@domain-style
268 addresses. Using a user's account URI, a web site can perform a
269 query to discover the associated OpenID identifier for a user.
271 Let's assume Carol is trying to use OpenID to log into a blog. The
272 blog server might issue the following query to get the host metadata
273 information:
275 GET /.well-known/host-meta.json HTTP/1.1
276 Host: example.com
278 The response that comes back is similar to the previous example:
280 HTTP/1.1 200 OK
281 Access-Control-Allow-Origin: *
282 Content-Type: application/json; charset=UTF-8
283 {
284 "expires" : "2012-03-13T20:56:11Z",
285 "links" :
286 [
287 {
288 "rel" : "lrdd",
289 "type" : "application/json",
290 "template" :
291 "https://example.com/lrdd/?format=json&uri={uri}"
292 }
294 ]
295 }
297 The blog server processes the response as described in RFC 6415. It
298 will process the LRDD link relation using Carol's account URI by
299 issuing this query:
301 GET /lrdd/?format=json&uri=acct%3Acarol%40example.com HTTP/1.1
303 The server might return a response like this:
305 HTTP/1.1 200 OK
306 Access-Control-Allow-Origin: *
307 Content-Type: application/json; charset=UTF-8
309 {
310 "subject" : "acct:carol@example.com",
311 "links" :
312 [
313 {
314 "rel" : "http://webfinger.net/rel/avatar",
315 "href" : "http://example.com/~alice/alice.jpg"
316 },
317 {
318 "rel" : "http://specs.openid.net/auth/2.0/provider",
319 "href" : "https://openid.example.com/carol"
320 }
321 ]
322 }
324 At this point, the blog server knows that Carol's OpenID identifier
325 is https://openid.example.com/carol and could then proceed with the
326 login process as usual.
328 3.4. Retrieving Device Information
330 While the examples thus far have been focused on information about
331 humans, WebFinger does not limit queries to only those that use the
332 account URI scheme. Let's suppose there are devices on the network
333 like printers and you would like to check the current toner level for
334 a particular printer identified via the URI like
335 device:p1.example.com. While the "device" URI scheme is not
336 presently specified, we use it here for illustrative purposes.
338 Following the procedures similar to those above, a query may be
339 issued to get link relations specific to this URI like this:
341 GET /lrdd/?format=json&uri=device%3Ap1.example.com HTTP/1.1
342 Host: example.com
344 The link relations that are returned may be quite different than
345 those for human users. Perhaps we may see a response like this:
347 HTTP/1.1 200 OK
348 Access-Control-Allow-Origin: *
349 Content-Type: application/json; charset=UTF-8
351 {
352 "subject" : "device:p1.example.com",
353 "links" :
354 [
355 {
356 "rel" : "tipsi",
357 "href" : "http://192.168.1.5/npap/"
358 }
359 ]
360 }
362 While this example is entirely fictitious, you can imagine that
363 perhaps the Transport Independent, Printer/System Interface [18] may
364 be enhanced with a web interface that allows a device that
365 understands the TIP/SI web interface specification to query the
366 printer for toner levels.
368 4. WebFinger Protocol
370 WebFinger does not actually introduce a new protocol, per se.
371 Rather, it builds upon the existing Web Host Metadata [9]
372 specification and leverages the Cross-Origin Resource Sharing (CORS)
373 [7] specification.
375 4.1. Performing a WebFinger Query
377 The first step a client must perform in executing a WebFinger query
378 is to query for the host metadata using HTTPS or HTTP. The
379 procedures are defined in the Web Host Metadata [9] specification.
381 WebFinger clients MUST locate the LRDD link relation, if present, and
382 perform a query for that link relation, if present. All other link
383 templates found must be processed to form a complete resource
384 descriptor. The processing rules in Section 4.2 of RFC 6415 MUST be
385 followed.
387 WebFinger servers MUST accept requests for both XRD [8] and JRD [9]
388 documents. The default representation returned by the server MUST be
389 an XRD document, but a JRD document MUST be returned if the client
390 explicitly requests it by using /.well-known/host-meta.json or
391 includes an Accept header in the HTTP request with a type of
392 "application/json" [4].
394 If the client requests a JRD document when querying for host
395 metadata, the WebFinger server can assume that the client will want a
396 JRD documents when querying the LRDD resource. As such, when the
397 WebFinger server returns a JRD document containing host metadata it
398 should include a URI for an LRDD resource that can return a JRD
399 document and MAY include a URI for an LRDD resource that will return
400 an XRD document.
402 If the client queries the LRDD resource and provides a URI for which
403 the server has no information, the server MUST return a 404 status
404 code. Likewise, any query to a URI in the resource descriptor that
405 is unknown to the server MUST result in the server returning a 404
406 status code.
408 WebFinger servers MAY include cache validators in a response to
409 enable conditional requests by clients and/or expiration times as per
410 RFC 2616 section 13.
412 4.2. The Web Host Metadata "resource" Parameter
414 In addition to the normal processing logic for processing host
415 metadata information, WebFinger defines the "resource" parameter for
416 querying for host metadata and returning all of the link relations
417 from LRDD and other resource-specific link templates in a single
418 query. This resource essentially pushes the work to the server to
419 form a complete resource descriptor for the specified resource.
421 Note that support for the "resource" parameter is optional, but
422 strongly RECOMMENDED for improved performance. If a server does not
423 implement the "resource" parameter, then the server's host metadata
424 processing logic remains unchanged from RFC 6415.
426 To utilize the host-meta "resource" parameter, a WebFinger client
427 issues a request to /.well-known/host-meta or /.well-known/host-
428 meta.json as usual, but then appends a "resource" parameter as shown
429 in this example:
431 GET /.well-known/host-meta.json?resource=\
432 acct%3Abob%40example.com HTTP/1.1
433 Host: example.com
435 Note that the "\" character shown above is to indicate that the line
436 breaks at this point and continues on the next line. This was shown
437 only to avoid line wrapping in this document and is not a part of the
438 HTTP protocol.
440 When processing this request, the WebFinger server MUST
441 * Return a 404 status code if the URI provided in the resource
442 parameter is unknown to the server; and
444 * Set the "Subject" returned in the response to the value of the
445 "resource" parameter if the URI provided in the resource
446 parameter is known to the server
448 The WebFinger client can verify support for the "resource" parameter
449 by checking the value of the Subject returned in the response. If
450 the Subject matches the value of the "resource" parameter, then the
451 "resource" parameter is supported by the server.
453 For illustrative purposes, the following is an example usage of the
454 "resource" parameter that aligns with the example in Section 1.1.1 of
455 RFC 6415. The WebFinger client would issue this request:
457 GET /.well-known/host-meta.json?resource=\
458 http%3A%2F%2Fexample.com%2Fxy HTTP/1.1
459 Host: example.com
461 The WebFinger server would reply with this response:
463 HTTP/1.1 200 OK
464 Access-Control-Allow-Origin: *
465 Content-Type: application/json; charset=UTF-8
467 {
468 "subject" : "http://example.com/xy",
469 "properties" :
470 {
471 "http://spec.example.net/color" : "red"
472 },
473 "links" :
474 [
475 {
476 "rel" : "hub",
477 "href" : "http://example.com/hub"
478 },
479 {
480 "rel" : "hub",
481 "href" : "http://example.com/another/hub"
482 },
483 {
484 "rel" : "author",
485 "href" : "http://example.com/john"
486 },
487 {
488 "rel" : "author",
489 "template" : "http://example.com/author?\
490 q=http%3A%2F%2Fexample.com%2Fxy"
491 }
492 ]
493 }
495 4.3. The Web Host Metadata "rel" Parameter
497 WebFinger also defines the "rel" parameter for use when querying for
498 host metadata. It is used to return a subset of the information that
499 would otherwise be returned without the "rel" parameter. When the
500 "rel" parameter is used, only the link relations that match the
501 space-separated list of link relations provided via "rel" are
502 included in the list of links returned in resource descriptor. All
503 other information normally present in a resource descriptor is
504 present in the resource descriptor, even when "rel" is employed.
506 The purpose of the "rel" parameter is to return a subset of
507 resource's link relations. It is not intended to reduce the work
508 required of a server to produce a response. That said, use of the
509 parameter might reduce processing requirements on either the client
510 or server, and it might also reduce the bandwidth required to convey
511 the partial resource descriptor, especially if there are numerous
512 link relation values to convey for a given resource.
514 Support for the "rel" parameter is OPTIONAL, but support is
515 RECOMMENDED for both the host-meta resource and the LRDD resource.
517 For illustrative purposes, the following is an example usage of the
518 "rel" parameter that aligns with the example in Section 1.1.1 of RFC
519 6415. The WebFinger client would issue this request to receive links
520 that are of the type "hub" and "copyright":
522 GET /.well-known/host-meta.json?resource=\
523 http%3A%2F%2Fexample.com%2Fxy&rel=hub%20copyright HTTP/1.1
524 Host: example.com
526 The WebFinger server would reply with this response:
528 HTTP/1.1 200 OK
529 Access-Control-Allow-Origin: *
530 Content-Type: application/json; charset=UTF-8
532 {
533 "subject" : "http://example.com/xy",
534 "properties" :
535 {
536 "http://spec.example.net/color" : "red"
537 },
538 "links" :
540 [
541 {
542 "rel" : "hub",
543 "href" : "http://example.com/hub"
544 },
545 {
546 "rel" : "hub",
547 "href" : "http://example.com/another/hub"
548 }
549 ]
550 }
552 Note that in this example, the "author" links are removed, though all
553 other content is present. Since there were no "copyright" links,
554 none are returned.
556 In the event that a client requests links for link relations that are
557 not defined for the specified resource, a resource descriptor MUST be
558 returned, void of any links. When a JRD is returned, the "links"
559 array MAY be either absent or empty. The server MUST NOT return a
560 404 status code when a particular link relation specified via "rel"
561 is not defined for the resource, as a 404 status code is reserved for
562 indicating that the resource itself (e.g., as indicated via the
563 "resource" parameter) does not exist.
565 5. The "acct" URI
567 The Web Host Metadata specification [9] allows for any kind of
568 resource to be queried, as does WebFinger. However, a specific type
569 of resource is needed in order to query information about a human
570 user.
572 WebFinger uses the "acct" URI to refer to a human user's account on
573 the Internet. While other URI scheme MAY be used to query for
574 information related to a human user, other schemes are not explicitly
575 defined for that purpose.
577 5.1. Using the "acct" URI
579 The "acct" URI takes a familiar form in looking like an email
580 address. However, the account URI is not an email address and should
581 not be mistaken for one. Quite often, the account URI minus the
582 "acct:" scheme prefix may be exactly the same as the user's email
583 address.
585 A user MUST NOT be required to enter the "acct" URI scheme name along
586 with his account identifier into any WebFinger client. Rather, the
587 WebFinger client MUST accept identifiers that are void of the "acct:"
588 portion of the identifier. Composing a properly formatted "acct" URI
589 is the responsibility of the WebFinger client.
591 A user MAY provide a fully-specified "acct" URI.
593 5.2. Syntax of "acct" URI
595 The "acct" URI syntax is defined here in Augmented Backus-Naur Form
596 (ABNF) [6] and borrows syntax elements from RFC 3986 [5]:
598 acctURI = "acct:" userpart "@" domainpart
599 userpart = 1*( unreserved / pct-encoded )
600 domainpart = domainlabel 1*( "." domainlabel)
601 domainlabel = alphanum / alphanum *( alphanum / "-" ) alphanum
602 alphanum = ALPHA / DIGIT
604 The "acct" URI scheme allows any character from the Unicode [11]
605 character set encoded as a UTF-8 [19] string that is then percent-
606 encoded as necessary into valid ASCII [20]. Characters in the
607 domainpart must be encoded to support internationalized domain names
608 (IDNs) [12].
610 Characters in the userpart or domainpart that are not unreserved must
611 be percent-encoded when used in a protocol or document that only
612 supports or requires ASCII. When carried in a document (e.g., XRD or
613 JRD) or protocol that supports the Unicode character set (e.g., UTF-8
614 or UTF-16 [21]), the URI strings may appear in the protocol or
615 document's native encoding without percent-encoding. Such usage of a
616 URI is commonly referred to as an Internationalized Resource
617 Identifier (IRI). Conversion between an IRI and URI is described in
618 Section 3 of RFC 3987 [13].
620 6. The "acct" Link Relation
622 6.1. Purpose for the "acct" Link Relation
624 Users of some services might have an "acct" URI that looks
625 significantly different from his or her email address, perhaps using
626 an entirely different domain name. It is also possible for a user
627 have multiple accounts that a user wants to advertise and that a
628 WebFinger client may want to query. To address both of these needs,
629 this specification defines the "acct" link relation.
631 Since an account may make a reference to one or more different
632 accounts, WebFinger clients MUST take steps to avoid loops wherein
633 two accounts, directly or indirectly, refer the client to each other.
635 There are no limits on the number of "acct" link relations that might
636 be returned in a WebFinger query.
638 An "acct" link relation used within the context of a WebFinger query
639 for a user's account MUST NOT return "acct" link relations for
640 another individual.
642 The "acct" link relation also makes it possible to use the link
643 relation in HTML documents or in HTTP headers as described in the Web
644 Linking specification [3]. This would allow, by way of example, for
645 a user to advertise his or her account identifier in a blog, article,
646 or other content located on a server that is unrelated to his user
647 account. Since there may be multiple contributors to an article,
648 there may be more than one "acct" link relation in an HTML document
649 or in HTTP headers. It is RECOMMENDED that no more than one "acct"
650 link relation is advertised per author of a given web page, as a
651 client may otherwise not understand that the multiple link relations
652 are for the same person; references to other accounts should be done
653 from within a user's account, as described in the preceding
654 paragraphs.
656 6.2. Example Message Exchange Using the "acct" Link Relation
658 Consider the following non-normative example.
660 Suppose Alice receives an email from bob@example.net. While Bob's
661 email identifier might be in the example.net domain, he holds his
662 account with an "acct" URI in the example.com domain. His email
663 provider may provide WebFinger services to enable redirecting Alice
664 when she queries for acct:bob@example.net.
666 Suppose Alice's client issues the following request:
668 GET /.well-known/host-meta.json?resource=\
669 acct%3Abob%40example.net HTTP/1.1
670 Host: example.net
672 The response that Alice's client receives back might be:
674 HTTP/1.1 200 OK
675 Access-Control-Allow-Origin: *
676 Content-Type: application/json; charset=UTF-8
678 {
679 "subject" : "acct:bob@example.net",
680 "links" :
681 [
682 {
683 "rel" : "acct",
684 "href" : "acct:bob@example.com"
685 },
686 {
687 "rel" : "acct",
688 "href" : "acct:bob@example.org"
689 }
690 ]
691 }
693 Alice's WebFinger client could then perform queries against the URIs
694 acct:bob@example.com and acct:bob@example.org in order to get the
695 information Alice is seeking.
697 7. Cross-Origin Resource Sharing (CORS)
699 WebFinger is most useful when it is accessible without restrictions
700 on the Internet, and that includes web browsers. Therefore,
701 WebFinger servers MUST support Cross-Origin Resource Sharing (CORS)
702 [7]. Specifically, all queries to /.well-known/host-meta, /.well-
703 known/host-meta.json, and to the LRDD URI must include the following
704 HTTP header in the response:
706 Access-Control-Allow-Origin: *
708 8. Security Considerations
710 All of the security considerations applicable to Web Host Metadata
711 [9] and Cross-Origin Resource Sharing [7] are also applicable to this
712 specification. Of particular importance is the recommended use of
713 HTTPS to ensure that information is not modified during transit.
714 Clients should verify that the certificate used on an HTTPS
715 connection is valid.
717 When using HTTP to request an XRD document, WebFinger clients SHOULD
718 verify the XRD document's signature, if present, to ensure that the
719 XRD document has not been modified. WebFinger servers SHOULD include
720 a signature for XRD documents.
722 Service providers and users should be aware that placing information
723 on the Internet accessible through WebFinger means that any user can
724 access that information. While WebFinger can be an extremely useful
725 tool for allowing quick and easy access to one's avatar, blog, or
726 other personal information, users should understand the risks, too.
727 If one does not wish to share certain information with the world, do
728 not allow that information to be accessible through WebFinger.
730 The aforementioned word of caution is perhaps worth emphasizing again
731 with respect to dynamic information one might wish to share, such as
732 the current location of a user. WebFinger can be a powerful tool
733 used to assemble information about a person all in one place, but
734 service providers and users should be mindful of the nature of that
735 information shared and the fact that it might be available for the
736 entire world to see. Sharing location information, for example,
737 would potentially put a person in danger from any individual who
738 might seek to inflict harm on that person.
740 The easy access to user information via WebFinger was a design goal
741 of the protocol, not a limitation. If one wishes to limit access to
742 information available via WebFinger, such as a WebFinger server for
743 use inside a corporate network, the network administrator must take
744 measures necessary to limit access from outside the network.
746 9. IANA Considerations
748 RFC Editor: Please replace QQQQ in the following two sub-sections
749 with a reference to this RFC.
751 9.1. Registration of the "acct" URI scheme name
753 This specification requests IANA to register the "acct" URI scheme in
754 the "Permanent URI Schemes" sub-registry in the "Uniform Resource
755 Identifier (URI) Schemes" IANA registry [17]. This registration
756 follows the URI Scheme Registration Template detailed in Section 5.4
757 of RFC 4395 [15].
759 URI scheme name: acct
761 Status: Permanent
763 URI scheme syntax: see Section 4.1 of RFC QQQQ
765 URI scheme semantics: see Section 4.1 of RFC QQQQ
767 Encoding considerations: The "acct" URI scheme allows any character
768 from the Unicode character set encoded as a UTF-8 string that is
769 then percent-encoded as necessary to result in an internal
770 representation in US-ASCII [10]
772 Applications/protocols that use this URI scheme name: WebFinger
774 Security considerations: see Section 7 of RFC QQQQ
776 Contact: Gonzalo Salgueiro
778 Author/Change controller: IETF
780 References: See Section 10 of RFC QQQQ
782 9.2. Registration of the "acct" Link Relation Type
784 Relation Name: acct
785 Description: A link relation that refers to a user's WebFinger
786 account identifier.
788 Reference: RFC QQQQ
790 Notes:
792 Application Data:
794 10. Acknowledgments
796 The authors would like to acknowledge Eran Hammer-Lahav, Blaine Cook,
797 Brad Fitzpatrick, Laurent-Walter Goix, and Joe Clarke for their
798 invaluable input.
800 11. References
802 11.1. Normative References
804 [1] Bradner, S., "Key words for use in RFCs to Indicate Requirement
805 Levels", BCP 14, RFC 2119, March 1997.
807 [2] Fielding, R., Gettys, J., Mogul, J., Frystyk, H.,
808 Masinter, L., Leach, P., and T. Berners-Lee, "Hypertext
809 Transfer Protocol -- HTTP/1.1", RFC 2616, June 1999.
811 [3] Nottingham, M., "Web Linking", RFC 5988, October 2010.
813 [4] Crockford, D., "The application/json Media Type for
814 JavaScript Object Notation (JSON)", RFC 4627, July 2006.
816 [5] Berners-Lee, T., Fielding, R., and Masinter, L., "Uniform
817 Resource Identifier (URI): Generic Syntax", STD 66, RFC 3986,
818 January 2005.
820 [6] Crocker, D. and P. Overell, "Augmented BNF for Syntax
821 Specifications: ABNF", STD 68, RFC 5234, January 2008.
823 [7] Van Kesteren, A., "Cross-Origin Resource Sharing", W3C CORS
824 http://www.w3.org/TR/cors/, July 2010.
826 [8] Hammer-Lahav, E. and W. Norris, "Extensible Resource Descriptor
827 (XRD) Version 1.0", http://docs.oasis-
828 open.org/xri/xrd/v1.0/xrd-1.0.html.
830 [9] Hammer-Lahav, E. and Cook, B., "Web Host Metadata", RFC 6415,
831 October 2011.
833 [10] American National Standards Institute, "Coded Character Set -
834 7-bit American Standard Code for Information Interchange", ANSI
835 X3.4, 1986.
837 [11] The Unicode Consortium. The Unicode Standard, Version 6.1.0,
838 (Mountain View, CA: The Unicode Consortium, 2012. ISBN 978-1-
839 936213-02-3) http://www.unicode.org/versions/Unicode6.1.0/.
841 [12] Klensin, J., "Internationalized Domain Names in Applications
842 (IDNA): Protocol", RFC 5891, August 2010.
844 [13] Duerst, M., "Internationalized Resource Identifiers (IRIs)",
845 RFC 3987, January 2005.
847 11.2. Informative References
849 [14] Zimmerman, D., "The Finger User Information Protocol", RFC
850 1288, December 1991.
852 [15] Hansen, T., Hardie, T., and L. Masinter, "Guidelines and
853 Registration Procedures for New URI Schemes", BCP 35, RFC 4395,
854 February 2006.
856 [16] Perreault, S., "vCard Format Specification", RFC 6350, August
857 2011.
859 [17] Internet Assigned Numbers Authority (IANA) Registry, "Uniform
860 Resource Identifier (URI) Schemes",
861 .
863 [18] "Transport Independent, Printer/System Interface", IEEE Std
864 1284.1-1997, 1997.
866 [19] Yergeau, F., "UTF-8, a transformation format of ISO 10646", RFC
867 3629, November 2003.
869 [20] Information Systems -- Coded Character Sets 7-Bit American
870 National Standard Code for Information Interchange (7-Bit
871 ASCII), ANSI X3.4-1986, December 30, 1986.
873 [21] Hoffman, P., Yergeau, F., "UTF-16, an encoding of ISO 10646",
874 RFC 2781, February 2000.
876 Author's Addresses
878 Paul E. Jones
879 Cisco Systems, Inc.
880 7025 Kit Creek Rd.
881 Research Triangle Park, NC 27709
882 USA
884 Phone: +1 919 476 2048
885 Email: paulej@packetizer.com
886 IM: xmpp:paulej@packetizer.com
888 Gonzalo Salgueiro
889 Cisco Systems, Inc.
890 7025 Kit Creek Rd.
891 Research Triangle Park, NC 27709
892 USA
894 Phone: +1 919 392 3266
895 Email: gsalguei@cisco.com
896 IM: xmpp:gsalguei@cisco.com
898 Joseph Smarr
899 Google
901 Email: jsmarr@google.com
903 Change Log (To Be Deleted Before Publication)
904 =============================================
906 -03 Draft
908 * Changed the name from Webfinger to WebFinger (common usage)
910 * Added a new paragraph to Section 4.1 to remind readers that WebFinger
911 benefits from all of the existing HTTP caching functionality
913 * Added the "rel" parameter to allow filtering the results of a
914 WebFinger query to include Links of the specified type(s)
916 * Corrected a reference to an obsoleted RFC
918 * Removed extraneous text from the terminology section
920 -02 Draft
922 * Minor editorial changes
924 * Added to the XML example to highlight that this element
925 exists, since some may not be aware
927 * Changed some of the link relation values, particularly for those that
928 are not yet standardized
930 * Added a note about "device:" not being standard
932 * Overhauled the "acct" link relation text, breaking the normative and
933 non-normative pieces apart
935 * Added additional text to the security considerations section related
936 to dynamic information (e.g., geographic information)