draft-ietf-appsawg-webfinger-00.txt   draft-ietf-appsawg-webfinger-01.txt 
Network Working Group Paul E. Jones Network Working Group Paul E. Jones
Internet Draft Gonzalo Salgueiro Internet Draft Gonzalo Salgueiro
Intended status: Standards Track Cisco Systems Intended status: Standards Track Cisco Systems
Expires: January 3, 2013 Joseph Smarr Expires: April 19, 2013 Joseph Smarr
Google Google
July 3, 2012 October 19, 2012
WebFinger WebFinger
draft-ietf-appsawg-webfinger-00.txt draft-ietf-appsawg-webfinger-01.txt
Abstract Abstract
This specification defines the WebFinger protocol. WebFinger may be This specification defines the WebFinger protocol. WebFinger may be
used to discover information about people on the Internet, such as a used to discover information about people on the Internet, such as a
person's personal profile address, identity service, telephone person's personal profile address, identity service, telephone
number, or preferred avatar. WebFinger may also be used to learn number, or preferred avatar. WebFinger may also be used to discover
information about objects on the network, such as the amount of toner information about objects on the network, such as the amount of toner
in a printer or the physical location of a server. in a printer or the physical location of a server.
Status of this Memo Status of this Memo
This Internet-Draft is submitted in full conformance with the This Internet-Draft is submitted in full conformance with the
provisions of BCP 78 and BCP 79. provisions of BCP 78 and BCP 79.
Internet-Drafts are working documents of the Internet Engineering Internet-Drafts are working documents of the Internet Engineering
Task Force (IETF). Note that other groups may also distribute Task Force (IETF). Note that other groups may also distribute
working documents as Internet-Drafts. The list of current Internet- working documents as Internet-Drafts. The list of current Internet-
Drafts is at http://datatracker.ietf.org/drafts/current/. Drafts is at http://datatracker.ietf.org/drafts/current/.
Internet-Drafts are draft documents valid for a maximum of six months Internet-Drafts are draft documents valid for a maximum of six months
and may be updated, replaced, or obsoleted by other documents at any and may be updated, replaced, or obsoleted by other documents at any
time. It is inappropriate to use Internet-Drafts as reference time. It is inappropriate to use Internet-Drafts as reference
material or to cite them other than as "work in progress." material or to cite them other than as "work in progress."
This Internet-Draft will expire on January 3, 2013. This Internet-Draft will expire on April 19, 2013.
Copyright Notice Copyright Notice
Copyright (c) 2012 IETF Trust and the persons identified as the Copyright (c) 2012 IETF Trust and the persons identified as the
document authors. All rights reserved. document authors. All rights reserved.
This document is subject to BCP 78 and the IETF Trust's Legal This document is subject to BCP 78 and the IETF Trust's Legal
Provisions Relating to IETF Documents Provisions Relating to IETF Documents
(http://trustee.ietf.org/license-info) in effect on the date of (http://trustee.ietf.org/license-info) in effect on the date of
publication of this document. Please review these documents publication of this document. Please review these documents
skipping to change at page 2, line 15 skipping to change at page 2, line 15
the Trust Legal Provisions and are provided without warranty as the Trust Legal Provisions and are provided without warranty as
described in the Simplified BSD License. described in the Simplified BSD License.
Table of Contents Table of Contents
1. Introduction...................................................2 1. Introduction...................................................2
2. Terminology....................................................3 2. Terminology....................................................3
3. Overview.......................................................3 3. Overview.......................................................3
4. Example Uses of WebFinger......................................4 4. Example Uses of WebFinger......................................4
4.1. Locating a User's Blog....................................4 4.1. Locating a User's Blog....................................4
4.2. Retrieving a Person's Contact Information.................7 4.2. Simplifying the Login Process.............................7
4.3. Simplifying the Login Process.............................8 4.3. Retrieving Device Information.............................8
4.4. Retrieving Device Information.............................9 5. WebFinger Protocol.............................................8
5. WebFinger Protocol............................................10 5.1. Performing a WebFinger Query..............................9
5.1. Performing a WebFinger Query.............................10 5.2. The Web Host Metadata "resource" Parameter...............10
5.2. The Web Host Metadata "resource" Parameter...............11 5.3. The Web Host Metadata "rel" Parameter....................12
5.3. The Web Host Metadata "rel" Parameter....................13
5.4. WebFinger and URIs.......................................14 5.4. WebFinger and URIs.......................................14
6. The "acct" Link Relation......................................15 6. The "acct" Link Relation......................................14
6.1. Purpose for the "acct" Link Relation.....................15 6.1. Purpose for the "acct" Link Relation.....................14
6.2. Example Message Exchange Using the "acct" Link Relation..16 6.2. Example Message Exchange Using the "acct" Link Relation..15
7. Cross-Origin Resource Sharing (CORS)..........................17 7. Cross-Origin Resource Sharing (CORS)..........................16
8. Controlling Access to Information.............................17 8. Controlling Access to Information.............................17
9. Implementation Notes (Non-Normative)..........................18 9. Hosted and Distributed WebFinger Services.....................17
10. Security Considerations......................................18 9.1. Hosting the Entire Domain................................17
11. IANA Considerations..........................................19 9.2. Distributed WebFinger Services...........................18
11.1. Registration of the "acct" Link Relation Type...........19 10. Web Host Metadata Interoperability Considerations............20
12. Acknowledgments..............................................19 11. Security Considerations......................................20
13. References...................................................19 12. IANA Considerations..........................................21
13.1. Normative References....................................19 12.1. Registration of the "acct" Link Relation Type...........21
13.2. Informative References..................................20 13. Acknowledgments..............................................21
Author's Addresses...............................................21 14. References...................................................21
14.1. Normative References....................................21
14.2. Informative References..................................22
APPENDIX A: XRD Usage (Non-normative)............................24
A.1. How XRD Documents are Requested via WebFinger............24
A.2. WebFinger Example using XRDs.............................24
A.3. Security Considerations Related to XRDs..................25
Author's Addresses...............................................26
1. Introduction 1. Introduction
There is a utility found on UNIX systems called "finger" [14] that There is a utility found on UNIX systems called "finger" [14] that
allows a person to access information about another person. The allows a person to access information about another person or entity
information being queried might be on a computer anywhere in the that has a UNIX account. The information queried might be on the
world. The information returned via "finger" is simply a plain text same computer or a computer anywhere in the world. What is returned
file that contains unstructured information provided by the queried via "finger" is simply a plain text file that contains unstructured
user. information provided by the queried user, stored in a file named
.plan in the user's home directory.
WebFinger borrows the concept of the legacy finger protocol, but WebFinger borrows the concept of the legacy finger protocol, but
introduces a very different approach to sharing information. Rather introduces a very different approach to sharing information. Rather
than returning a simple unstructured text file, Webfinger uses than return a simple unstructured text file, Webfinger uses
structured documents that contain link relations. These link structured documents that contain link relations. These link
relations point to information a user or entity on the Internet relations point to information and might return properties related to
wishes to expose. For a person, the kinds of information that might information a user or entity on the Internet wishes to expose. For a
be exposed include a personal profile address, identity service, person, the kinds of information that might be exposed include a
telephone number, or preferred avatar. WebFinger may also be used to personal profile address, identity service, telephone number, or
learn information about objects on the network, such as the amount of preferred avatar. WebFinger may also be used to discover information
toner in a printer or the physical location of a server. about objects on the network, such as the amount of toner in a
printer or the physical location of a server.
Information returned via WebFinger might be for direct human Information returned via WebFinger might be for direct human
consumption (e.g., another user's phone number) or it might be used consumption (e.g., another user's phone number) or it might be used
by systems to help carry out some operation (e.g., facilitate logging by systems to help carry out some operation (e.g., facilitate logging
into a web site by determining a user's identification service). into a web site by determining a user's identity service).
2. Terminology 2. Terminology
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
"SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this
document are to be interpreted as described in RFC 2119 [1]. document are to be interpreted as described in RFC 2119 [1].
WebFinger makes heavy use of "Link Relations". Briefly, a Link WebFinger makes heavy use of "Link Relations". Briefly, a Link
Relation is an attribute and value pair used on the Internet wherein Relation is an attribute and value pair used on the Internet wherein
the attribute identifies the type of link to which the associated the attribute identifies the type of link to which the associated
value refers. In Hypertext Transfer Protocol (HTTP) [2] and Web value refers. In Hypertext Transfer Protocol (HTTP) [2] and Web
Linking Error! Reference source not found., the attribute is a "rel" Linking [4], the attribute is a "rel" and the value is an "href".
and the value is an "href".
3. Overview 3. Overview
WebFinger enables the discovery of information about accounts, WebFinger enables the discovery of information about accounts,
devices, and other entities that are associated with web-accessible devices, and other entities that are associated with a host.
domains. In essence, there are two steps to discovering such Discover involves two distinct steps that may be optimized as a
information: single step, as will be explained later. The first step is to query
the host to find out how to discover information about accounts,
devices, and other entities associated with that host. The second
step is to query explicitly for a specific resource (e.g., user
account) to discover a set of link relations that point to resource-
specific information about the entity being queried.
1. By querying the domain itself, one can find out how to discover This protocol makes heavy use of well-known URIs as defined in RFC
information about accounts, devices, and other associated with 5785 [3] and "Link Relations" as defined in RFC 5988 [4]. Further,
that domain. the protocol builds on RFC 6415 [11], which provides the foundation
2. By then querying an entity at the domain, one will find links to for the procedures described in this document.
more detailed information, which can then be queried individually.
To enable such functionality, WebFinger makes heavy use of well-known Briefly, a link is a typed connection between two web resources that
URIs as defined in RFC 5785 [3] and "Link Relations" as defined in are identified by Internationalized Resource Identifiers (IRIs) [13];
RFC 5988 [3]. Briefly, a link is a typed connection between two web this connection consists of a context IRI, a link relation type, a
resources that are identified by Internationalized Resource target IRI, and optionally some target attributes, resulting in
Identifiers (IRIs) [13]; this connection consists of a context IRI, a statements of the form "{context IRI} has a {relation type} resource
link relation type, a target IRI, and optionally some target at {target IRI}, which has {target attributes}". When used in the
attributes, resulting in statements of the form "{context IRI} has a Link HTTP header, the context IRI is the IRI of the requested
{relation type} resource at {target IRI}, which has {target resource, the relation type is the value of the "rel" parameter, the
attributes}". When used in the Link HTTP header, the context IRI is target IRI is URI-Reference contained in the Link header, and the
the IRI of the requested resource, the relation type is the value of target attributes are the parameters such as "hreflang", "media",
the "rel" parameter, the target IRI is URI-Reference contained in the "title", "title*", "type", and any other link-extension parameters.
Link header, and the target attributes are the parameters such as
"hreflang", "media", "title", "title*", "type", and any other link-
extension parameters.
Thus the framework for WebFinger consists of several building blocks: Thus the framework for WebFinger consists of several building blocks:
1. To query the domain, one requests a web host metadata file [11] 1. To query the host, one requests a web host metadata document
located at a well-known URI of /.well-known/host-meta at the located at the well-known URI /.well-known/host-meta or /.well-
domain of interest. known/host-meta.json (referred to as the host-meta resources) at
2. The web server at the domain returns an Extensible Resource the host.
Descriptor (XRD) or a JavaScript Object Notation (JSON) Resource 2. The web server at the host returns a JavaScript Object Notation
Descriptor (JRD) document, including a Link-based Resource (JSON) [5] Resource Descriptor (JRD) or an Extensible Resource
Descriptor (XRD) [10] document, including a Link-based Resource
Descriptor Document (LRDD) link relation. Descriptor Document (LRDD) link relation.
3. To discover information about accounts, devices, or other entities 3. To discover information about accounts, devices, or other entities
associated with the domain, one requests the actual Link-based associated with the host, one requests the actual Link-based
Resource Descriptor Document associated with a particular URI at Resource Descriptor Document associated with a particular URI at
the domain (e.g., an 'acct' URI, 'http' URI', or 'mailto' URI). the host (e.g., an "acct" URI, "http" URI, or "mailto" URI).
4. The web server at the domain returns an XRD or JRD document about 4. The web server at the host returns a JRD or XRD document for the
the requested URI, which includes specialized link relations requested URI, which includes link relations pointing to resources
pointing to resources that contain more detailed information about that contain more detailed information about the entity.
the entity.
This model is illustrated in the examples under Section 4, then This model is illustrated in the examples in Section 4, then
described more formally under Section 5. Note that steps 2 and 3 described more formally in Section 5. Steps 2 and 3 above can be
above may be accomplished simultaneously by utilizing the "resource" accomplished simultaneously by utilizing the "resource" parameter
parameter defined in Section 5.2. defined in Section 5.2.
4. Example Uses of WebFinger 4. Example Uses of WebFinger
In this section, we describe just a few sample uses for WebFinger and In this section, we describe just a few sample uses for WebFinger and
show what the protocol looks like. This is not an exhaustive list of show what the protocol looks like. This is not an exhaustive list of
possible uses and the entire section should be considered non- possible uses and the entire section should be considered non-
normative. The list of potential use cases is virtually unlimited normative. The list of potential use cases is virtually unlimited
since a user can share any kind of machine-consumable information via since a user can share any kind of machine-consumable information via
WebFinger. WebFinger.
All of the following examples utilize JRDs, as that is the only
mandatory format required to be supported by WebFinger servers. For
completeness, an example utilizing XRDs is presented in Appendix A.
4.1. Locating a User's Blog 4.1. Locating a User's Blog
Assume you receive an email from Bob and he refers to something he Assume you receive an email from Bob and he refers to something he
posted on his blog, but you do not know where Bob's blog is located. posted on his blog, but you do not know where Bob's blog is located.
It would be simple to discover the address of Bob's blog if he makes It would be simple to discover the address of Bob's blog if he makes
that information available via WebFinger. that information available via WebFinger.
Let's assume your email client discovers that blog automatically for Let's assume your email client discovers that blog automatically for
you. After receiving the message from Bob (bob@example.com), your you. After receiving the message from Bob (bob@example.com), your
email client performs the following steps behind the scenes. email client performs the following steps behind the scenes.
First, it tries to get the host metadata [11] information for the First, your email client tries to get the host metadata information
domain example.com. It does this by issuing the following HTTPS for the host example.com. It does this by issuing the following
query to example.com: HTTPS query to example.com:
GET /.well-known/host-meta HTTP/1.1 GET /.well-known/host-meta.json HTTP/1.1
Host: example.com Host: example.com
The server replies with an XRD [10] document: The server replies with a JRD document:
HTTP/1.1 200 OK HTTP/1.1 200 OK
Access-Control-Allow-Origin: * Access-Control-Allow-Origin: *
Content-Type: application/xrd+xml; charset=UTF-8 Content-Type: application/json; charset=UTF-8
<?xml version="1.0" encoding="UTF-8"?> {
<XRD xmlns="http://docs.oasis-open.org/ns/xri/xrd-1.0"> "links" :
<Link rel="lrdd" [
type="application/xrd+xml" {
template="https://example.com/lrdd/?uri={uri}"/> "rel" : "lrdd",
</XRD> "type" : "application/json",
"template" : "https://example.com/lrdd/?f=json&uri={uri}"
}
]
}
The client then processes the received XRD in accordance with the Web The client then processes the received JRD in accordance with the Web
Host Metadata [11] procedures. The client will see the LRDD link Host Metadata procedures. The client will see the LRDD link relation
relation and issue a query with the user's account URI [6] or other and issue a query with the user's account URI [6] or other URI that
URI that serves as an alias for the account. (The account URI is serves as an alias for the account. (The account URI is discussed in
discussed in Section 4.2.) The query might look like this: Section 4.2.) The query might look like this:
GET /lrdd/?uri=acct%3Abob%40example.com HTTP/1.1 GET /lrdd/?f=json&uri=acct%3Abob%40example.com HTTP/1.1
Host: example.com Host: example.com
The server might then respond with a message like this: The server might then respond with a message like this:
HTTP/1.1 200 OK HTTP/1.1 200 OK
Access-Control-Allow-Origin: * Access-Control-Allow-Origin: *
Content-Type: application/xrd+xml; charset=UTF-8
<?xml version="1.0" encoding="UTF-8"?>
<XRD xmlns="http://docs.oasis-open.org/ns/xri/xrd-1.0">
<Expires>2012-03-13T20:56:11Z</Expires>
<Subject>acct:bob@example.com</Subject>
<Alias>http://www.example.com/~bob/</Alias>
<Link rel="http://webfinger.net/rel/avatar"
href="http://www.example.com/~bob/bob.jpg"/>
<Link rel="http://webfinger.net/rel/profile-page"
href="http://www.example.com/~bob/"/>
<Link rel="http://packetizer.com/rel/blog"
href="http://blogs.example.com/bob/"/>
</XRD>
The email client might take note of the "blog" link relation in the
above XRD document that refers to Bob's blog. This URL would then be
presented to you so that you could then visit his blog.
The email client might also note that Bob has published an avatar
link relation and use that picture to represent Bob inside the email
client.
Note in the above example that an alias is provided that can also be
used to return information about the user's account. Had the "http:"
URI been used to query for information about Bob, the query would
have appeared as:
GET /lrdd/?uri= http%3A%2F%2Fwww.example.com%2F~bob%2F HTTP/1.1
Host: example.com
The response would have been substantially the same, with the subject
and alias information changed as necessary. Other information, such
as the expiration time might also change, but the set of link
relations and properties would be the same with either response.
Let's assume, though, that for the above query the client requested a
JRD representation for the resource rather than an XRD
representation. In that case, the response would have been:
HTTP/1.1 200 OK
Access-Control-Allow-Origin: *
Content-Type: application/json; charset=UTF-8 Content-Type: application/json; charset=UTF-8
{ {
"expires" : "2012-03-13T20:56:11Z", "expires" : "2012-10-12T20:56:11Z",
"subject" : "http://www.example.com/~bob/", "subject" : "acct:bob@example.com",
"aliases" : "aliases" :
[ [
"acct:bob@example.com" "http://www.example.com/~bob/"
], ],
"links" : "links" :
[ [
{ {
"rel" : "http://webfinger.net/rel/avatar", "rel" : "http://webfinger.net/rel/avatar",
"href" : "http://www.example.com/~bob/bob.jpg" "href" : "http://www.example.com/~bob/bob.jpg"
}, },
{ {
"rel" : "http://webfinger.net/rel/profile-page", "rel" : "http://webfinger.net/rel/profile-page",
"href" : "http://www.example.com/~bob/" "href" : "http://www.example.com/~bob/"
}, },
{ {
"rel" : "http://packetizer.com/rel/blog", "rel" : "http://packetizer.com/rel/blog",
"href" : "http://blogs.example.com/bob/" "href" : "http://blogs.example.com/bob/"
} },
]
}
4.2. Retrieving a Person's Contact Information
Assume you have Alice in your address book, but her phone number
appears to be invalid. You could use WebFinger to find her current
phone number and update your address book.
Let's assume you have a web-based address book that you wish to
update. When you instruct the address book to pull Alice's current
contact information, the address book might issue a query like this
to get host metadata information for example.com:
GET /.well-known/host-meta.json HTTP/1.1
Host: example.com
Note the address book is looking for a JSON [5] representation,
whereas we used XML in the previous example.
The server might reply with something like this:
HTTP/1.1 200 OK
Access-Control-Allow-Origin: *
Content-Type: application/json; charset=UTF-8
{
"links" :
[
{ {
"rel" : "lrdd", "rel" : "vcard",
"type" : "application/json", "href" : "http://www.example.com/~bob/bob.vcf"
"template" :
"https://example.com/lrdd/?format=json&uri={uri}"
} }
] ]
} }
The client processes the response as described in RFC 6415 [11]. It The email client might take note of the "blog" link relation in the
will process the LRDD link relation using Alice's account URI by above JRD document that refers to Bob's blog. This URL would then be
issuing this query: presented to you so that you could then visit his blog. The email
client might also note that Bob has published an avatar link relation
GET /lrdd/?format=json&uri=acct%3Aalice%40example.com HTTP/1.1 and use that picture to represent Bob inside the email client.
Host: example.com Lastly, the client might consider the vcard [16] link relation in
order to update contact information for Bob.
The server might return a response like this:
HTTP/1.1 200 OK Note in the above example that an alias is provided that can also be
Access-Control-Allow-Origin: * used to return information about the user's account. Had the "http:"
Content-Type: application/json; charset=UTF-8 URI shown as an alias been used to query for information about Bob,
the query would have appeared as:
{ GET /lrdd/?uri=http%3A%2F%2Fwww.example.com%2F~bob%2F HTTP/1.1
"expires" : "2012-03-13T20:56:11Z", Host: example.com
"subject" : "acct:alice@example.com",
"links" :
[
{
"rel" : "http://webfinger.net/rel/avatar",
"href" : "http://example.com/~alice/alice.jpg"
},
{
"rel" : "vcard",
"href" : "http://example.com/~alice/alice.vcf"
}
]
}
With this response, the address book might see the vcard [16] link The response would have been substantially the same, with the subject
relation and use that file to offer you updated contact information. and alias information changed as necessary. Other information, such
as the expiration time might also change, but the set of link
relations and properties would be the same with either response.
4.3. Simplifying the Login Process 4.2. Simplifying the Login Process
OpenID (http://www.openid.net) is great for allowing users to log OpenID (http://www.openid.net) is great for allowing users to log
into a web site, though one criticism is that it is challenging for into a web site, though one criticism is that it is challenging for
users to remember the URI they are assigned. WebFinger can help users to remember the URI they are assigned. WebFinger can help
address this issue by allowing users to use user@domain-style address this issue by allowing users to use user@domain-style
addresses. Using a user's account URI, a web site can perform a addresses. Using a user's account URI, a web site can perform a
query to discover the associated OpenID identifier for a user. query to discover the associated OpenID identifier for a user.
Let's assume Carol is trying to use OpenID to log into a blog. The Let's assume Carol is trying to use OpenID to log into a blog. The
blog server might issue the following query to get the host metadata blog server might issue the following query to discover the OpenID
information: identity provider URL for Carol and to get Carol's avatar. In this
example, we utilize the "rel" and "resource" parameters as described
in sections 5.2 and 5.3:
GET /.well-known/host-meta.json HTTP/1.1 GET /.well-known/host-meta.json?\
rel=avatar%20\
http%3A%3F%3Fspecs.openid.net%3Fauth%3F2.0%3Fprovider&\
resource=acct%3Acarol%40example.com HTTP/1.1
Host: example.com Host: example.com
The response that comes back is similar to the previous example:
HTTP/1.1 200 OK
Access-Control-Allow-Origin: *
Content-Type: application/json; charset=UTF-8
{
"expires" : "2012-03-13T20:56:11Z",
"links" :
[
{
"rel" : "lrdd",
"type" : "application/json",
"template" :
"https://example.com/lrdd/?format=json&uri={uri}"
}
]
}
The blog server processes the response as described in RFC 6415. It
will process the LRDD link relation using Carol's account URI by
issuing this query:
GET /lrdd/?format=json&uri=acct%3Acarol%40example.com HTTP/1.1
The server might return a response like this: The server might return a response like this:
HTTP/1.1 200 OK HTTP/1.1 200 OK
Access-Control-Allow-Origin: * Access-Control-Allow-Origin: *
Content-Type: application/json; charset=UTF-8 Content-Type: application/json; charset=UTF-8
{ {
"subject" : "acct:carol@example.com", "subject" : "acct:carol@example.com",
"links" : "links" :
[ [
skipping to change at page 9, line 37 skipping to change at page 7, line 49
}, },
{ {
"rel" : "http://specs.openid.net/auth/2.0/provider", "rel" : "http://specs.openid.net/auth/2.0/provider",
"href" : "https://openid.example.com/carol" "href" : "https://openid.example.com/carol"
} }
] ]
} }
At this point, the blog server knows that Carol's OpenID identifier At this point, the blog server knows that Carol's OpenID identifier
is https://openid.example.com/carol and could then proceed with the is https://openid.example.com/carol and could then proceed with the
login process as usual. login process as usual. Her avatar can also be displayed for the
benefit of other users on the blog.
4.4. Retrieving Device Information 4.3. Retrieving Device Information
While the examples thus far have been focused on information about While the examples thus far have been focused on information about
humans, WebFinger does not limit queries to only those that use the humans, WebFinger does not limit queries to only those that use the
account URI scheme. Any URI scheme that contains domain information account URI scheme. Any URI scheme that contains host information
MAY be used with WebFinger. Let's suppose there are devices on the MAY be used with WebFinger. Let's suppose there are devices on the
network like printers and you would like to check the current toner network like printers and you would like to check the current toner
level for a particular printer identified via the URI like level for a particular printer identified via the URI like
device:p1.example.com. While the "device" URI scheme is not device:p1.example.com. While the "device" URI scheme is not
presently specified, we use it here for illustrative purposes. presently specified, we use it here only for illustrative purposes.
Following the procedures similar to those above, a query may be Following the procedures similar to those above, a query may be
issued to get link relations specific to this URI like this: issued to get link relations specific to this URI like this:
GET /lrdd/?format=json&uri=device%3Ap1.example.com HTTP/1.1 GET /.well-known/host-meta.json?resource=\
device%3Ap1.example.com HTTP/1.1
Host: example.com Host: example.com
The link relations that are returned may be quite different than The link relations that are returned may be quite different than
those for user accounts. Perhaps we may see a response like this: those for user accounts. Perhaps we may see a response like this:
HTTP/1.1 200 OK HTTP/1.1 200 OK
Access-Control-Allow-Origin: * Access-Control-Allow-Origin: *
Content-Type: application/json; charset=UTF-8 Content-Type: application/json; charset=UTF-8
{ {
skipping to change at page 10, line 35 skipping to change at page 8, line 50
While this example is entirely fictitious, you can imagine that While this example is entirely fictitious, you can imagine that
perhaps the Transport Independent, Printer/System Interface [18] may perhaps the Transport Independent, Printer/System Interface [18] may
be enhanced with a web interface that allows a device that be enhanced with a web interface that allows a device that
understands the TIP/SI web interface specification to query the understands the TIP/SI web interface specification to query the
printer for toner levels. printer for toner levels.
5. WebFinger Protocol 5. WebFinger Protocol
WebFinger does not actually introduce a new protocol, per se. WebFinger does not actually introduce a new protocol, per se.
Rather, it builds upon the existing Web Host Metadata [11] Rather, it builds upon the existing Web Host Metadata specification
specification and leverages the Cross-Origin Resource Sharing (CORS) and leverages the Cross-Origin Resource Sharing (CORS) [9]
[9] specification. specification.
While WebFinger strives to maintain backward-compatibility with RFC
6415, this specification introduces a fundamental change in
requirements. Specifically, support for server-side production of
JSON Resource Descriptor (JRD) documents is mandatory and support for
server-side production Extensible Resource Descriptor (XRD) documents
is optional. Please refer to Section 10 for interoperability
considerations.
5.1. Performing a WebFinger Query 5.1. Performing a WebFinger Query
The first step a client must perform in executing a WebFinger query The first step a client performs in executing a WebFinger query is to
is to query for the host metadata using HTTPS or HTTP. The query for the host metadata using HTTPS or HTTP. The procedures are
procedures are defined in the Web Host Metadata [11] specification. defined in the Web Host Metadata specification. It is strongly
RECOMMENDED that WebFinger servers return content using secure
(HTTPS) connections. Clients MUST first attempt queries using HTTPS
before attempting a query using HTTP.
WebFinger clients MUST locate the LRDD link relation, if present, and WebFinger clients MUST locate the LRDD link relation and perform a
perform a query for that link relation, if present. All other link query for that link relation, if present. All other link templates
templates found must be processed to form a complete resource found must be processed to form a complete resource descriptor. The
descriptor. The processing rules in Section 4.2 of RFC 6415 MUST be processing rules in Section 4.2 of RFC 6415 MUST be followed.
followed.
WebFinger servers MUST accept requests for both XRD [10] and JRD [11] WebFinger servers MAY accept requests for both JRD and XRD documents,
documents. The default representation returned by the server MUST be but MUST support requests for JRD documents. For interoperability
an XRD document, but a JRD document MUST be returned if the client with RFC 6415 implementations, the default representation returned by
explicitly requests it by using /.well-known/host-meta.json or a server via the resource at /.well-known/host-meta MUST be an XRD
includes an Accept header in the HTTP request with a type of document if XRD is supported by the server and a JRD document is not
"application/json" [5]. explicitly requested by the client. The default format returned via
the resource /.well-known/host-meta.json MUST be a JRD document.
As per RFC 6415, a JRD document MUST be returned by the WebFinger
server if the client explicitly requests it by querying /.well-
known/host-meta.json or by querying /.well-known/host-meta and
including an "Accept" header in the HTTP request with a type of
"application/json" [5]. Additionally, the server MUST return a JRD
document if it does not support production of XRD documents (or any
other format requested by the client). Servers MUST indicate the
type of document returned using the "Content-Type" header in the HTTP
response.
To avoid the possibility of receiving the wrong document format,
WebFinger clients SHOULD submit queries to the server via the /.well-
known/host-meta.json resource.
If the client requests a JRD document when querying for host If the client requests a JRD document when querying for host
metadata, the WebFinger server can assume that the client will want a metadata, the WebFinger server MUST assume that the client will want
JRD documents when querying the LRDD resource. As such, when the a JRD document when querying the LRDD resource. Thus when the
WebFinger server returns a JRD document containing host metadata it WebFinger server returns a JRD document containing host metadata that
should include a URI for an LRDD resource that can return a JRD contains an LRDD link relation, it MUST include a URI for the LRDD
document and MAY include a URI for an LRDD resource that will return resource(s) that will return a JRD document. Likewise, if a client
an XRD document. requests an XRD document when querying the host metadata resource,
the server MUST, unless unable due to external factors, return LRDD
link relations that would return XRD documents.
It is important to note that unless the "resource" parameter is used
as per section 5.2, it is the responsibility of the client to process
each of the LRDD link relations as per Section 4.2 of RFC 6415 if a
server returns multiple LRDD link relations. Multiple LRDD link
relations in a server response do not represent alternative URIs for
the same LRDD document.
If the client queries the LRDD resource and provides a URI for which If the client queries the LRDD resource and provides a URI for which
the server has no information, the server MUST return a 404 status the server has no information, the server MUST return a 404 status
code. Likewise, any query to a URI in the resource descriptor that code. Likewise, any query to a URI in the resource descriptor that
is unknown to the server MUST result in the server returning a 404 is unknown to the server MUST result in the server returning a 404
status code. status code.
WebFinger servers MAY include cache validators in a response to WebFinger servers MAY include cache validators in a response to
enable conditional requests by clients and/or expiration times as per enable conditional requests by clients and/or expiration times as per
RFC 2616 section 13. RFC 2616 section 13.
5.2. The Web Host Metadata "resource" Parameter 5.2. The Web Host Metadata "resource" Parameter
In addition to the normal processing logic for processing host In addition to the traditional processing logic for processing host
metadata information, WebFinger defines the "resource" parameter for metadata information, WebFinger defines the "resource" parameter for
querying for host metadata and returning all of the link relations querying for host metadata and returning all of the link relations
from LRDD and other resource-specific link templates in a single from LRDD and other resource-specific link templates in a single
query. This resource essentially pushes the work to the server to response. This parameter essentially pushes the work to the server
form a complete resource descriptor for the specified resource. to form a complete resource descriptor for the specified resource.
WebFinger servers compliant with this specification MUST support for WebFinger servers compliant with this specification MUST support for
the "resource" parameter as a means of improving performance and the "resource" parameter as a means of improving performance and
reducing client complexity. Note that an RFC 6415-compliant server reducing client complexity. Note that an RFC 6415-compliant server
might not implement the "resource" parameter, though the server would might not implement the "resource" parameter, though the server would
respond to queries from the client as described in RFC 6415. Thus, respond to queries from the client as described in RFC 6415. Thus,
WebFinger clients MUST check the server response to ensure that the WebFinger clients MUST check the server response to ensure that the
"resource" parameter is supported as explained below. "resource" parameter is supported as explained below.
To utilize the host-meta "resource" parameter, a WebFinger client To utilize the host-meta "resource" parameter, a WebFinger client
issues a request to /.well-known/host-meta or /.well-known/host- issues a request to /.well-known/host-meta.json (RECOMMENDED) or
meta.json as usual, but then appends a "resource" parameter as shown /.well-known/host-meta as usual, but then appends a "resource"
in this example: parameter as shown in this example:
GET /.well-known/host-meta.json?resource=\ GET /.well-known/host-meta.json?resource=\
acct%3Abob%40example.com HTTP/1.1 acct%3Abob%40example.com HTTP/1.1
Host: example.com Host: example.com
Note that the "\" character shown above is to indicate that the line
breaks at this point and continues on the next line. This was shown
only to avoid line wrapping in this document and is not a part of the
HTTP protocol.
When processing this request, the WebFinger server MUST When processing this request, the WebFinger server MUST
* Return a 404 status code if the URI provided in the resource * Return a 404 status code if the URI provided in the resource
parameter is unknown to the server; and parameter is unknown to the server; and
* Set the "Subject" returned in the response to the value of the * Set the "Subject" returned in the response to the value of the
"resource" parameter if the URI provided in the resource "resource" parameter if the URI provided in the resource
parameter is known to the server parameter is known to the server; and
The WebFinger client can verify support for the "resource" parameter * Collect and expand all resource-specific link relations,
including those returned by querying for any LRDD link
relations, discard any host-wide link relations, and return a
complete resource descriptor following the processing rules in
Section 4.2 of RFC 6415; and
The WebFinger server MUST NOT issue HTTP queries for any link
relations other than LRDD link relations. It is not the
responsibility of the WebFinger server to verify, for example, that a
URI pointing to a person's avatar is a valid URI. When querying an
LRDD resource to collect additional resource-specific information,
any errors (e.g., 500 or 404) MUST be ignored by the server. When a
request for an LRDD fails, the server MUST NOT attempt to augment
missing resource information or return a "template" type link
relation to a client that utilizes the "resource" parameter.
The WebFinger client MUST verify support for the "resource" parameter
by checking the value of the Subject returned in the response. If by checking the value of the Subject returned in the response. If
the Subject matches the value of the "resource" parameter, then the the Subject matches the value of the "resource" parameter, then the
"resource" parameter is supported by the server. "resource" parameter is supported by the server. The Subject would
be absent if the "resource" parameter is not supported.
For illustrative purposes, the following is an example usage of the For illustrative purposes, the following is an example usage of the
"resource" parameter that aligns with the example in Section 1.1.1 of "resource" parameter that aligns with the example in Section 1.1.1 of
RFC 6415. The WebFinger client would issue this request: RFC 6415. The WebFinger client would issue this request:
GET /.well-known/host-meta.json?resource=\ GET /.well-known/host-meta.json?resource=\
http%3A%2F%2Fexample.com%2Fxy HTTP/1.1 http%3A%2F%2Fexample.com%2Fxy HTTP/1.1
Host: example.com Host: example.com
Note: The "\" character shown above and used throughout this document
indicates that the line breaks at this point and continues on the
next line. The content of the next line should be concatenated to
the previous line without any whitespace characters, replacing the
"\" character. This is shown only to avoid line wrapping in this
document.
The WebFinger server would reply with this response: The WebFinger server would reply with this response:
HTTP/1.1 200 OK HTTP/1.1 200 OK
Access-Control-Allow-Origin: * Access-Control-Allow-Origin: *
Content-Type: application/json; charset=UTF-8 Content-Type: application/json; charset=UTF-8
{ {
"subject" : "http://example.com/xy", "subject" : "http://example.com/xy",
"properties" : "properties" :
{ {
"http://spec.example.net/color" : "red" "http://spec.example.net/color" : "red"
}, },
"links" : "links" :
[ [
{ {
"rel" : "hub", "rel" : "hub",
skipping to change at page 13, line 19 skipping to change at page 12, line 35
"rel" : "author", "rel" : "author",
"href" : "http://example.com/author?\ "href" : "http://example.com/author?\
q=http%3A%2F%2Fexample.com%2Fxy" q=http%3A%2F%2Fexample.com%2Fxy"
} }
] ]
} }
5.3. The Web Host Metadata "rel" Parameter 5.3. The Web Host Metadata "rel" Parameter
WebFinger also defines the "rel" parameter for use when querying for WebFinger also defines the "rel" parameter for use when querying for
host metadata. It is used to return a subset of the information that host metadata or resource-specific information. It is used to return
would otherwise be returned without the "rel" parameter. When the a subset of the information that would otherwise be returned without
"rel" parameter is used, only the link relations that match the the "rel" parameter. When the "rel" parameter is used, only the link
space-separated list of link relations provided via "rel" are relations that match the space-separated list of link relations
included in the list of links returned in the resource descriptor. provided via "rel" are included in the list of links returned in the
All other information normally present in a resource descriptor is resource descriptor. All other information normally present in a
present in the resource descriptor, even when "rel" is employed. resource descriptor is present in the resource descriptor, even when
"rel" is employed.
The purpose of the "rel" parameter is to return a subset of The purpose of the "rel" parameter is to return a subset of
resource's link relations. It is not intended to reduce the work resource's link relations. It is not intended to reduce the work
required of a server to produce a response. That said, use of the required of a server to produce a response. That said, use of the
parameter might reduce processing requirements on either the client parameter might reduce processing requirements on either the client
or server, and it might also reduce the bandwidth required to convey or server, and it might also reduce the bandwidth required to convey
the partial resource descriptor, especially if there are numerous the partial resource descriptor, especially if there are numerous
link relation values to convey for a given resource. link relation values to convey for a given resource.
Support for the "rel" parameter is OPTIONAL, but support is Support for the "rel" parameter is OPTIONAL, but support is
RECOMMENDED for both the host-meta resource and the LRDD resource. RECOMMENDED for the host-meta resources and LRDD resources.
For illustrative purposes, the following is an example usage of the For illustrative purposes, the following is an example usage of the
"rel" parameter that aligns with the example in Section 1.1.1 of RFC "rel" parameter that aligns with the example in Section 1.1.1 of RFC
6415. The WebFinger client would issue this request to receive links 6415. The WebFinger client would issue this request to receive links
that are of the type "hub" and "copyright": that are of the type "hub" and "copyright":
GET /.well-known/host-meta.json?resource=\ GET /.well-known/host-meta.json?resource=\
http%3A%2F%2Fexample.com%2Fxy&rel=hub%20copyright HTTP/1.1 http%3A%2F%2Fexample.com%2Fxy&rel=hub%20copyright HTTP/1.1
Host: example.com Host: example.com
skipping to change at page 14, line 33 skipping to change at page 13, line 52
Note that in this example, the "author" links are removed, though all Note that in this example, the "author" links are removed, though all
other content is present. Since there were no "copyright" links, other content is present. Since there were no "copyright" links,
none are returned. none are returned.
In the event that a client requests links for link relations that are In the event that a client requests links for link relations that are
not defined for the specified resource, a resource descriptor MUST be not defined for the specified resource, a resource descriptor MUST be
returned, void of any links. When a JRD is returned, the "links" returned, void of any links. When a JRD is returned, the "links"
array MAY be either absent or empty. The server MUST NOT return a array MAY be either absent or empty. The server MUST NOT return a
404 status code when a particular link relation specified via "rel" 404 status code when a particular link relation specified via "rel"
is not defined for the resource, as a 404 status code is reserved for is not defined for the resource, as a 404 status code is reserved for
indicating that the resource itself (e.g., as indicated via the indicating that the resource itself (e.g., either /.well-known/host-
"resource" parameter) does not exist. meta.json or the resource indicated via the "resource" parameter)
does not exist.
5.4. WebFinger and URIs 5.4. WebFinger and URIs
Requests for both LRDD documents and hostmeta files can include a Requests for both LRDD documents and host metadata can include a
parameter specifying the URI of an account, device, or other entity parameter specifying the URI of an account, device, or other entity
(for LRDD this is the "uri" parameter as defined by the operative XRD (for LRDD this is the "uri" parameter as defined by the operative JRD
or JRD template, for hostmeta this is the "resource" parameter). or XRD template and for host metadata this is the "resource"
WebFinger itself is agnostic regarding the scheme of such a URI: it parameter). WebFinger itself is agnostic regarding the scheme of
could be an "acct" URI as defined in the next section, an "http" or such a URI: it could be an "acct" URI [7], an "http" or "https" URI,
"https" URI, a "mailto" URI, or some other scheme. a "mailto" URI, or some other scheme.
For resources associated with a user account at a domain, use of the For resources associated with a user account at a host, use of the
"acct" URI scheme [7] is RECOMMENDED, since it explicitly identifies "acct" URI scheme is RECOMMENDED, since it explicitly identifies an
an account accessible via WebFinger. Further, the "acct" URI scheme account accessible via WebFinger. Further, the "acct" URI scheme is
is not associated other protocols as, by way of example, the "mailto" not associated with other protocols as, by way of example, the
URI scheme is associated with email. Since not every domain offers "mailto" URI scheme is associated with email. Since not every host
email service, using the "mailto" URI scheme [8] is not ideal for offers email service, using the "mailto" URI scheme [8] is not ideal
identifying user accounts across all domains. That said, use of the for identifying user accounts on all hosts. That said, use of the
"mailto" URI scheme would be ideal for use with WebFinger to discover "mailto" URI scheme would be ideal for use with WebFinger to discover
mail server configuration information for a user, for example. mail server configuration information for a user, for example.
A domain MAY utilize one or more URIs that serve as aliases for the A host MAY utilize one or more URIs that serve as aliases for the
user's account, such as URIs that use the "http" URI scheme [2]. A user's account, such as URIs that use the "http" URI scheme [2]. A
WebFinger server MUST return substantially the same response to both WebFinger server MUST return substantially the same response to both
an "acct" URI and any alias URI for the account, including the same an "acct" URI and any alias URI for the account, including the same
set of link relations and properties. In addition, the server SHOULD set of link relations and properties. In addition, the server SHOULD
include the entire list aliases for the user's account in the XRD or include the entire list aliases for the user's account in the JRD or
JRD. XRD returned when querying the LRDD resource or when utilizing the
"resource" parameter.
6. The "acct" Link Relation 6. The "acct" Link Relation
6.1. Purpose for the "acct" Link Relation 6.1. Purpose for the "acct" Link Relation
Users of some services might have an "acct" URI that looks Users of some services might have an "acct" URI that looks
significantly different from his or her email address, perhaps using significantly different from his or her email address, perhaps using
an entirely different domain name. It is also possible for a user to an entirely different domain name. It is also possible for a user to
have multiple accounts that a user wants to have cross-referenced have multiple accounts that a user wants to have cross-referenced
from another account. To address both of these needs, this from another account. To address both of these needs, this
specification defines the "acct" link relation. specification defines the "acct" link relation.
The "acct" link relation allows a WebFinger server to reference one The "acct" link relation allows a resource descriptor to reference
or more other user account URIs from within a user account. The one or more other user account URIs. The "acct" link relation is
"acct" link relation is intended to allow a client to incorporate intended to allow a client to incorporate additional link relations
additional link relations by reference to produce a complete set of by reference so that it might utilize a more complete set of link
link relations for a user. Any newly discovered link relations found relations for a user. For example, a user acct:bob@example.com might
by querying the referenced account SHOULD be merged into the resource wish to allow a client to discover additional information about him
descriptor document at the point where the "acct" link relation was by including an "acct" link relation with the URI
inserted. acct:bob@example.net.
Note that the "acct" link relation does not replace the use of Note that the "acct" link relation does not replace the use of
standard HTTP 3xx response codes to indicate the new temporary or standard HTTP 3xx response codes to indicate the new temporary or
permanent location of a user account. If a user account is moved to permanent location of a user account. If a user account is moved to
a different location, then a 3xx response code SHOULD be used. a different location, then a 3xx response code SHOULD be used. Also,
the "acct" link relation does not replace Link-based Resource
Descriptor Documents (LRDDs). A WebFinger server might return
multiple LRDD link relations for a user, each of which perhaps
containing link relations that are to be merged to form a complete
resource descriptor. The "acct" link relation is different in that
it would refer to an entirely different, separate resource
descriptor. Further, only a client would act consider the "acct"
link relations as it performs queries, not the WebFinger server.
Since an account may make a reference to one or more different Since an account may make a reference to one or more different
accounts, WebFinger clients MUST take steps to avoid loops wherein accounts, WebFinger clients that support automatic processing of the
two account URIs, directly or indirectly, refer the client to each "acct" link relations MUST take steps to avoid loops wherein two
other. account URIs, directly or indirectly, refer the client to each other.
There are no limits on the number of "acct" link relations that might There are no limits on the number of "acct" link relations that might
be returned in a WebFinger query. be returned in a WebFinger query.
An "acct" link relation used within the context of a WebFinger query An "acct" link relation used within the context of a WebFinger query
for a user's account MUST NOT return "acct" link relations for for a user's account MUST NOT return "acct" link relations for
another user. another user.
Client-side consideration of the "acct" link relation is OPTIONAL and
WebFinger server MUST NOT assume a client will perform additional
processing in response to receiving an "acct" link relation.
6.2. Example Message Exchange Using the "acct" Link Relation 6.2. Example Message Exchange Using the "acct" Link Relation
Consider the following non-normative example. Consider the following non-normative example.
Suppose Alice receives an email from bob@example.net. While Bob's Suppose Alice receives an email from bob@example.net. While Bob's
email identifier might be in the example.net domain, he holds a user email identifier might be in the example.net domain, he holds a user
account in the example.com domain and another account in the account in the example.com domain and another account in the
example.org domain. His email provider may provide WebFinger example.org domain. His email provider may provide WebFinger
services to enable redirecting Alice when she queries for services, but is unable to serve information from other domains.
acct:bob@example.net.
Suppose Alice's client issues the following request: Suppose Alice's client issues the following request:
GET /.well-known/host-meta.json?resource=\ GET /.well-known/host-meta.json?resource=\
acct%3Abob%40example.net HTTP/1.1 acct%3Abob%40example.net HTTP/1.1
Host: example.net Host: example.net
The response that Alice's client receives back might be: The response that Alice's client receives back might be:
HTTP/1.1 200 OK HTTP/1.1 200 OK
skipping to change at page 16, line 40 skipping to change at page 16, line 21
"links" : "links" :
[ [
{ {
"rel" : "acct", "rel" : "acct",
"href" : "acct:bob@example.com" "href" : "acct:bob@example.com"
}, },
{ {
"rel" : "acct", "rel" : "acct",
"href" : "acct:bob@example.org" "href" : "acct:bob@example.org"
}, },
{ {
"rel" : "acct", "rel" : "acct",
"href" : "mailto:bob@example.net" "href" : "mailto:bob@example.net"
} }
] ]
} }
Alice's WebFinger client could then perform queries against the URIs While these link relations provide Alice with very little
acct:bob@example.com, acct:bob@example.org, and information, Alice's WebFinger client could then perform subsequent
mailto:bob@example.net in order to get the information Alice is queries against the URIs acct:bob@example.com, acct:bob@example.org,
and mailto:bob@example.net in order to get the information Alice is
seeking. seeking.
7. Cross-Origin Resource Sharing (CORS) 7. Cross-Origin Resource Sharing (CORS)
WebFinger is most useful when it is accessible without restrictions WebFinger is most useful when it is accessible without restrictions
on the Internet, and that includes web browsers. Therefore, on the Internet, and that includes web browsers. Therefore,
WebFinger servers MUST support Cross-Origin Resource Sharing (CORS) WebFinger servers MUST support Cross-Origin Resource Sharing (CORS)
[9] when serving content intended for public consumption. [9] when serving content intended for public consumption.
Specifically, all queries to /.well-known/host-meta, /.well- Specifically, all queries to /.well-known/host-meta.json, /.well-
known/host-meta.json, and to the LRDD URI must include the following known/host-meta, and to any LRDD URIs MUST include the following HTTP
HTTP header in the response: header in the response:
Access-Control-Allow-Origin: * Access-Control-Allow-Origin: *
Enterprise WebFinger servers that wish to restrict access to Enterprise WebFinger servers that wish to restrict access to
information from external entities SHOULD use a more restrictive information from external entities SHOULD use a more restrictive
Access-Control-Allow-Origin header and MAY exclude the header Access-Control-Allow-Origin header and MAY exclude the header
entirely. entirely.
8. Controlling Access to Information 8. Controlling Access to Information
skipping to change at page 17, line 42 skipping to change at page 17, line 25
or outside a corporate network. As a concrete example, a query or outside a corporate network. As a concrete example, a query
performed on the internal corporate network might return link performed on the internal corporate network might return link
relations to employee pictures whereas link relations for employee relations to employee pictures whereas link relations for employee
pictures might not be provided to external entities. pictures might not be provided to external entities.
Further, link relations provided in a WebFinger server response MAY Further, link relations provided in a WebFinger server response MAY
point to web resources that impose access restrictions. For example, point to web resources that impose access restrictions. For example,
it is possible that the aforementioned corporate server may provide it is possible that the aforementioned corporate server may provide
both internal and external entities with URIs to employee pictures, both internal and external entities with URIs to employee pictures,
but further authentication MAY be required in order for the WebFinger but further authentication MAY be required in order for the WebFinger
client to access those resources if the request comes from outside client to access those picture resources if the request comes from
the corporate network. outside the corporate network.
The decisions made with respect to what set of link relations a The decisions made with respect to what set of link relations a
WebFinger server provides to one client versus another and what WebFinger server provides to one client versus another and what
resources require further authentication, as well as the specific resources require further authentication, as well as the specific
authentication mechanisms employed, are outside the scope of this authentication mechanisms employed, are outside the scope of this
document. document.
9. Implementation Notes (Non-Normative) 9. Hosted and Distributed WebFinger Services
A user should not be required to enter the "acct" URI scheme name 9.1. Hosting the Entire Domain
along with his account identifier into any WebFinger client. Rather,
the WebFinger client should accept identifiers that are void of the
"acct:" portion of the identifier. Composing a properly formatted
"acct" URI is the responsibility of the WebFinger client.
10. Security Considerations As with most services provided on the Internet, it is possible for a
domain owner to utilize "hosted" WebFinger services. By way of
example, a domain owner might control most aspects of their domain,
but use a third-party hosting service email. In the case of email,
mail servers for a domain are identified by MX records. An MX record
points to the mail server to which mail for the domain should be
delivered. It does not matter to the sending mail server whether
those MX records point to a server in the destination domain or a
different domain.
Likewise, a domain owner might utilize the services of a third party
to provide WebFinger services on behalf of its users. Just as a
domain owner was required to insert MX records into DNS to allow for
hosted email serves, the domain owner is required to redirect HTTP(S)
queries to its domain to allow for hosted WebFinger services.
When a query is issued to /.well-known/host-meta.json or /.well-
known/host-meta, the target domain's web server MUST return a 301,
302, or 307 response status code that includes a Location header
pointing to the location of the hosted WebFinger service URL. The
WebFinger service URL does not need to point to /.well-known/* on the
hosting service provider server. In fact, it should not, as that
location would be reserved for queries relating to the service
provider's domain. WebFinger clients MUST follow all 301, 302, or
307 redirection requests.
As an example, let's assume that example.com's WebFinger services are
hosted by example.net. Suppose a client issues a query for
acct:alice@example.com like this:
GET /.well-known/host-meta.json?
resource=acct%3Aalice%40example.com HTTP/1.1
Host: example.com
The server might respond with this:
HTTP/1.1 301 Moved Permanently
Location: http://wf.example.net/example.org/host-meta.json
The client should follow the request, re-issuing the request to the
URL provided in the Location header.
Note that both of the /.well-known/host-meta.json and /.well-
known/host-meta resources need to be considered when redirecting
request to third party service providers. Those URLs requests SHOULD
NOT be redirected to the same location and without any
differentiation, since the default format returned by host-meta.json
is a JRD and the default format returned by host-meta MAY be XRD.
Each resource is distinct and should be redirected separately and to
different service locations or differentiated with a URI parameter.
Since the "Referer" HTTP header field is not mandatory, service
providers cannot rely on that header to determine the URL of the
original request.
9.2. Distributed WebFinger Services
A domain owner may wish to manage only a part of its WebFinger
services and WebFinger service providers or the domain owner may wish
to distribute WebFinger services across a number of WebFinger service
locations. The key to enabling this type of distribution is
placement of resource-specific information in more than one LRDD
document, each document existing at different locations.
Assume that the company operating example.com manages its own
WebFinger services, but also wants to utilize the services of
example.org to serve link relations related to some aspects of its
business. Suppose a client issued this request:
GET /.well-known/host-meta.json HTTP/1.1
Host: example.com
The server might reply with this JRD document:
HTTP/1.1 200 OK
Access-Control-Allow-Origin: *
Content-Type: application/json; charset=UTF-8
{
"links" :
[
{
"rel" : "lrdd",
"type" : "application/json",
"template" : "https://example.com/lrdd/?f=json&uri={uri}"
},
{
"rel" : "lrdd",
"type" : "application/json",
"template" : "https://wf.example.org/lrdd/?f=json&uri={uri}"
}
]
}
This would indicate to the client that some of the resource-specific
information is found at example.com and some is found at example.org,
following those specific URLs. Observing the rules in Section 4.2 of
RFC 6415, the client would issue queries to both URLs and construct a
complete resource descriptor.
As discussed in Section 5.2, a client may issue a query like this to
the example.com domain:
GET /.well-known/host-meta.json?resource=\
acct%3Aalice%40example.com HTTP/1.1
Host: example.com
In that case, it would be the responsibility of the WebFinger server
at example.com to query the LRDD URL at example.org and then compose
a complete descriptor document. The client that uses the resource
parameter remains entirely oblivious to the fact that link relation
information is distributed across multiple servers or domains.
10. Web Host Metadata Interoperability Considerations
As noted in Section 3, RFC 6415 required all servers to support the
production of Extensible Resource Documents (XRDs) and optionally
support the production of JSON Resource Documents (JRDs). This
specification reverses that requirement: WebFinger-compliant servers
MUST support JRD and MAY support XRD documents.
Given that some servers might implement only RFC 6415 and other
servers might implement only the minimum required set of features
defined for WebFinger, all clients should take care to ensure to
request a resource descriptor in the appropriate format. If a client
wishes to receive only JRDs, for example, it SHOULD issue a request
to /.well-known/host-meta.json, but MAY issue a request to /.well-
known/host-meta and include the "Accept" header with the type
"application/json".
Further, clients MUST ensure that the response returned from the
server contains the correct format. RFC 6415-compliant servers might
return an XRD document, regardless of what is requested by the
client.
Lastly, RFC 6415 did not require clients to follow 301, 302, or 307
redirection requests, but WebFinger clients MUST re-issue requests
when redirected using any of those HTTP status codes.
11. Security Considerations
All of the security considerations applicable to Web Host Metadata All of the security considerations applicable to Web Host Metadata
[11] and Cross-Origin Resource Sharing [9] are also applicable to and Cross-Origin Resource Sharing [9] are also applicable to this
this specification. Of particular importance is the recommended use specification. Of particular importance is the recommended use of
of HTTPS to ensure that information is not modified during transit. HTTPS to ensure that information is not modified during transit.
Clients should verify that the certificate used on an HTTPS Clients SHOULD verify that the certificate used on an HTTPS
connection is valid. connection is valid.
When using HTTP to request an XRD document, WebFinger clients SHOULD
verify the XRD document's signature, if present, to ensure that the
XRD document has not been modified. Additionally, WebFinger servers
SHOULD include a signature for XRD documents served over HTTP.
Service providers and users should be aware that placing information Service providers and users should be aware that placing information
on the Internet accessible through WebFinger means that any user can on the Internet accessible through WebFinger means that any user can
access that information. While WebFinger can be an extremely useful access that information. While WebFinger can be an extremely useful
tool for allowing quick and easy access to one's avatar, blog, or tool for allowing quick and easy access to one's avatar, blog, or
other personal information, users should understand the risks, too. other personal information, users should understand the risks, too.
If one does not wish to share certain information with the world, do If one does not wish to share certain information with the world, do
not allow that information to be freely accessible through WebFinger. not allow that information to be freely accessible through WebFinger.
The aforementioned word of caution is perhaps worth emphasizing again The aforementioned word of caution is perhaps worth emphasizing again
with respect to dynamic information one might wish to share, such as with respect to dynamic information one might wish to share, such as
skipping to change at page 19, line 7 skipping to change at page 21, line 19
of the protocol, not a limitation. If one wishes to limit access to of the protocol, not a limitation. If one wishes to limit access to
information available via WebFinger, such as a WebFinger server for information available via WebFinger, such as a WebFinger server for
use inside a corporate network, the network administrator must take use inside a corporate network, the network administrator must take
measures necessary to limit access from outside the network. Using measures necessary to limit access from outside the network. Using
standard methods for securing web resources, network administrators standard methods for securing web resources, network administrators
do have the ability to control access to resources that might return do have the ability to control access to resources that might return
sensitive information. Further, WebFinger servers can be employed in sensitive information. Further, WebFinger servers can be employed in
such a way as to require authentication and prevent disclosure of such a way as to require authentication and prevent disclosure of
information to unauthorized entities. information to unauthorized entities.
11. IANA Considerations 12. IANA Considerations
RFC Editor: Please replace QQQQ in the following two sub-sections RFC Editor: Please replace QQQQ in the following two sub-sections
with a reference to this RFC. with a reference to this RFC.
11.1. Registration of the "acct" Link Relation Type 12.1. Registration of the "acct" Link Relation Type
Relation Name: acct Relation Name: acct
Description: A link relation that refers to a user's WebFinger Description: A link relation that refers to a user's WebFinger
account identifier. account identifier.
Reference: RFC QQQQ Reference: RFC QQQQ
Notes: Notes:
Application Data: Application Data:
12. Acknowledgments 13. Acknowledgments
The authors would like to acknowledge Eran Hammer-Lahav, Blaine Cook, The authors would like to acknowledge Eran Hammer-Lahav, Blaine Cook,
Brad Fitzpatrick, Laurent-Walter Goix, Joe Clarke, Mike Jones, and Brad Fitzpatrick, Laurent-Walter Goix, Joe Clarke, Mike Jones, and
Peter Saint-Andre for their invaluable input. Peter Saint-Andre for their invaluable input.
13. References 14. References
13.1. Normative References 14.1. Normative References
[1] Bradner, S., "Key words for use in RFCs to Indicate Requirement [1] Bradner, S., "Key words for use in RFCs to Indicate Requirement
Levels", BCP 14, RFC 2119, March 1997. Levels", BCP 14, RFC 2119, March 1997.
[2] Fielding, R., Gettys, J., Mogul, J., Frystyk, H., [2] Fielding, R., Gettys, J., Mogul, J., Frystyk, H.,
Masinter, L., Leach, P., and T. Berners-Lee, "Hypertext Masinter, L., Leach, P., and T. Berners-Lee, "Hypertext
Transfer Protocol -- HTTP/1.1", RFC 2616, June 1999. Transfer Protocol -- HTTP/1.1", RFC 2616, June 1999.
[3] Nottingham, M., Hammer-Lahav, E., "Defining Well-Known Uniform [3] Nottingham, M., Hammer-Lahav, E., "Defining Well-Known Uniform
Resource Identifiers (URIs)", RFC 5785, April 2010. Resource Identifiers (URIs)", RFC 5785, April 2010.
[4] Nottingham, M., "Web Linking", RFC 5988, October 2010. [4] Nottingham, M., "Web Linking", RFC 5988, October 2010.
[5] Crockford, D., "The application/json Media Type for [5] Crockford, D., "The application/json Media Type for
JavaScript Object Notation (JSON)", RFC 4627, July 2006. JavaScript Object Notation (JSON)", RFC 4627, July 2006.
[6] Berners-Lee, T., Fielding, R., and Masinter, L., "Uniform [6] Berners-Lee, T., Fielding, R., and Masinter, L., "Uniform
Resource Identifier (URI): Generic Syntax", STD 66, RFC 3986, Resource Identifier (URI): Generic Syntax", STD 66, RFC 3986,
January 2005. January 2005.
[7] Saint-Andre, P., "The 'acct' URI Scheme", draft-saintandre- [7] Saint-Andre, P., "The 'acct' URI Scheme", draft-ietf-appsawg-
acct-uri-01, July 2012. acct-uri-00, August 2012.
[8] Duerst, M., Masinter, L., and J. Zawinski, "The 'mailto' URI [8] Duerst, M., Masinter, L., and J. Zawinski, "The 'mailto' URI
Scheme", RFC 6068, October 2010. Scheme", RFC 6068, October 2010.
[9] Van Kesteren, A., "Cross-Origin Resource Sharing", W3C CORS [9] Van Kesteren, A., "Cross-Origin Resource Sharing", W3C CORS
http://www.w3.org/TR/cors/, July 2010. http://www.w3.org/TR/cors/, July 2010.
[10] Hammer-Lahav, E. and W. Norris, "Extensible Resource Descriptor [10] Hammer-Lahav, E. and W. Norris, "Extensible Resource Descriptor
(XRD) Version 1.0", http://docs.oasis- (XRD) Version 1.0", http://docs.oasis-
open.org/xri/xrd/v1.0/xrd-1.0.html. open.org/xri/xrd/v1.0/xrd-1.0.html.
skipping to change at page 20, line 28 skipping to change at page 22, line 40
[11] Hammer-Lahav, E. and Cook, B., "Web Host Metadata", RFC 6415, [11] Hammer-Lahav, E. and Cook, B., "Web Host Metadata", RFC 6415,
October 2011. October 2011.
[12] American National Standards Institute, "Coded Character Set - [12] American National Standards Institute, "Coded Character Set -
7-bit American Standard Code for Information Interchange", ANSI 7-bit American Standard Code for Information Interchange", ANSI
X3.4, 1986. X3.4, 1986.
[13] Duerst, M., "Internationalized Resource Identifiers (IRIs)", [13] Duerst, M., "Internationalized Resource Identifiers (IRIs)",
RFC 3987, January 2005. RFC 3987, January 2005.
13.2. Informative References 14.2. Informative References
[14] Zimmerman, D., "The Finger User Information Protocol", RFC [14] Zimmerman, D., "The Finger User Information Protocol", RFC
1288, December 1991. 1288, December 1991.
[15] Hansen, T., Hardie, T., and L. Masinter, "Guidelines and [15] Hansen, T., Hardie, T., and L. Masinter, "Guidelines and
Registration Procedures for New URI Schemes", BCP 35, RFC 4395, Registration Procedures for New URI Schemes", BCP 35, RFC 4395,
February 2006. February 2006.
[16] Perreault, S., "vCard Format Specification", RFC 6350, August [16] Perreault, S., "vCard Format Specification", RFC 6350, August
2011. 2011.
skipping to change at page 21, line 5 skipping to change at page 24, line 5
[17] Internet Assigned Numbers Authority (IANA) Registry, "Uniform [17] Internet Assigned Numbers Authority (IANA) Registry, "Uniform
Resource Identifier (URI) Schemes", Resource Identifier (URI) Schemes",
<http://www.iana.org/assignments/uri-schemes.html>. <http://www.iana.org/assignments/uri-schemes.html>.
[18] "Transport Independent, Printer/System Interface", IEEE Std [18] "Transport Independent, Printer/System Interface", IEEE Std
1284.1-1997, 1997. 1284.1-1997, 1997.
[19] Hoffman, P., Yergeau, F., "UTF-16, an encoding of ISO 10646", [19] Hoffman, P., Yergeau, F., "UTF-16, an encoding of ISO 10646",
RFC 2781, February 2000. RFC 2781, February 2000.
APPENDIX A: XRD Usage (Non-normative)
A.1. How XRD Documents are Requested via WebFinger
The framework for using XRD documents with WebFinger is as follows:
1. WebFinger clients issue request for XRD documents by requesting
the Web Host Metadata document located at the well-known URI
/.well-known/host-meta at the host.
2. The web server at the host returns an XRD document, including a
Link-based Resource Descriptor Document (LRDD) link relation.
3. To discover information about accounts, devices, or other
entities associated with the host, a request is issued for the
Link-based Resource Descriptor Document(s) associated with a
particular URI at the host (e.g., an "acct" URI, "http" URI, or
"mailto" URI).
4. The web server at the host would return an XRD document about
the requested URI, which included those resource-specific link
relations pointing to resources that contain information about
the entity.
5. Following the procedures in Section 4.2 of RFC 6415, the client
would assemble all of the resource-specific link relations from
the host-meta resource and LRDD resource(s) into a complete
resource descriptor.
The LRDD resources return resource descriptor documents of the type
"application/xrd+xml".
A.2. WebFinger Example using XRDs
Section 4 introduces examples where JRD documents are returned to
clients. For completeness, this section shows an example where a
client requests an XRD document.
Recall the example from Section 4.1 where the email client tried to
retrieve information about Bob to discover the URL for his blog. If
the client implemented support for XRD, it tries to get the host
metadata information for the domain example.com in a similar way. As
with the original example, it issues the following HTTPS query to
example.com:
GET /.well-known/host-meta HTTP/1.1
Host: example.com
The server replies with an XRD document:
HTTP/1.1 200 OK
Access-Control-Allow-Origin: *
Content-Type: application/xrd+xml; charset=UTF-8
<?xml version="1.0" encoding="UTF-8"?>
<XRD xmlns="http://docs.oasis-open.org/ns/xri/xrd-1.0">
<Link rel="lrdd"
type="application/xrd+xml"
template="https://example.com/lrdd/?uri={uri}"/>
</XRD>
The client then processes the received XRD in accordance with the Web
Host Metadata procedures. The client will see the LRDD link relation
and issue a query with the user's account URI [6] or other URI that
serves as an alias for the account. (The account URI is discussed in
Section 4.2.) The query might look like this:
GET /lrdd/?uri=acct%3Abob%40example.com HTTP/1.1
Host: example.com
The server might then respond with a message like this:
HTTP/1.1 200 OK
Access-Control-Allow-Origin: *
Content-Type: application/xrd+xml; charset=UTF-8
<?xml version="1.0" encoding="UTF-8"?>
<XRD xmlns="http://docs.oasis-open.org/ns/xri/xrd-1.0">
<Expires>2012-10-12T20:56:11Z</Expires>
<Subject>acct:bob@example.com</Subject>
<Alias>http://www.example.com/~bob/</Alias>
<Link rel="http://webfinger.net/rel/avatar"
href="http://www.example.com/~bob/bob.jpg"/>
<Link rel="http://webfinger.net/rel/profile-page"
href="http://www.example.com/~bob/"/>
<Link rel="http://packetizer.com/rel/blog"
href="http://blogs.example.com/bob/"/>
</XRD>
The email client might take note of the "blog" link relation in the
above XRD document that refers to Bob's blog. This URL would then be
presented to you so that you could then visit his blog.
A.3. Security Considerations Related to XRDs
When using HTTP to request an XRD document, WebFinger clients SHOULD
verify the XRD document's signature, if present, to ensure that the
XRD document has not been modified. Additionally, WebFinger servers
SHOULD include a signature for XRD documents served over HTTP.
Author's Addresses Author's Addresses
Paul E. Jones Paul E. Jones
Cisco Systems, Inc. Cisco Systems, Inc.
7025 Kit Creek Rd. 7025 Kit Creek Rd.
Research Triangle Park, NC 27709 Research Triangle Park, NC 27709
USA USA
Phone: +1 919 476 2048 Phone: +1 919 476 2048
Email: paulej@packetizer.com Email: paulej@packetizer.com
 End of changes. 93 change blocks. 
349 lines changed or deleted 554 lines changed or added

This html diff was produced by rfcdiff 1.41. The latest version is available from http://tools.ietf.org/tools/rfcdiff/