idnits 2.17.1
draft-jones-appsawg-webfinger-06.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 (June 18, 2012) is 4330 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 958, 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. '8'
-- Possible downref: Non-RFC (?) normative reference: ref. '9'
-- Possible downref: Non-RFC (?) normative reference: ref. '11'
-- Possible downref: Non-RFC (?) normative reference: ref. '12'
-- Obsolete informational reference (is this intentional?): RFC 4395 (ref.
'16') (Obsoleted by RFC 7595)
Summary: 4 errors (**), 0 flaws (~~), 2 warnings (==), 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: December 18, 2012 Joseph Smarr
6 Google
7 June 18, 2012
9 WebFinger
10 draft-jones-appsawg-webfinger-06.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 December 18, 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. 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" URI................................................15
69 7. The "acct" Link Relation......................................16
70 7.1. Purpose for the "acct" Link Relation.....................16
71 7.2. Example Message Exchange Using the "acct" Link Relation..16
72 8. Cross-Origin Resource Sharing (CORS)..........................17
73 9. Controlling Access to Information.............................17
74 10. Implementation Notes (Non-Normative).........................18
75 11. Security Considerations......................................18
76 12. IANA Considerations..........................................19
77 12.1. Registration of the "acct" URI scheme name..............19
78 12.2. Registration of the "acct" Link Relation Type...........20
79 13. Acknowledgments..............................................20
80 14. References...................................................20
81 14.1. Normative References....................................20
82 14.2. Informative References..................................21
83 Author's Addresses...............................................22
85 1. Introduction
87 There is a utility found on UNIX systems called "finger" [15] that
88 allows a person to access information about another person. The
89 information being queried might be on a computer anywhere in the
90 world. The information returned via "finger" is simply a plain text
91 file that contains unstructured information provided by the queried
92 user.
94 WebFinger borrows the concept of the legacy finger protocol, but
95 introduces a very different approach to sharing information. Rather
96 than returning a simple unstructured text file, Webfinger uses
97 structured documents that contain link relations. These link
98 relations point to information a user or entity on the Internet
99 wishes to expose. For a person, the kinds of information that might
100 be exposed include a personal profile address, identity service,
101 telephone number, or preferred avatar. WebFinger may also be used to
102 learn information about objects on the network, such as the amount of
103 toner in a printer or the physical location of a server.
105 Information returned via WebFinger might be for direct human
106 consumption (e.g., another user's phone number) or it might be used
107 by systems to help carry out some operation (e.g., facilitate logging
108 into a web site by determining a user's identification service).
110 2. Terminology
112 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
113 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this
114 document are to be interpreted as described in RFC 2119 [1].
116 WebFinger makes heavy use of "Link Relations". Briefly, a Link
117 Relation is an attribute and value pair used on the Internet wherein
118 the attribute identifies the type of link to which the associated
119 value refers. In Hypertext Transfer Protocol (HTTP) [2] and Web
120 Linking Error! Reference source not found., the attribute is a "rel"
121 and the value is an "href".
123 3. Overview
125 WebFinger enables the discovery of information about accounts,
126 devices, and other entities that are associated with web-accessible
127 domains. In essence, there are two steps to discovering such
128 information:
130 1. By querying the domain itself, one can find out how to discover
131 information about accounts, devices, and other associated with
132 that domain.
133 2. By then querying an entity at the domain, one will find links to
134 more detailed information, which can then be queried individually.
136 To enable such functionality, WebFinger makes heavy use of well-known
137 URIs as defined in RFC 5785 [3] and "Link Relations" as defined in
138 RFC 5988 [3]. Briefly, a link is a typed connection between two web
139 resources that are identified by Internationalized Resource
140 Identifiers (IRIs) [14]; this connection consists of a context IRI, a
141 link relation type, a target IRI, and optionally some target
142 attributes, resulting in statements of the form "{context IRI} has a
143 {relation type} resource at {target IRI}, which has {target
144 attributes}". When used in the Link HTTP header, the context IRI is
145 the IRI of the requested resource, the relation type is the value of
146 the "rel" parameter, the target IRI is URI-Reference contained in the
147 Link header, and the target attributes are the parameters such as
148 "hreflang", "media", "title", "title*", "type", and any other link-
149 extension parameters.
151 Thus the framework for WebFinger consists of several building blocks:
153 1. To query the domain, one requests a web host metadata file [10]
154 located at a well-known URI of /.well-known/host-meta at the
155 domain of interest.
156 2. The web server at the domain returns an Extensible Resource
157 Descriptor (XRD) or a JavaScript Object Notation (JSON) Resource
158 Descriptor (JRD) document, including a Link-based Resource
159 Descriptor Document (LRDD) link relation.
160 3. To discover information about accounts, devices, or other entities
161 associated with the domain, one requests the actual Link-based
162 Resource Descriptor Document associated with a particular URI at
163 the domain (e.g., an 'acct' URI, 'http' URI', or 'mailto' URI).
164 4. The web server at the domain returns an XRD or JRD document about
165 the requested URI, which includes specialized link relations
166 pointing to resources that contain more detailed information about
167 the entity.
169 This model is illustrated in the examples under Section 4, then
170 described more formally under Section 5. Note that steps 2 and 3
171 above may be accomplished simultaneously by utilizing the "resource"
172 parameter defined in Section 5.2.
174 4. Example Uses of WebFinger
176 In this section, we describe just a few sample uses for WebFinger and
177 show what the protocol looks like. This is not an exhaustive list of
178 possible uses and the entire section should be considered non-
179 normative. The list of potential use cases is virtually unlimited
180 since a user can share any kind of machine-consumable information via
181 WebFinger.
183 4.1. Locating a User's Blog
185 Assume you receive an email from Bob and he refers to something he
186 posted on his blog, but you do not know where Bob's blog is located.
187 It would be simple to discover the address of Bob's blog if he makes
188 that information available via WebFinger.
190 Let's assume your email client discovers that blog automatically for
191 you. After receiving the message from Bob (bob@example.com), your
192 email client performs the following steps behind the scenes.
194 First, it tries to get the host metadata [10] information for the
195 domain example.com. It does this by issuing the following HTTPS
196 query to example.com:
198 GET /.well-known/host-meta HTTP/1.1
199 Host: example.com
201 The server replies with an XRD [9] document:
203 HTTP/1.1 200 OK
204 Access-Control-Allow-Origin: *
205 Content-Type: application/xrd+xml; charset=UTF-8
207
208
209
212
214 The client then processes the received XRD in accordance with the Web
215 Host Metadata [10] procedures. The client will see the LRDD link
216 relation and issue a query with the user's account URI [6] or other
217 URI that serves as an alias for the account. (The account URI is
218 discussed in Section 4.2.) The query might look like this:
220 GET /lrdd/?uri=acct%3Abob%40example.com HTTP/1.1
221 Host: example.com
223 The server might then respond with a message like this:
225 HTTP/1.1 200 OK
226 Access-Control-Allow-Origin: *
227 Content-Type: application/xrd+xml; charset=UTF-8
229
230
231 2012-03-13T20:56:11Z
232 acct:bob@example.com
233 http://www.example.com/~bob/
234
236
238
240
242 The email client might take note of the "blog" link relation in the
243 above XRD document that refers to Bob's blog. This URL would then be
244 presented to you so that you could then visit his blog.
246 The email client might also note that Bob has published an avatar
247 link relation and use that picture to represent Bob inside the email
248 client.
250 Note in the above example that an alias is provided that can also be
251 used to return information about the user's account. Had the "http:"
252 URI been used to query for information about Bob, the query would
253 have appeared as:
255 GET /lrdd/?uri= http%3A%2F%2Fwww.example.com%2F~bob%2F HTTP/1.1
256 Host: example.com
258 The response would have been substantially the same, with the subject
259 and alias information changed as necessary. Other information, such
260 as the expiration time might also change, but the set of link
261 relations and properties would be the same with either response.
262 Let's assume, though, that for the above query the client requested a
263 JRD representation for the resource rather than an XRD
264 representation. In that case, the response would have been:
266 HTTP/1.1 200 OK
267 Access-Control-Allow-Origin: *
268 Content-Type: application/json; charset=UTF-8
270 {
271 "expires" : "2012-03-13T20:56:11Z",
272 "subject" : "http://www.example.com/~bob/",
273 "aliases" :
274 [
275 "acct:bob@example.com"
276 ],
277 "links" :
278 [
279 {
280 "rel" : "http://webfinger.net/rel/avatar",
281 "href" : "http://www.example.com/~bob/bob.jpg"
282 },
283 {
284 "rel" : "http://webfinger.net/rel/profile-page",
285 "href" : "http://www.example.com/~bob/"
286 },
287 {
288 "rel" : "http://packetizer.com/rel/blog",
289 "href" : "http://blogs.example.com/bob/"
290 }
292 ]
293 }
295 4.2. Retrieving a Person's Contact Information
297 Assume you have Alice in your address book, but her phone number
298 appears to be invalid. You could use WebFinger to find her current
299 phone number and update your address book.
301 Let's assume you have a web-based address book that you wish to
302 update. When you instruct the address book to pull Alice's current
303 contact information, the address book might issue a query like this
304 to get host metadata information for example.com:
306 GET /.well-known/host-meta.json HTTP/1.1
307 Host: example.com
309 Note the address book is looking for a JSON [5] representation,
310 whereas we used XML in the previous example.
312 The server might reply with something like this:
314 HTTP/1.1 200 OK
315 Access-Control-Allow-Origin: *
316 Content-Type: application/json; charset=UTF-8
318 {
319 "links" :
320 [
321 {
322 "rel" : "lrdd",
323 "type" : "application/json",
324 "template" :
325 "https://example.com/lrdd/?format=json&uri={uri}"
326 }
327 ]
328 }
330 The client processes the response as described in RFC 6415 [10]. It
331 will process the LRDD link relation using Alice's account URI by
332 issuing this query:
334 GET /lrdd/?format=json&uri=acct%3Aalice%40example.com HTTP/1.1
335 Host: example.com
337 The server might return a response like this:
339 HTTP/1.1 200 OK
340 Access-Control-Allow-Origin: *
341 Content-Type: application/json; charset=UTF-8
343 {
344 "expires" : "2012-03-13T20:56:11Z",
345 "subject" : "acct:alice@example.com",
346 "links" :
347 [
348 {
349 "rel" : "http://webfinger.net/rel/avatar",
350 "href" : "http://example.com/~alice/alice.jpg"
351 },
352 {
353 "rel" : "vcard",
354 "href" : "http://example.com/~alice/alice.vcf"
355 }
356 ]
357 }
359 With this response, the address book might see the vcard [17] link
360 relation and use that file to offer you updated contact information.
362 4.3. Simplifying the Login Process
364 OpenID (http://www.openid.net) is great for allowing users to log
365 into a web site, though one criticism is that it is challenging for
366 users to remember the URI they are assigned. WebFinger can help
367 address this issue by allowing users to use user@domain-style
368 addresses. Using a user's account URI, a web site can perform a
369 query to discover the associated OpenID identifier for a user.
371 Let's assume Carol is trying to use OpenID to log into a blog. The
372 blog server might issue the following query to get the host metadata
373 information:
375 GET /.well-known/host-meta.json HTTP/1.1
376 Host: example.com
378 The response that comes back is similar to the previous example:
380 HTTP/1.1 200 OK
381 Access-Control-Allow-Origin: *
382 Content-Type: application/json; charset=UTF-8
383 {
384 "expires" : "2012-03-13T20:56:11Z",
385 "links" :
386 [
387 {
388 "rel" : "lrdd",
389 "type" : "application/json",
390 "template" :
391 "https://example.com/lrdd/?format=json&uri={uri}"
392 }
393 ]
394 }
396 The blog server processes the response as described in RFC 6415. It
397 will process the LRDD link relation using Carol's account URI by
398 issuing this query:
400 GET /lrdd/?format=json&uri=acct%3Acarol%40example.com HTTP/1.1
402 The server might return a response like this:
404 HTTP/1.1 200 OK
405 Access-Control-Allow-Origin: *
406 Content-Type: application/json; charset=UTF-8
408 {
409 "subject" : "acct:carol@example.com",
410 "links" :
411 [
412 {
413 "rel" : "http://webfinger.net/rel/avatar",
414 "href" : "http://example.com/~alice/alice.jpg"
415 },
416 {
417 "rel" : "http://specs.openid.net/auth/2.0/provider",
418 "href" : "https://openid.example.com/carol"
419 }
420 ]
421 }
423 At this point, the blog server knows that Carol's OpenID identifier
424 is https://openid.example.com/carol and could then proceed with the
425 login process as usual.
427 4.4. Retrieving Device Information
429 While the examples thus far have been focused on information about
430 humans, WebFinger does not limit queries to only those that use the
431 account URI scheme. Any URI scheme that contains domain information
432 MAY be used with WebFinger. Let's suppose there are devices on the
433 network like printers and you would like to check the current toner
434 level for a particular printer identified via the URI like
435 device:p1.example.com. While the "device" URI scheme is not
436 presently specified, we use it here for illustrative purposes.
438 Following the procedures similar to those above, a query may be
439 issued to get link relations specific to this URI like this:
441 GET /lrdd/?format=json&uri=device%3Ap1.example.com HTTP/1.1
442 Host: example.com
444 The link relations that are returned may be quite different than
445 those for user accounts. Perhaps we may see a response like this:
447 HTTP/1.1 200 OK
448 Access-Control-Allow-Origin: *
449 Content-Type: application/json; charset=UTF-8
451 {
452 "subject" : "device:p1.example.com",
453 "links" :
454 [
455 {
456 "rel" : "tipsi",
457 "href" : "http://192.168.1.5/npap/"
458 }
459 ]
460 }
462 While this example is entirely fictitious, you can imagine that
463 perhaps the Transport Independent, Printer/System Interface [19] may
464 be enhanced with a web interface that allows a device that
465 understands the TIP/SI web interface specification to query the
466 printer for toner levels.
468 5. WebFinger Protocol
470 WebFinger does not actually introduce a new protocol, per se.
471 Rather, it builds upon the existing Web Host Metadata [10]
472 specification and leverages the Cross-Origin Resource Sharing (CORS)
473 [8] specification.
475 5.1. Performing a WebFinger Query
477 The first step a client must perform in executing a WebFinger query
478 is to query for the host metadata using HTTPS or HTTP. The
479 procedures are defined in the Web Host Metadata [10] specification.
481 WebFinger clients MUST locate the LRDD link relation, if present, and
482 perform a query for that link relation, if present. All other link
483 templates found must be processed to form a complete resource
484 descriptor. The processing rules in Section 4.2 of RFC 6415 MUST be
485 followed.
487 WebFinger servers MUST accept requests for both XRD [9] and JRD [10]
488 documents. The default representation returned by the server MUST be
489 an XRD document, but a JRD document MUST be returned if the client
490 explicitly requests it by using /.well-known/host-meta.json or
491 includes an Accept header in the HTTP request with a type of
492 "application/json" [5].
494 If the client requests a JRD document when querying for host
495 metadata, the WebFinger server can assume that the client will want a
496 JRD documents when querying the LRDD resource. As such, when the
497 WebFinger server returns a JRD document containing host metadata it
498 should include a URI for an LRDD resource that can return a JRD
499 document and MAY include a URI for an LRDD resource that will return
500 an XRD document.
502 If the client queries the LRDD resource and provides a URI for which
503 the server has no information, the server MUST return a 404 status
504 code. Likewise, any query to a URI in the resource descriptor that
505 is unknown to the server MUST result in the server returning a 404
506 status code.
508 WebFinger servers MAY include cache validators in a response to
509 enable conditional requests by clients and/or expiration times as per
510 RFC 2616 section 13.
512 5.2. The Web Host Metadata "resource" Parameter
514 In addition to the normal processing logic for processing host
515 metadata information, WebFinger defines the "resource" parameter for
516 querying for host metadata and returning all of the link relations
517 from LRDD and other resource-specific link templates in a single
518 query. This resource essentially pushes the work to the server to
519 form a complete resource descriptor for the specified resource.
521 WebFinger servers compliant with this specification MUST support for
522 the "resource" parameter as a means of improving performance and
523 reducing client complexity. Note that an RFC 6415-compliant server
524 might not implement the "resource" parameter, though the server would
525 respond to queries from the client as described in RFC 6415. Thus,
526 WebFinger clients MUST check the server response to ensure that the
527 "resource" parameter is supported as explained below.
529 To utilize the host-meta "resource" parameter, a WebFinger client
530 issues a request to /.well-known/host-meta or /.well-known/host-
531 meta.json as usual, but then appends a "resource" parameter as shown
532 in this example:
534 GET /.well-known/host-meta.json?resource=\
535 acct%3Abob%40example.com HTTP/1.1
536 Host: example.com
538 Note that the "\" character shown above is to indicate that the line
539 breaks at this point and continues on the next line. This was shown
540 only to avoid line wrapping in this document and is not a part of the
541 HTTP protocol.
543 When processing this request, the WebFinger server MUST
545 * Return a 404 status code if the URI provided in the resource
546 parameter is unknown to the server; and
548 * Set the "Subject" returned in the response to the value of the
549 "resource" parameter if the URI provided in the resource
550 parameter is known to the server
552 The WebFinger client can verify support for the "resource" parameter
553 by checking the value of the Subject returned in the response. If
554 the Subject matches the value of the "resource" parameter, then the
555 "resource" parameter is supported by the server.
557 For illustrative purposes, the following is an example usage of the
558 "resource" parameter that aligns with the example in Section 1.1.1 of
559 RFC 6415. The WebFinger client would issue this request:
561 GET /.well-known/host-meta.json?resource=\
562 http%3A%2F%2Fexample.com%2Fxy HTTP/1.1
563 Host: example.com
565 The WebFinger server would reply with this response:
567 HTTP/1.1 200 OK
568 Access-Control-Allow-Origin: *
569 Content-Type: application/json; charset=UTF-8
571 {
572 "subject" : "http://example.com/xy",
573 "properties" :
574 {
575 "http://spec.example.net/color" : "red"
576 },
577 "links" :
578 [
579 {
580 "rel" : "hub",
581 "href" : "http://example.com/hub"
582 },
583 {
584 "rel" : "hub",
585 "href" : "http://example.com/another/hub"
586 },
587 {
588 "rel" : "author",
589 "href" : "http://example.com/john"
590 },
591 {
592 "rel" : "author",
593 "href" : "http://example.com/author?\
594 q=http%3A%2F%2Fexample.com%2Fxy"
595 }
596 ]
597 }
599 5.3. The Web Host Metadata "rel" Parameter
601 WebFinger also defines the "rel" parameter for use when querying for
602 host metadata. It is used to return a subset of the information that
603 would otherwise be returned without the "rel" parameter. When the
604 "rel" parameter is used, only the link relations that match the
605 space-separated list of link relations provided via "rel" are
606 included in the list of links returned in the resource descriptor.
607 All other information normally present in a resource descriptor is
608 present in the resource descriptor, even when "rel" is employed.
610 The purpose of the "rel" parameter is to return a subset of
611 resource's link relations. It is not intended to reduce the work
612 required of a server to produce a response. That said, use of the
613 parameter might reduce processing requirements on either the client
614 or server, and it might also reduce the bandwidth required to convey
615 the partial resource descriptor, especially if there are numerous
616 link relation values to convey for a given resource.
618 Support for the "rel" parameter is OPTIONAL, but support is
619 RECOMMENDED for both the host-meta resource and the LRDD resource.
621 For illustrative purposes, the following is an example usage of the
622 "rel" parameter that aligns with the example in Section 1.1.1 of RFC
623 6415. The WebFinger client would issue this request to receive links
624 that are of the type "hub" and "copyright":
626 GET /.well-known/host-meta.json?resource=\
627 http%3A%2F%2Fexample.com%2Fxy&rel=hub%20copyright HTTP/1.1
628 Host: example.com
630 The WebFinger server would reply with this response:
632 HTTP/1.1 200 OK
633 Access-Control-Allow-Origin: *
634 Content-Type: application/json; charset=UTF-8
636 {
637 "subject" : "http://example.com/xy",
638 "properties" :
639 {
640 "http://spec.example.net/color" : "red"
641 },
642 "links" :
643 [
644 {
645 "rel" : "hub",
646 "href" : "http://example.com/hub"
647 },
648 {
649 "rel" : "hub",
650 "href" : "http://example.com/another/hub"
651 }
652 ]
653 }
655 Note that in this example, the "author" links are removed, though all
656 other content is present. Since there were no "copyright" links,
657 none are returned.
659 In the event that a client requests links for link relations that are
660 not defined for the specified resource, a resource descriptor MUST be
661 returned, void of any links. When a JRD is returned, the "links"
662 array MAY be either absent or empty. The server MUST NOT return a
663 404 status code when a particular link relation specified via "rel"
664 is not defined for the resource, as a 404 status code is reserved for
665 indicating that the resource itself (e.g., as indicated via the
666 "resource" parameter) does not exist.
668 5.4. WebFinger and URIs
670 Requests for both LRDD documents and hostmeta files can include a
671 parameter specifying the URI of an account, device, or other entity
672 (for LRDD this is the "uri" parameter as defined by the operative XRD
673 or JRD template, for hostmeta this is the "resource" parameter).
674 WebFinger itself is agnostic regarding the scheme of such a URI: it
675 could be an "acct" URI as defined in the next section, an "http" or
676 "https" URI, a "mailto" URI, or some other scheme.
678 For resources associated with a user account at a domain, use of the
679 "acct" URI scheme is RECOMMENDED, since it explicitly identifies an
680 account accessible via WebFinger. Further, the "acct" URI scheme is
681 not associated other protocols as, by way of example, the "mailto"
682 URI scheme is associated with email. Since not every domain offers
683 email service, using the "mailto" URI scheme is not ideal for
684 identifying user accounts across all domains. That said, use of the
685 "mailto" URI scheme would be ideal for use with WebFinger to discover
686 mail server configuration information for a user, for example.
688 A domain MAY utilize one or more URIs that serve as aliases for the
689 user's account, such as URIs that use the "http" URI scheme. A
690 WebFinger server MUST return substantially the same response to both
691 an "acct" URI and any alias URI for the account, including the same
692 set of link relations and properties. In addition, the server SHOULD
693 include the entire list aliases for the user's account in the XRD or
694 JRD.
696 6. The "acct" URI
698 The "acct" URI takes a familiar form in looking like an email
699 address. However, the account URI is not an email address and should
700 not be mistaken for one. Quite often, the account URI minus the
701 "acct:" scheme prefix may be exactly the same as the user's email
702 address.
704 The "acct" URI syntax is defined here in Augmented Backus-Naur Form
705 (ABNF) [7] and borrows syntax elements from RFC 3986 [6]:
707 acctURI = "acct:" userpart "@" domainpart
708 userpart = 1*( unreserved / pct-encoded )
709 domainpart = domainlabel 1*( "." domainlabel)
710 domainlabel = alphanum / alphanum *( alphanum / "-" ) alphanum
711 alphanum = ALPHA / DIGIT
713 The "acct" URI scheme allows any character from the Unicode [12]
714 character set encoded as a UTF-8 [20] string that is then percent-
715 encoded as necessary into valid ASCII [21]. Characters in the
716 domainpart must be encoded to support internationalized domain names
717 (IDNs) [13].
719 Characters in the userpart or domainpart that are not unreserved must
720 be percent-encoded when used in a protocol or document that only
721 supports or requires ASCII. When carried in a document (e.g., XRD or
722 JRD) or protocol that supports the Unicode character set (e.g., UTF-8
723 or UTF-16 [22]), the URI strings may appear in the protocol or
724 document's native encoding without percent-encoding. Such usage of a
725 URI is commonly referred to as an Internationalized Resource
726 Identifier (IRI). Conversion between an IRI and URI is described in
727 Section 3 of RFC 3987 [14].
729 7. The "acct" Link Relation
731 7.1. Purpose for the "acct" Link Relation
733 Users of some services might have an "acct" URI that looks
734 significantly different from his or her email address, perhaps using
735 an entirely different domain name. It is also possible for a user
736 have multiple accounts that a user wants to advertise and that a
737 WebFinger client may want to query. To address both of these needs,
738 this specification defines the "acct" link relation.
740 Since an account may make a reference to one or more different
741 accounts, WebFinger clients MUST take steps to avoid loops wherein
742 two accounts, directly or indirectly, refer the client to each other.
744 There are no limits on the number of "acct" link relations that might
745 be returned in a WebFinger query.
747 An "acct" link relation used within the context of a WebFinger query
748 for a user's account MUST NOT return "acct" link relations for
749 another individual.
751 7.2. Example Message Exchange Using the "acct" Link Relation
753 Consider the following non-normative example.
755 Suppose Alice receives an email from bob@example.net. While Bob's
756 email identifier might be in the example.net domain, he holds his
757 account with an "acct" URI in the example.com domain. His email
758 provider may provide WebFinger services to enable redirecting Alice
759 when she queries for acct:bob@example.net.
761 Suppose Alice's client issues the following request:
763 GET /.well-known/host-meta.json?resource=\
764 acct%3Abob%40example.net HTTP/1.1
765 Host: example.net
767 The response that Alice's client receives back might be:
769 HTTP/1.1 200 OK
770 Access-Control-Allow-Origin: *
771 Content-Type: application/json; charset=UTF-8
773 {
774 "subject" : "acct:bob@example.net",
775 "links" :
776 [
777 {
778 "rel" : "acct",
779 "href" : "acct:bob@example.com"
780 },
781 {
782 "rel" : "acct",
783 "href" : "acct:bob@example.org"
784 }
785 ]
786 }
788 Alice's WebFinger client could then perform queries against the URIs
789 acct:bob@example.com and acct:bob@example.org in order to get the
790 information Alice is seeking.
792 8. Cross-Origin Resource Sharing (CORS)
794 WebFinger is most useful when it is accessible without restrictions
795 on the Internet, and that includes web browsers. Therefore,
796 WebFinger servers MUST support Cross-Origin Resource Sharing (CORS)
797 [8] when serving content intended for public consumption.
798 Specifically, all queries to /.well-known/host-meta, /.well-
799 known/host-meta.json, and to the LRDD URI must include the following
800 HTTP header in the response:
802 Access-Control-Allow-Origin: *
804 Enterprise WebFinger servers that wish to restrict access to
805 information from external entities SHOULD use a more restrictive
806 Access-Control-Allow-Origin header and MAY exclude the header
807 entirely.
809 9. Controlling Access to Information
811 As with all web resources, access to the Host Metadata resource and
812 the LRDD resource MAY require authentication. Further, failure to
813 provide required credentials MAY result in the server forbidding
814 access or providing a different response than had the client
815 authenticated with the server.
817 Likewise, a server MAY provide different responses to different
818 clients based on other factors, such as whether the client is inside
819 or outside a corporate network. As a concrete example, a query
820 performed on the internal corporate network might return link
821 relations to employee pictures whereas link relations for employee
822 pictures might not be provided to external entities.
824 Further, link relations provided in a WebFinger server response MAY
825 point to web resources that impose access restrictions. For example,
826 it is possible that the aforementioned corporate server may provide
827 both internal and external entities with URIs to employee pictures,
828 but further authentication MAY be required in order for the WebFinger
829 client to access those resources if the request comes from outside
830 the corporate network.
832 The decisions made with respect to what set of link relations a
833 WebFinger server provides to one client versus another and what
834 resources require further authentication, as well as the specific
835 authentication mechanisms employed, are outside the scope of this
836 document.
838 10. Implementation Notes (Non-Normative)
840 A user should not be required to enter the "acct" URI scheme name
841 along with his account identifier into any WebFinger client. Rather,
842 the WebFinger client should accept identifiers that are void of the
843 "acct:" portion of the identifier. Composing a properly formatted
844 "acct" URI is the responsibility of the WebFinger client.
846 11. Security Considerations
848 All of the security considerations applicable to Web Host Metadata
849 [10] and Cross-Origin Resource Sharing [8] are also applicable to
850 this specification. Of particular importance is the recommended use
851 of HTTPS to ensure that information is not modified during transit.
852 Clients should verify that the certificate used on an HTTPS
853 connection is valid.
855 When using HTTP to request an XRD document, WebFinger clients SHOULD
856 verify the XRD document's signature, if present, to ensure that the
857 XRD document has not been modified. Additionally, WebFinger servers
858 SHOULD include a signature for XRD documents served over HTTP.
860 Service providers and users should be aware that placing information
861 on the Internet accessible through WebFinger means that any user can
862 access that information. While WebFinger can be an extremely useful
863 tool for allowing quick and easy access to one's avatar, blog, or
864 other personal information, users should understand the risks, too.
865 If one does not wish to share certain information with the world, do
866 not allow that information to be freely accessible through WebFinger.
868 The aforementioned word of caution is perhaps worth emphasizing again
869 with respect to dynamic information one might wish to share, such as
870 the current location of a user. WebFinger can be a powerful tool
871 used to assemble information about a person all in one place, but
872 service providers and users should be mindful of the nature of that
873 information shared and the fact that it might be available for the
874 entire world to see. Sharing location information, for example,
875 would potentially put a person in danger from any individual who
876 might seek to inflict harm on that person.
878 The easy access to user information via WebFinger was a design goal
879 of the protocol, not a limitation. If one wishes to limit access to
880 information available via WebFinger, such as a WebFinger server for
881 use inside a corporate network, the network administrator must take
882 measures necessary to limit access from outside the network. Using
883 standard methods for securing web resources, network administrators
884 do have the ability to control access to resources that might return
885 sensitive information. Further, WebFinger servers can be employed in
886 such a way as to require authentication and prevent disclosure of
887 information to unauthorized entities.
889 12. IANA Considerations
891 RFC Editor: Please replace QQQQ in the following two sub-sections
892 with a reference to this RFC.
894 12.1. Registration of the "acct" URI scheme name
896 This specification requests IANA to register the "acct" URI scheme in
897 the "Permanent URI Schemes" sub-registry in the "Uniform Resource
898 Identifier (URI) Schemes" IANA registry [18]. This registration
899 follows the URI Scheme Registration Template detailed in Section 5.4
900 of RFC 4395 [16].
902 URI scheme name: acct
904 Status: Permanent
906 URI scheme syntax: see Section 5.2 of RFC QQQQ
908 URI scheme semantics: see Section 5 of RFC QQQQ
910 Encoding considerations: The "acct" URI scheme allows any character
911 from the Unicode character set encoded as a UTF-8 string that is
912 then percent-encoded as necessary to result in an internal
913 representation in US-ASCII [11]
915 Applications/protocols that use this URI scheme name: WebFinger
917 Security considerations: see Section 7 of RFC QQQQ
919 Contact: Gonzalo Salgueiro
921 Author/Change controller: IETF
923 References: See Section 10 of RFC QQQQ
925 12.2. Registration of the "acct" Link Relation Type
927 Relation Name: acct
929 Description: A link relation that refers to a user's WebFinger
930 account identifier.
932 Reference: RFC QQQQ
934 Notes:
936 Application Data:
938 13. Acknowledgments
940 The authors would like to acknowledge Eran Hammer-Lahav, Blaine Cook,
941 Brad Fitzpatrick, Laurent-Walter Goix, Joe Clarke, Mike Jones, and
942 Peter Saint-Andre for their invaluable input.
944 14. References
946 14.1. Normative References
948 [1] Bradner, S., "Key words for use in RFCs to Indicate Requirement
949 Levels", BCP 14, RFC 2119, March 1997.
951 [2] Fielding, R., Gettys, J., Mogul, J., Frystyk, H.,
952 Masinter, L., Leach, P., and T. Berners-Lee, "Hypertext
953 Transfer Protocol -- HTTP/1.1", RFC 2616, June 1999.
955 [3] Nottingham, M., Hammer-Lahav, E., "Defining Well-Known Uniform
956 Resource Identifiers (URIs)", RFC 5785, April 2010.
958 [4] Nottingham, M., "Web Linking", RFC 5988, October 2010.
960 [5] Crockford, D., "The application/json Media Type for
961 JavaScript Object Notation (JSON)", RFC 4627, July 2006.
963 [6] Berners-Lee, T., Fielding, R., and Masinter, L., "Uniform
964 Resource Identifier (URI): Generic Syntax", STD 66, RFC 3986,
965 January 2005.
967 [7] Crocker, D. and P. Overell, "Augmented BNF for Syntax
968 Specifications: ABNF", STD 68, RFC 5234, January 2008.
970 [8] Van Kesteren, A., "Cross-Origin Resource Sharing", W3C CORS
971 http://www.w3.org/TR/cors/, July 2010.
973 [9] Hammer-Lahav, E. and W. Norris, "Extensible Resource Descriptor
974 (XRD) Version 1.0", http://docs.oasis-
975 open.org/xri/xrd/v1.0/xrd-1.0.html.
977 [10] Hammer-Lahav, E. and Cook, B., "Web Host Metadata", RFC 6415,
978 October 2011.
980 [11] American National Standards Institute, "Coded Character Set -
981 7-bit American Standard Code for Information Interchange", ANSI
982 X3.4, 1986.
984 [12] The Unicode Consortium. The Unicode Standard, Version 6.1.0,
985 (Mountain View, CA: The Unicode Consortium, 2012. ISBN 978-1-
986 936213-02-3) http://www.unicode.org/versions/Unicode6.1.0/.
988 [13] Klensin, J., "Internationalized Domain Names in Applications
989 (IDNA): Protocol", RFC 5891, August 2010.
991 [14] Duerst, M., "Internationalized Resource Identifiers (IRIs)",
992 RFC 3987, January 2005.
994 14.2. Informative References
996 [15] Zimmerman, D., "The Finger User Information Protocol", RFC
997 1288, December 1991.
999 [16] Hansen, T., Hardie, T., and L. Masinter, "Guidelines and
1000 Registration Procedures for New URI Schemes", BCP 35, RFC 4395,
1001 February 2006.
1003 [17] Perreault, S., "vCard Format Specification", RFC 6350, August
1004 2011.
1006 [18] Internet Assigned Numbers Authority (IANA) Registry, "Uniform
1007 Resource Identifier (URI) Schemes",
1008 .
1010 [19] "Transport Independent, Printer/System Interface", IEEE Std
1011 1284.1-1997, 1997.
1013 [20] Yergeau, F., "UTF-8, a transformation format of ISO 10646", RFC
1014 3629, November 2003.
1016 [21] Information Systems -- Coded Character Sets 7-Bit American
1017 National Standard Code for Information Interchange (7-Bit
1018 ASCII), ANSI X3.4-1986, December 30, 1986.
1020 [22] Hoffman, P., Yergeau, F., "UTF-16, an encoding of ISO 10646",
1021 RFC 2781, February 2000.
1023 Author's Addresses
1025 Paul E. Jones
1026 Cisco Systems, Inc.
1027 7025 Kit Creek Rd.
1028 Research Triangle Park, NC 27709
1029 USA
1031 Phone: +1 919 476 2048
1032 Email: paulej@packetizer.com
1033 IM: xmpp:paulej@packetizer.com
1035 Gonzalo Salgueiro
1036 Cisco Systems, Inc.
1037 7025 Kit Creek Rd.
1038 Research Triangle Park, NC 27709
1039 USA
1041 Phone: +1 919 392 3266
1042 Email: gsalguei@cisco.com
1043 IM: xmpp:gsalguei@cisco.com
1045 Joseph Smarr
1046 Google
1048 Email: jsmarr@google.com
1050 Change Log (To Be Deleted Before Publication)
1051 =============================================
1053 -06 Draft
1055 * Added an overview section
1057 * Made changes to example to show use of aliases
1059 * Added text to highlight that WebFinger may use various URI schemes
1061 * Reduced the text in the "acct" URI scheme section
1063 * Added an Implementation Notes section
1065 -05 Draft
1067 * Minor editorial corrections
1069 * Removed last paragraph from Section 6.1
1071 * Clarified use of CORS and how it may differ for enterprise use
1073 -04 Draft
1075 * Added text that makes the "resource" parameter required
1077 * Added a new section 8 that discusses controlling access to information
1079 * Added a little more to the security considerations section to briefly
1080 cover what was more fully explained in the new section 8
1082 -03 Draft
1084 * Changed the name from Webfinger to WebFinger (common usage)
1086 * Added a new paragraph to Section 4.1 to remind readers that WebFinger
1087 benefits from all of the existing HTTP caching functionality
1089 * Added the "rel" parameter to allow filtering the results of a
1090 WebFinger query to include Links of the specified type(s)
1092 * Corrected a reference to an obsoleted RFC
1093 * Removed extraneous text from the terminology section
1095 -02 Draft
1097 * Minor editorial changes
1099 * Added to the XML example to highlight that this element
1100 exists, since some may not be aware
1102 * Changed some of the link relation values, particularly for those that
1103 are not yet standardized
1105 * Added a note about "device:" not being standard
1107 * Overhauled the "acct" link relation text, breaking the normative and
1108 non-normative pieces apart
1110 * Added additional text to the security considerations section related
1111 to dynamic information (e.g., geographic information)