idnits 2.17.1
draft-ietf-appsawg-webfinger-00.txt:
Checking boilerplate required by RFC 5378 and the IETF Trust (see
https://trustee.ietf.org/license-info):
----------------------------------------------------------------------------
No issues found here.
Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt:
----------------------------------------------------------------------------
No issues found here.
Checking nits according to https://www.ietf.org/id-info/checklist :
----------------------------------------------------------------------------
No issues found here.
Miscellaneous warnings:
----------------------------------------------------------------------------
== The copyright year in the IETF Trust and authors Copyright Line does not
match the current year
-- The document date (July 3, 2012) is 4315 days in the past. Is this
intentional?
Checking references for intended status: Proposed Standard
----------------------------------------------------------------------------
(See RFCs 3967 and 4897 for information about using normative references
to lower-maturity documents in RFCs)
== Unused Reference: '4' is defined on line 913, but no explicit reference
was found in the text
== Unused Reference: '12' is defined on line 938, but no explicit reference
was found in the text
== Unused Reference: '15' is defined on line 950, but no explicit reference
was found in the text
== Unused Reference: '17' is defined on line 957, but no explicit reference
was found in the text
== Unused Reference: '19' is defined on line 964, but no explicit reference
was found in the text
** Obsolete normative reference: RFC 2616 (ref. '2') (Obsoleted by RFC
7230, RFC 7231, RFC 7232, RFC 7233, RFC 7234, RFC 7235)
** Obsolete normative reference: RFC 5785 (ref. '3') (Obsoleted by RFC 8615)
** Obsolete normative reference: RFC 5988 (ref. '4') (Obsoleted by RFC 8288)
** Obsolete normative reference: RFC 4627 (ref. '5') (Obsoleted by RFC
7158, RFC 7159)
-- Possible downref: Non-RFC (?) normative reference: ref. '9'
-- Possible downref: Non-RFC (?) normative reference: ref. '10'
-- Possible downref: Non-RFC (?) normative reference: ref. '12'
-- Obsolete informational reference (is this intentional?): RFC 4395 (ref.
'15') (Obsoleted by RFC 7595)
Summary: 4 errors (**), 0 flaws (~~), 6 warnings (==), 5 comments (--).
Run idnits with the --verbose option for more detailed information about
the items above.
--------------------------------------------------------------------------------
2 Network Working Group Paul E. Jones
3 Internet Draft Gonzalo Salgueiro
4 Intended status: Standards Track Cisco Systems
5 Expires: January 3, 2013 Joseph Smarr
6 Google
7 July 3, 2012
9 WebFinger
10 draft-ietf-appsawg-webfinger-00.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 January 3, 2013.
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. Overview.......................................................3
58 4. Example Uses of WebFinger......................................4
59 4.1. Locating a User's Blog....................................4
60 4.2. Retrieving a Person's Contact Information.................7
61 4.3. Simplifying the Login Process.............................8
62 4.4. Retrieving Device Information.............................9
63 5. WebFinger Protocol............................................10
64 5.1. Performing a WebFinger Query.............................10
65 5.2. The Web Host Metadata "resource" Parameter...............11
66 5.3. The Web Host Metadata "rel" Parameter....................13
67 5.4. WebFinger and URIs.......................................14
68 6. The "acct" Link Relation......................................15
69 6.1. Purpose for the "acct" Link Relation.....................15
70 6.2. Example Message Exchange Using the "acct" Link Relation..16
71 7. Cross-Origin Resource Sharing (CORS)..........................17
72 8. Controlling Access to Information.............................17
73 9. Implementation Notes (Non-Normative)..........................18
74 10. Security Considerations......................................18
75 11. IANA Considerations..........................................19
76 11.1. Registration of the "acct" Link Relation Type...........19
77 12. Acknowledgments..............................................19
78 13. References...................................................19
79 13.1. Normative References....................................19
80 13.2. Informative References..................................20
81 Author's Addresses...............................................21
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 Error! Reference source not found., the attribute is a "rel"
119 and the value is an "href".
121 3. Overview
123 WebFinger enables the discovery of information about accounts,
124 devices, and other entities that are associated with web-accessible
125 domains. In essence, there are two steps to discovering such
126 information:
128 1. By querying the domain itself, one can find out how to discover
129 information about accounts, devices, and other associated with
130 that domain.
131 2. By then querying an entity at the domain, one will find links to
132 more detailed information, which can then be queried individually.
134 To enable such functionality, WebFinger makes heavy use of well-known
135 URIs as defined in RFC 5785 [3] and "Link Relations" as defined in
136 RFC 5988 [3]. Briefly, a link is a typed connection between two web
137 resources that are identified by Internationalized Resource
138 Identifiers (IRIs) [13]; this connection consists of a context IRI, a
139 link relation type, a target IRI, and optionally some target
140 attributes, resulting in statements of the form "{context IRI} has a
141 {relation type} resource at {target IRI}, which has {target
142 attributes}". When used in the Link HTTP header, the context IRI is
143 the IRI of the requested resource, the relation type is the value of
144 the "rel" parameter, the target IRI is URI-Reference contained in the
145 Link header, and the target attributes are the parameters such as
146 "hreflang", "media", "title", "title*", "type", and any other link-
147 extension parameters.
149 Thus the framework for WebFinger consists of several building blocks:
151 1. To query the domain, one requests a web host metadata file [11]
152 located at a well-known URI of /.well-known/host-meta at the
153 domain of interest.
154 2. The web server at the domain returns an Extensible Resource
155 Descriptor (XRD) or a JavaScript Object Notation (JSON) Resource
156 Descriptor (JRD) document, including a Link-based Resource
157 Descriptor Document (LRDD) link relation.
158 3. To discover information about accounts, devices, or other entities
159 associated with the domain, one requests the actual Link-based
160 Resource Descriptor Document associated with a particular URI at
161 the domain (e.g., an 'acct' URI, 'http' URI', or 'mailto' URI).
162 4. The web server at the domain returns an XRD or JRD document about
163 the requested URI, which includes specialized link relations
164 pointing to resources that contain more detailed information about
165 the entity.
167 This model is illustrated in the examples under Section 4, then
168 described more formally under Section 5. Note that steps 2 and 3
169 above may be accomplished simultaneously by utilizing the "resource"
170 parameter defined in Section 5.2.
172 4. Example Uses of WebFinger
174 In this section, we describe just a few sample uses for WebFinger and
175 show what the protocol looks like. This is not an exhaustive list of
176 possible uses and the entire section should be considered non-
177 normative. The list of potential use cases is virtually unlimited
178 since a user can share any kind of machine-consumable information via
179 WebFinger.
181 4.1. Locating a User's Blog
183 Assume you receive an email from Bob and he refers to something he
184 posted on his blog, but you do not know where Bob's blog is located.
185 It would be simple to discover the address of Bob's blog if he makes
186 that information available via WebFinger.
188 Let's assume your email client discovers that blog automatically for
189 you. After receiving the message from Bob (bob@example.com), your
190 email client performs the following steps behind the scenes.
192 First, it tries to get the host metadata [11] information for the
193 domain example.com. It does this by issuing the following HTTPS
194 query to example.com:
196 GET /.well-known/host-meta HTTP/1.1
197 Host: example.com
199 The server replies with an XRD [10] document:
201 HTTP/1.1 200 OK
202 Access-Control-Allow-Origin: *
203 Content-Type: application/xrd+xml; charset=UTF-8
205
206
207
210
212 The client then processes the received XRD in accordance with the Web
213 Host Metadata [11] procedures. The client will see the LRDD link
214 relation and issue a query with the user's account URI [6] or other
215 URI that serves as an alias for the account. (The account URI is
216 discussed in Section 4.2.) The query might look like this:
218 GET /lrdd/?uri=acct%3Abob%40example.com HTTP/1.1
219 Host: example.com
221 The server might then respond with a message like this:
223 HTTP/1.1 200 OK
224 Access-Control-Allow-Origin: *
225 Content-Type: application/xrd+xml; charset=UTF-8
227
228
229 2012-03-13T20:56:11Z
230 acct:bob@example.com
231 http://www.example.com/~bob/
232
234
236
238
240 The email client might take note of the "blog" link relation in the
241 above XRD document that refers to Bob's blog. This URL would then be
242 presented to you so that you could then visit his blog.
244 The email client might also note that Bob has published an avatar
245 link relation and use that picture to represent Bob inside the email
246 client.
248 Note in the above example that an alias is provided that can also be
249 used to return information about the user's account. Had the "http:"
250 URI been used to query for information about Bob, the query would
251 have appeared as:
253 GET /lrdd/?uri= http%3A%2F%2Fwww.example.com%2F~bob%2F HTTP/1.1
254 Host: example.com
256 The response would have been substantially the same, with the subject
257 and alias information changed as necessary. Other information, such
258 as the expiration time might also change, but the set of link
259 relations and properties would be the same with either response.
260 Let's assume, though, that for the above query the client requested a
261 JRD representation for the resource rather than an XRD
262 representation. In that case, the response would have been:
264 HTTP/1.1 200 OK
265 Access-Control-Allow-Origin: *
266 Content-Type: application/json; charset=UTF-8
268 {
269 "expires" : "2012-03-13T20:56:11Z",
270 "subject" : "http://www.example.com/~bob/",
271 "aliases" :
272 [
273 "acct:bob@example.com"
274 ],
275 "links" :
276 [
277 {
278 "rel" : "http://webfinger.net/rel/avatar",
279 "href" : "http://www.example.com/~bob/bob.jpg"
280 },
281 {
282 "rel" : "http://webfinger.net/rel/profile-page",
283 "href" : "http://www.example.com/~bob/"
284 },
285 {
286 "rel" : "http://packetizer.com/rel/blog",
287 "href" : "http://blogs.example.com/bob/"
288 }
289 ]
290 }
292 4.2. Retrieving a Person's Contact Information
294 Assume you have Alice in your address book, but her phone number
295 appears to be invalid. You could use WebFinger to find her current
296 phone number and update your address book.
298 Let's assume you have a web-based address book that you wish to
299 update. When you instruct the address book to pull Alice's current
300 contact information, the address book might issue a query like this
301 to get host metadata information for example.com:
303 GET /.well-known/host-meta.json HTTP/1.1
304 Host: example.com
306 Note the address book is looking for a JSON [5] representation,
307 whereas we used XML in the previous example.
309 The server might reply with something like this:
311 HTTP/1.1 200 OK
312 Access-Control-Allow-Origin: *
313 Content-Type: application/json; charset=UTF-8
315 {
316 "links" :
317 [
318 {
319 "rel" : "lrdd",
320 "type" : "application/json",
321 "template" :
322 "https://example.com/lrdd/?format=json&uri={uri}"
323 }
324 ]
325 }
327 The client processes the response as described in RFC 6415 [11]. It
328 will process the LRDD link relation using Alice's account URI by
329 issuing this query:
331 GET /lrdd/?format=json&uri=acct%3Aalice%40example.com HTTP/1.1
332 Host: example.com
334 The server might return a response like this:
336 HTTP/1.1 200 OK
337 Access-Control-Allow-Origin: *
338 Content-Type: application/json; charset=UTF-8
340 {
341 "expires" : "2012-03-13T20:56:11Z",
342 "subject" : "acct:alice@example.com",
343 "links" :
344 [
345 {
346 "rel" : "http://webfinger.net/rel/avatar",
347 "href" : "http://example.com/~alice/alice.jpg"
348 },
349 {
350 "rel" : "vcard",
351 "href" : "http://example.com/~alice/alice.vcf"
352 }
353 ]
354 }
356 With this response, the address book might see the vcard [16] link
357 relation and use that file to offer you updated contact information.
359 4.3. Simplifying the Login Process
361 OpenID (http://www.openid.net) is great for allowing users to log
362 into a web site, though one criticism is that it is challenging for
363 users to remember the URI they are assigned. WebFinger can help
364 address this issue by allowing users to use user@domain-style
365 addresses. Using a user's account URI, a web site can perform a
366 query to discover the associated OpenID identifier for a user.
368 Let's assume Carol is trying to use OpenID to log into a blog. The
369 blog server might issue the following query to get the host metadata
370 information:
372 GET /.well-known/host-meta.json HTTP/1.1
373 Host: example.com
375 The response that comes back is similar to the previous example:
377 HTTP/1.1 200 OK
378 Access-Control-Allow-Origin: *
379 Content-Type: application/json; charset=UTF-8
380 {
381 "expires" : "2012-03-13T20:56:11Z",
382 "links" :
383 [
384 {
385 "rel" : "lrdd",
386 "type" : "application/json",
387 "template" :
388 "https://example.com/lrdd/?format=json&uri={uri}"
389 }
391 ]
392 }
394 The blog server processes the response as described in RFC 6415. It
395 will process the LRDD link relation using Carol's account URI by
396 issuing this query:
398 GET /lrdd/?format=json&uri=acct%3Acarol%40example.com HTTP/1.1
400 The server might return a response like this:
402 HTTP/1.1 200 OK
403 Access-Control-Allow-Origin: *
404 Content-Type: application/json; charset=UTF-8
406 {
407 "subject" : "acct:carol@example.com",
408 "links" :
409 [
410 {
411 "rel" : "http://webfinger.net/rel/avatar",
412 "href" : "http://example.com/~alice/alice.jpg"
413 },
414 {
415 "rel" : "http://specs.openid.net/auth/2.0/provider",
416 "href" : "https://openid.example.com/carol"
417 }
418 ]
419 }
421 At this point, the blog server knows that Carol's OpenID identifier
422 is https://openid.example.com/carol and could then proceed with the
423 login process as usual.
425 4.4. Retrieving Device Information
427 While the examples thus far have been focused on information about
428 humans, WebFinger does not limit queries to only those that use the
429 account URI scheme. Any URI scheme that contains domain information
430 MAY be used with WebFinger. Let's suppose there are devices on the
431 network like printers and you would like to check the current toner
432 level for a particular printer identified via the URI like
433 device:p1.example.com. While the "device" URI scheme is not
434 presently specified, we use it here for illustrative purposes.
436 Following the procedures similar to those above, a query may be
437 issued to get link relations specific to this URI like this:
439 GET /lrdd/?format=json&uri=device%3Ap1.example.com HTTP/1.1
440 Host: example.com
442 The link relations that are returned may be quite different than
443 those for user accounts. Perhaps we may see a response like this:
445 HTTP/1.1 200 OK
446 Access-Control-Allow-Origin: *
447 Content-Type: application/json; charset=UTF-8
449 {
450 "subject" : "device:p1.example.com",
451 "links" :
452 [
453 {
454 "rel" : "tipsi",
455 "href" : "http://192.168.1.5/npap/"
456 }
457 ]
458 }
460 While this example is entirely fictitious, you can imagine that
461 perhaps the Transport Independent, Printer/System Interface [18] may
462 be enhanced with a web interface that allows a device that
463 understands the TIP/SI web interface specification to query the
464 printer for toner levels.
466 5. WebFinger Protocol
468 WebFinger does not actually introduce a new protocol, per se.
469 Rather, it builds upon the existing Web Host Metadata [11]
470 specification and leverages the Cross-Origin Resource Sharing (CORS)
471 [9] specification.
473 5.1. Performing a WebFinger Query
475 The first step a client must perform in executing a WebFinger query
476 is to query for the host metadata using HTTPS or HTTP. The
477 procedures are defined in the Web Host Metadata [11] specification.
479 WebFinger clients MUST locate the LRDD link relation, if present, and
480 perform a query for that link relation, if present. All other link
481 templates found must be processed to form a complete resource
482 descriptor. The processing rules in Section 4.2 of RFC 6415 MUST be
483 followed.
485 WebFinger servers MUST accept requests for both XRD [10] and JRD [11]
486 documents. The default representation returned by the server MUST be
487 an XRD document, but a JRD document MUST be returned if the client
488 explicitly requests it by using /.well-known/host-meta.json or
489 includes an Accept header in the HTTP request with a type of
490 "application/json" [5].
492 If the client requests a JRD document when querying for host
493 metadata, the WebFinger server can assume that the client will want a
494 JRD documents when querying the LRDD resource. As such, when the
495 WebFinger server returns a JRD document containing host metadata it
496 should include a URI for an LRDD resource that can return a JRD
497 document and MAY include a URI for an LRDD resource that will return
498 an XRD document.
500 If the client queries the LRDD resource and provides a URI for which
501 the server has no information, the server MUST return a 404 status
502 code. Likewise, any query to a URI in the resource descriptor that
503 is unknown to the server MUST result in the server returning a 404
504 status code.
506 WebFinger servers MAY include cache validators in a response to
507 enable conditional requests by clients and/or expiration times as per
508 RFC 2616 section 13.
510 5.2. The Web Host Metadata "resource" Parameter
512 In addition to the normal processing logic for processing host
513 metadata information, WebFinger defines the "resource" parameter for
514 querying for host metadata and returning all of the link relations
515 from LRDD and other resource-specific link templates in a single
516 query. This resource essentially pushes the work to the server to
517 form a complete resource descriptor for the specified resource.
519 WebFinger servers compliant with this specification MUST support for
520 the "resource" parameter as a means of improving performance and
521 reducing client complexity. Note that an RFC 6415-compliant server
522 might not implement the "resource" parameter, though the server would
523 respond to queries from the client as described in RFC 6415. Thus,
524 WebFinger clients MUST check the server response to ensure that the
525 "resource" parameter is supported as explained below.
527 To utilize the host-meta "resource" parameter, a WebFinger client
528 issues a request to /.well-known/host-meta or /.well-known/host-
529 meta.json as usual, but then appends a "resource" parameter as shown
530 in this example:
532 GET /.well-known/host-meta.json?resource=\
533 acct%3Abob%40example.com HTTP/1.1
534 Host: example.com
536 Note that the "\" character shown above is to indicate that the line
537 breaks at this point and continues on the next line. This was shown
538 only to avoid line wrapping in this document and is not a part of the
539 HTTP protocol.
541 When processing this request, the WebFinger server MUST
543 * Return a 404 status code if the URI provided in the resource
544 parameter is unknown to the server; and
546 * Set the "Subject" returned in the response to the value of the
547 "resource" parameter if the URI provided in the resource
548 parameter is known to the server
550 The WebFinger client can verify support for the "resource" parameter
551 by checking the value of the Subject returned in the response. If
552 the Subject matches the value of the "resource" parameter, then the
553 "resource" parameter is supported by the server.
555 For illustrative purposes, the following is an example usage of the
556 "resource" parameter that aligns with the example in Section 1.1.1 of
557 RFC 6415. The WebFinger client would issue this request:
559 GET /.well-known/host-meta.json?resource=\
560 http%3A%2F%2Fexample.com%2Fxy HTTP/1.1
561 Host: example.com
563 The WebFinger server would reply with this response:
565 HTTP/1.1 200 OK
566 Access-Control-Allow-Origin: *
567 Content-Type: application/json; charset=UTF-8
569 {
570 "subject" : "http://example.com/xy",
571 "properties" :
572 {
573 "http://spec.example.net/color" : "red"
574 },
575 "links" :
576 [
577 {
578 "rel" : "hub",
579 "href" : "http://example.com/hub"
580 },
581 {
582 "rel" : "hub",
583 "href" : "http://example.com/another/hub"
584 },
585 {
586 "rel" : "author",
587 "href" : "http://example.com/john"
588 },
589 {
590 "rel" : "author",
591 "href" : "http://example.com/author?\
592 q=http%3A%2F%2Fexample.com%2Fxy"
593 }
594 ]
595 }
597 5.3. The Web Host Metadata "rel" Parameter
599 WebFinger also defines the "rel" parameter for use when querying for
600 host metadata. It is used to return a subset of the information that
601 would otherwise be returned without the "rel" parameter. When the
602 "rel" parameter is used, only the link relations that match the
603 space-separated list of link relations provided via "rel" are
604 included in the list of links returned in the resource descriptor.
605 All other information normally present in a resource descriptor is
606 present in the resource descriptor, even when "rel" is employed.
608 The purpose of the "rel" parameter is to return a subset of
609 resource's link relations. It is not intended to reduce the work
610 required of a server to produce a response. That said, use of the
611 parameter might reduce processing requirements on either the client
612 or server, and it might also reduce the bandwidth required to convey
613 the partial resource descriptor, especially if there are numerous
614 link relation values to convey for a given resource.
616 Support for the "rel" parameter is OPTIONAL, but support is
617 RECOMMENDED for both the host-meta resource and the LRDD resource.
619 For illustrative purposes, the following is an example usage of the
620 "rel" parameter that aligns with the example in Section 1.1.1 of RFC
621 6415. The WebFinger client would issue this request to receive links
622 that are of the type "hub" and "copyright":
624 GET /.well-known/host-meta.json?resource=\
625 http%3A%2F%2Fexample.com%2Fxy&rel=hub%20copyright HTTP/1.1
626 Host: example.com
628 The WebFinger server would reply with this response:
630 HTTP/1.1 200 OK
631 Access-Control-Allow-Origin: *
632 Content-Type: application/json; charset=UTF-8
633 {
634 "subject" : "http://example.com/xy",
635 "properties" :
636 {
637 "http://spec.example.net/color" : "red"
638 },
639 "links" :
640 [
641 {
642 "rel" : "hub",
643 "href" : "http://example.com/hub"
644 },
645 {
646 "rel" : "hub",
647 "href" : "http://example.com/another/hub"
648 }
649 ]
650 }
652 Note that in this example, the "author" links are removed, though all
653 other content is present. Since there were no "copyright" links,
654 none are returned.
656 In the event that a client requests links for link relations that are
657 not defined for the specified resource, a resource descriptor MUST be
658 returned, void of any links. When a JRD is returned, the "links"
659 array MAY be either absent or empty. The server MUST NOT return a
660 404 status code when a particular link relation specified via "rel"
661 is not defined for the resource, as a 404 status code is reserved for
662 indicating that the resource itself (e.g., as indicated via the
663 "resource" parameter) does not exist.
665 5.4. WebFinger and URIs
667 Requests for both LRDD documents and hostmeta files can include a
668 parameter specifying the URI of an account, device, or other entity
669 (for LRDD this is the "uri" parameter as defined by the operative XRD
670 or JRD template, for hostmeta this is the "resource" parameter).
671 WebFinger itself is agnostic regarding the scheme of such a URI: it
672 could be an "acct" URI as defined in the next section, an "http" or
673 "https" URI, a "mailto" URI, or some other scheme.
675 For resources associated with a user account at a domain, use of the
676 "acct" URI scheme [7] is RECOMMENDED, since it explicitly identifies
677 an account accessible via WebFinger. Further, the "acct" URI scheme
678 is not associated other protocols as, by way of example, the "mailto"
679 URI scheme is associated with email. Since not every domain offers
680 email service, using the "mailto" URI scheme [8] is not ideal for
681 identifying user accounts across all domains. That said, use of the
682 "mailto" URI scheme would be ideal for use with WebFinger to discover
683 mail server configuration information for a user, for example.
685 A domain MAY utilize one or more URIs that serve as aliases for the
686 user's account, such as URIs that use the "http" URI scheme [2]. A
687 WebFinger server MUST return substantially the same response to both
688 an "acct" URI and any alias URI for the account, including the same
689 set of link relations and properties. In addition, the server SHOULD
690 include the entire list aliases for the user's account in the XRD or
691 JRD.
693 6. The "acct" Link Relation
695 6.1. Purpose for the "acct" Link Relation
697 Users of some services might have an "acct" URI that looks
698 significantly different from his or her email address, perhaps using
699 an entirely different domain name. It is also possible for a user to
700 have multiple accounts that a user wants to have cross-referenced
701 from another account. To address both of these needs, this
702 specification defines the "acct" link relation.
704 The "acct" link relation allows a WebFinger server to reference one
705 or more other user account URIs from within a user account. The
706 "acct" link relation is intended to allow a client to incorporate
707 additional link relations by reference to produce a complete set of
708 link relations for a user. Any newly discovered link relations found
709 by querying the referenced account SHOULD be merged into the resource
710 descriptor document at the point where the "acct" link relation was
711 inserted.
713 Note that the "acct" link relation does not replace the use of
714 standard HTTP 3xx response codes to indicate the new temporary or
715 permanent location of a user account. If a user account is moved to
716 a different location, then a 3xx response code SHOULD be used.
718 Since an account may make a reference to one or more different
719 accounts, WebFinger clients MUST take steps to avoid loops wherein
720 two account URIs, directly or indirectly, refer the client to each
721 other.
723 There are no limits on the number of "acct" link relations that might
724 be returned in a WebFinger query.
726 An "acct" link relation used within the context of a WebFinger query
727 for a user's account MUST NOT return "acct" link relations for
728 another user.
730 6.2. Example Message Exchange Using the "acct" Link Relation
732 Consider the following non-normative example.
734 Suppose Alice receives an email from bob@example.net. While Bob's
735 email identifier might be in the example.net domain, he holds a user
736 account in the example.com domain and another account in the
737 example.org domain. His email provider may provide WebFinger
738 services to enable redirecting Alice when she queries for
739 acct:bob@example.net.
741 Suppose Alice's client issues the following request:
743 GET /.well-known/host-meta.json?resource=\
744 acct%3Abob%40example.net HTTP/1.1
745 Host: example.net
747 The response that Alice's client receives back might be:
749 HTTP/1.1 200 OK
750 Access-Control-Allow-Origin: *
751 Content-Type: application/json; charset=UTF-8
753 {
754 "subject" : "acct:bob@example.net",
755 "links" :
756 [
757 {
758 "rel" : "acct",
759 "href" : "acct:bob@example.com"
760 },
761 {
762 "rel" : "acct",
763 "href" : "acct:bob@example.org"
764 },
766 {
767 "rel" : "acct",
768 "href" : "mailto:bob@example.net"
769 }
770 ]
771 }
773 Alice's WebFinger client could then perform queries against the URIs
774 acct:bob@example.com, acct:bob@example.org, and
775 mailto:bob@example.net in order to get the information Alice is
776 seeking.
778 7. Cross-Origin Resource Sharing (CORS)
780 WebFinger is most useful when it is accessible without restrictions
781 on the Internet, and that includes web browsers. Therefore,
782 WebFinger servers MUST support Cross-Origin Resource Sharing (CORS)
783 [9] when serving content intended for public consumption.
784 Specifically, all queries to /.well-known/host-meta, /.well-
785 known/host-meta.json, and to the LRDD URI must include the following
786 HTTP header in the response:
788 Access-Control-Allow-Origin: *
790 Enterprise WebFinger servers that wish to restrict access to
791 information from external entities SHOULD use a more restrictive
792 Access-Control-Allow-Origin header and MAY exclude the header
793 entirely.
795 8. Controlling Access to Information
797 As with all web resources, access to the Host Metadata resource and
798 the LRDD resource MAY require authentication. Further, failure to
799 provide required credentials MAY result in the server forbidding
800 access or providing a different response than had the client
801 authenticated with the server.
803 Likewise, a server MAY provide different responses to different
804 clients based on other factors, such as whether the client is inside
805 or outside a corporate network. As a concrete example, a query
806 performed on the internal corporate network might return link
807 relations to employee pictures whereas link relations for employee
808 pictures might not be provided to external entities.
810 Further, link relations provided in a WebFinger server response MAY
811 point to web resources that impose access restrictions. For example,
812 it is possible that the aforementioned corporate server may provide
813 both internal and external entities with URIs to employee pictures,
814 but further authentication MAY be required in order for the WebFinger
815 client to access those resources if the request comes from outside
816 the corporate network.
818 The decisions made with respect to what set of link relations a
819 WebFinger server provides to one client versus another and what
820 resources require further authentication, as well as the specific
821 authentication mechanisms employed, are outside the scope of this
822 document.
824 9. Implementation Notes (Non-Normative)
826 A user should not be required to enter the "acct" URI scheme name
827 along with his account identifier into any WebFinger client. Rather,
828 the WebFinger client should accept identifiers that are void of the
829 "acct:" portion of the identifier. Composing a properly formatted
830 "acct" URI is the responsibility of the WebFinger client.
832 10. Security Considerations
834 All of the security considerations applicable to Web Host Metadata
835 [11] and Cross-Origin Resource Sharing [9] are also applicable to
836 this specification. Of particular importance is the recommended use
837 of HTTPS to ensure that information is not modified during transit.
838 Clients should verify that the certificate used on an HTTPS
839 connection is valid.
841 When using HTTP to request an XRD document, WebFinger clients SHOULD
842 verify the XRD document's signature, if present, to ensure that the
843 XRD document has not been modified. Additionally, WebFinger servers
844 SHOULD include a signature for XRD documents served over HTTP.
846 Service providers and users should be aware that placing information
847 on the Internet accessible through WebFinger means that any user can
848 access that information. While WebFinger can be an extremely useful
849 tool for allowing quick and easy access to one's avatar, blog, or
850 other personal information, users should understand the risks, too.
851 If one does not wish to share certain information with the world, do
852 not allow that information to be freely accessible through WebFinger.
854 The aforementioned word of caution is perhaps worth emphasizing again
855 with respect to dynamic information one might wish to share, such as
856 the current location of a user. WebFinger can be a powerful tool
857 used to assemble information about a person all in one place, but
858 service providers and users should be mindful of the nature of that
859 information shared and the fact that it might be available for the
860 entire world to see. Sharing location information, for example,
861 would potentially put a person in danger from any individual who
862 might seek to inflict harm on that person.
864 The easy access to user information via WebFinger was a design goal
865 of the protocol, not a limitation. If one wishes to limit access to
866 information available via WebFinger, such as a WebFinger server for
867 use inside a corporate network, the network administrator must take
868 measures necessary to limit access from outside the network. Using
869 standard methods for securing web resources, network administrators
870 do have the ability to control access to resources that might return
871 sensitive information. Further, WebFinger servers can be employed in
872 such a way as to require authentication and prevent disclosure of
873 information to unauthorized entities.
875 11. IANA Considerations
877 RFC Editor: Please replace QQQQ in the following two sub-sections
878 with a reference to this RFC.
880 11.1. Registration of the "acct" Link Relation Type
882 Relation Name: acct
884 Description: A link relation that refers to a user's WebFinger
885 account identifier.
887 Reference: RFC QQQQ
889 Notes:
891 Application Data:
893 12. Acknowledgments
895 The authors would like to acknowledge Eran Hammer-Lahav, Blaine Cook,
896 Brad Fitzpatrick, Laurent-Walter Goix, Joe Clarke, Mike Jones, and
897 Peter Saint-Andre for their invaluable input.
899 13. References
901 13.1. Normative References
903 [1] Bradner, S., "Key words for use in RFCs to Indicate Requirement
904 Levels", BCP 14, RFC 2119, March 1997.
906 [2] Fielding, R., Gettys, J., Mogul, J., Frystyk, H.,
907 Masinter, L., Leach, P., and T. Berners-Lee, "Hypertext
908 Transfer Protocol -- HTTP/1.1", RFC 2616, June 1999.
910 [3] Nottingham, M., Hammer-Lahav, E., "Defining Well-Known Uniform
911 Resource Identifiers (URIs)", RFC 5785, April 2010.
913 [4] Nottingham, M., "Web Linking", RFC 5988, October 2010.
915 [5] Crockford, D., "The application/json Media Type for
916 JavaScript Object Notation (JSON)", RFC 4627, July 2006.
918 [6] Berners-Lee, T., Fielding, R., and Masinter, L., "Uniform
919 Resource Identifier (URI): Generic Syntax", STD 66, RFC 3986,
920 January 2005.
922 [7] Saint-Andre, P., "The 'acct' URI Scheme", draft-saintandre-
923 acct-uri-01, July 2012.
925 [8] Duerst, M., Masinter, L., and J. Zawinski, "The 'mailto' URI
926 Scheme", RFC 6068, October 2010.
928 [9] Van Kesteren, A., "Cross-Origin Resource Sharing", W3C CORS
929 http://www.w3.org/TR/cors/, July 2010.
931 [10] Hammer-Lahav, E. and W. Norris, "Extensible Resource Descriptor
932 (XRD) Version 1.0", http://docs.oasis-
933 open.org/xri/xrd/v1.0/xrd-1.0.html.
935 [11] Hammer-Lahav, E. and Cook, B., "Web Host Metadata", RFC 6415,
936 October 2011.
938 [12] American National Standards Institute, "Coded Character Set -
939 7-bit American Standard Code for Information Interchange", ANSI
940 X3.4, 1986.
942 [13] Duerst, M., "Internationalized Resource Identifiers (IRIs)",
943 RFC 3987, January 2005.
945 13.2. Informative References
947 [14] Zimmerman, D., "The Finger User Information Protocol", RFC
948 1288, December 1991.
950 [15] Hansen, T., Hardie, T., and L. Masinter, "Guidelines and
951 Registration Procedures for New URI Schemes", BCP 35, RFC 4395,
952 February 2006.
954 [16] Perreault, S., "vCard Format Specification", RFC 6350, August
955 2011.
957 [17] Internet Assigned Numbers Authority (IANA) Registry, "Uniform
958 Resource Identifier (URI) Schemes",
959 .
961 [18] "Transport Independent, Printer/System Interface", IEEE Std
962 1284.1-1997, 1997.
964 [19] Hoffman, P., Yergeau, F., "UTF-16, an encoding of ISO 10646",
965 RFC 2781, February 2000.
967 Author's Addresses
969 Paul E. Jones
970 Cisco Systems, Inc.
971 7025 Kit Creek Rd.
972 Research Triangle Park, NC 27709
973 USA
975 Phone: +1 919 476 2048
976 Email: paulej@packetizer.com
977 IM: xmpp:paulej@packetizer.com
979 Gonzalo Salgueiro
980 Cisco Systems, Inc.
981 7025 Kit Creek Rd.
982 Research Triangle Park, NC 27709
983 USA
985 Phone: +1 919 392 3266
986 Email: gsalguei@cisco.com
987 IM: xmpp:gsalguei@cisco.com
989 Joseph Smarr
990 Google
992 Email: jsmarr@google.com