draft-ietf-appsawg-webfinger-03.txt   draft-ietf-appsawg-webfinger-04.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: May 16, 2013 Joseph Smarr Expires: May 21, 2013 Joseph Smarr
Google Google
November 16, 2012 November 21, 2012
WebFinger WebFinger
draft-ietf-appsawg-webfinger-03.txt draft-ietf-appsawg-webfinger-04.txt
Abstract Abstract
This specification defines the WebFinger protocol, which can be used This specification defines the WebFinger protocol, which can be used
to discover information about people or other entities on the to discover information about people or other entities on the
Internet using standard HTTP methods. Internet using standard HTTP methods.
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
skipping to change at page 1, line 34 skipping to change at page 1, line 34
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 May 16, 2013. This Internet-Draft will expire on May 21, 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 11 skipping to change at page 2, line 11
include Simplified BSD License text as described in Section 4.e of include Simplified BSD License text as described in Section 4.e of
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 Use of WebFinger.......................................3 4. Example Use of WebFinger.......................................3
4.1. Locating a User's Blog....................................4 4.1. Locating a User's Blog....................................3
4.2. Auto-Configuration of Email Clients.......................5 4.2. Auto-Configuration of Email Clients.......................5
4.3. Retrieving Device Information.............................6 4.3. Retrieving Device Information.............................7
5. WebFinger Protocol.............................................7 5. WebFinger Protocol.............................................8
5.1. Performing a WebFinger Query..............................7 5.1. Performing a WebFinger Query..............................8
5.2. The JSON Resource Descriptor (JRD) Document...............8 5.2. The JSON Resource Descriptor (JRD) Document...............9
5.3. The "rel" Parameter.......................................8 5.3. The "rel" Parameter.......................................9
5.4. WebFinger and URIs.......................................10 5.4. WebFinger and URIs.......................................11
6. Cross-Origin Resource Sharing (CORS)..........................10 6. Cross-Origin Resource Sharing (CORS)..........................12
7. Controlling Access to Information.............................11 7. Controlling Access to Information.............................12
8. Hosted WebFinger Services.....................................11 8. Hosted WebFinger Services.....................................13
9. Security Considerations.......................................12 9. Security Considerations.......................................14
10. IANA Considerations..........................................13 10. IANA Considerations..........................................15
11. Acknowledgments..............................................14 11. Acknowledgments..............................................16
12. References...................................................14 12. References...................................................16
12.1. Normative References....................................14 12.1. Normative References....................................16
12.2. Informative References..................................15 12.2. Informative References..................................16
Author's Addresses...............................................16 Author's Addresses...............................................17
1. Introduction 1. Introduction
There is a utility found on UNIX systems called "finger" [12] that There is a utility found on UNIX systems called "finger" [12] that
allows a person to access information about another person or entity allows a person to access information about another person or entity
that has a UNIX account. The information queried might be on the that has a UNIX account. The information queried might be on the
same computer or a computer anywhere in the world. What is returned same computer or a computer anywhere in the world. What is returned
via "finger" is a plain text file that contains unstructured via "finger" is a plain text file that contains unstructured
information provided by the queried user, stored in a file named information provided by the queried user, stored in a file named
.plan in the user's home directory. .plan in the user's home directory.
skipping to change at page 3, line 20 skipping to change at page 3, line 20
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) and Web Linking value refers. In Hypertext Transfer Protocol (HTTP) and Web Linking
[4], the attribute is a "rel" and the value is an "href". [4], the attribute is a "rel" and the value is an "href". WebFinger
also uses the "rel" attribute, where the "rel" value is either a
single IANA-registered link relation type [12] or a URI [6].
3. Overview 3. Overview
WebFinger enables the discovery of information about users, devices, WebFinger enables the discovery of information about users, devices,
and other entities that are associated with a host. Discovery and other entities that are associated with a host. Discovery
involves a single HTTP GET request to the well-known [3] "webfinger" involves a single HTTP GET request to the well-known [3] "webfinger"
resource at the target host and receiving back a JavaScript Object resource at the target host and receiving back a JavaScript Object
Notation (JSON) [5] Resource Descriptor (JRD) document [11] Notation (JSON) [5] Resource Descriptor (JRD) document [11]
containing link relations. The request MUST include the URI [6] or containing link relations. The request MUST include the URI or IRI
IRI [7] for the entity for which information is sought as a parameter [7] for the entity for which information is sought as a parameter
named "resource". named "resource".
Briefly, a link is a typed connection between two web resources that
are identified by Internationalized Resource Identifiers (IRIs); this
connection consists of a context IRI, a link relation type, a target
IRI, and optionally some target attributes, resulting in statements
of the form "{context IRI} has a {relation type} resource at {target
IRI}, which has {target attributes}". When used in the Link HTTP
header, the context IRI is the IRI of the requested resource, the
relation type is the value of the "rel" parameter, the target IRI is
URI-Reference contained in the Link header, and the target attributes
are the parameters such as "hreflang", "media", "title", "title*",
"type", and any other link-extension parameters.
Use of WebFinger is illustrated in the examples in Section 4, then Use of WebFinger is illustrated in the examples in Section 4, then
described more formally in Section 5. described more formally in Section 5.
4. Example Use of WebFinger 4. Example Use of WebFinger
In this section, we show a few samples using WebFinger so you can see In this section, we show a few samples using WebFinger so you can see
what the protocol looks like. This is not an exhaustive list of 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 is non-normative.
normative.
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 can discover the blog for you. After Let's assume your email client can discover the blog for you. After
receiving the message from Bob (bob@example.com), you instruct your receiving the message from Bob (bob@example.com), you instruct your
skipping to change at page 4, line 50 skipping to change at page 4, line 40
{ {
"rel" : "http://webfinger.net/rel/avatar", "rel" : "http://webfinger.net/rel/avatar",
"type" : "image/jpeg", "type" : "image/jpeg",
"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" : "blog",
"type" : "text/html", "type" : "text/html",
"href" : "http://blogs.example.com/bob/", "href" : "http://blogs.example.com/bob/",
"properties" : "titles" :
{ {
"en-us" : "The Magical World of Bob", "en-us" : "The Magical World of Bob",
"fr" : "Le monde magique de Bob" "fr" : "Le monde magique de Bob"
} }
}, },
{ {
"rel" : "vcard", "rel" : "vcard",
"href" : "http://www.example.com/~bob/bob.vcf" "href" : "http://www.example.com/~bob/bob.vcf"
} }
] ]
} }
The email client would take note of the The email client would take note of the
"http://packetizer.com/rel/blog" link relation in the above JRD "http://packetizer.com/rel/blog" link relation in the above JRD
document that refers to Bob's blog. This URL would then be presented 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 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 also note that Bob has published an avatar link relation and use that
picture to represent Bob inside the email client. Lastly, the client picture to represent Bob inside the email client. Lastly, the client
might consider the vcard [13] link relation in order to update might consider the vcard [14] link relation in order to update
contact information for Bob. contact information for Bob.
In the above example, an "acct" URI [8] is used in the query, though In the above example, an "acct" URI [8] is used in the query, though
any valid alias for the user might also be used. Had the "http:" URI any valid alias for the user might also be used. An alias is a URI
that is different from the "subject" URI that identifies the same
entity. In the above example, there is one "http" alias returned,
though there might have been more than one. Had the "http:" URI
shown as an alias been used to query for information about Bob, the shown as an alias been used to query for information about Bob, the
query would have appeared as: query would have appeared as:
GET /.well-known/webfinger? GET /.well-known/webfinger?
resource=http%3A%2F%2Fwww.example.com%2F~bob%2F HTTP/1.1 resource=http%3A%2F%2Fwww.example.com%2F~bob%2F HTTP/1.1
Host: example.com Host: example.com
The response would have been substantially the same, with the subject The response would have been substantially the same, with the subject
and alias information changed as necessary. Other information, such and alias information changed as necessary. Other information, such
as the expiration time might also change, but the set of link as the expiration time might also change, but the set of link
relations and properties would be the same with either response. relations and properties would be the same with either response.
4.2. Auto-Configuration of Email Clients 4.2. Identity Provider Discovery for OpenID Connect
Suppose Carol wishes to authenticate with a web site she visits using
OpenID Connect [16]. She would provide the web site with her OpenID
Connect identifier, say carol@example.com. The visited web site
would perform a WebFinger query looking for the OpenID Connect
Provider. Since the site is interested in only one particular link
relation, the server might utilize the "rel" parameter as described
in section 5.3:
GET /.well-known/webfinger?
resource=acct%3Acarol%40example.com&
rel=http%3A%2F%2Fopenid.net%2Fspecs%2Fconnect%2F1.0%2Fissuer
HTTP/1.1
Host: example.com
The server might respond with a JSON Resource Descriptor document
like this:
{
"expires" : "2012-11-16T19:41:35Z",
"subject" : "acct:carol@example.com",
"aliases" :
[
"http://www.example.com/~carol/"
],
"properties" :
{
"http://example.com/rel/role/" : "employee"
},
"links" :
[
{
"rel" : "http://openid.net/specs/connect/1.0/issuer",
"href" : "https://openid.example.com/"
}
]
}
Since the "rel" parameter only filters the link relations returned by
the server, other elements of the response, including any aliases or
properties, would be returned. Also, since support for the "rel"
parameter is optional, the client must not assume the "links" array
will contain only the requested link relation.
4.3. Auto-Configuration of Email Clients
WebFinger could be used to auto-provision an email client with basic WebFinger could be used to auto-provision an email client with basic
configuration data. Suppose that sue@example.com wants to configure configuration data. Suppose that sue@example.com wants to configure
her email client. Her email client might issue the following query: her email client. Her email client might issue the following query:
GET /.well-known/webfinger? GET /.well-known/webfinger?
resource=mailto%3Asue%40example.com HTTP/1.1 resource=mailto%3Asue%40example.com HTTP/1.1
Host: example.com Host: example.com
The response from the server would contain entries for the various The response from the server would contain entries for the various
skipping to change at page 6, line 13 skipping to change at page 7, line 4
each of the valid options and the client or Sue might select which each of the valid options and the client or Sue might select which
option to choose. Since JRD documents list link relations in a option to choose. Since JRD documents list link relations in a
specific order, then the most-preferred choices could be presented specific order, then the most-preferred choices could be presented
first. Consider this response: first. Consider this response:
{ {
"subject" : "mailto:sue@example.com", "subject" : "mailto:sue@example.com",
"links" : "links" :
[ [
{ {
"rel" : "smtp-server", "rel" : "http://example.net/rel/smtp-server",
"properties" : "properties" :
{ {
"host" : "smtp.example.com", "host" : "smtp.example.com",
"port" : "587", "port" : "587",
"login-required" : "yes", "login-required" : "yes",
"transport" : "starttls" "transport" : "starttls"
} }
}, },
{ {
"rel" : "imap-server", "rel" : "http://example.net/rel/imap-server",
"properties" : "properties" :
{ {
"host" : "imap.example.com", "host" : "imap.example.com",
"port" : "993", "port" : "993",
"transport" : "ssl" "transport" : "ssl"
} }
} }
] ]
} }
In this example, you can see that the WebFinger server advertises an In this example, you can see that the WebFinger server advertises an
SMTP service and an IMAP service. In this example, the "href" SMTP service and an IMAP service. In this example, the "href"
entries associated with the link relation are absent. This is valid entries associated with the link relation are absent. This is valid
when there is no external reference that needs to be made. when there is no external reference that needs to be made.
4.3. Retrieving Device Information 4.4. Retrieving Device Information
As another example, let's suppose there are printers on the network As another example, let's suppose there are printers on the network
and you would like to check the current toner level for a particular and you would like to check the current toner level for a particular
printer identified via the URI device:p1.example.com. While the printer identified via the URI device:p1.example.com. While the
"device" URI scheme is not presently specified, we use it here for "device" URI scheme is not presently specified, we use it here for
illustrative purposes. 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:
skipping to change at page 7, line 12 skipping to change at page 8, line 4
device%3Ap1.example.com HTTP/1.1 device%3Ap1.example.com HTTP/1.1
Host: example.com Host: example.com
The link relations that are returned for a device may be quite The link relations that are returned for a device may be quite
different than those for user accounts. Perhaps we may see a different than those for user accounts. Perhaps we may see a
response like this: 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" : "device:p1.example.com", "subject" : "device:p1.example.com",
"links" : "links" :
[ [
{ {
"rel" : "tipsi", "rel" : "http://example.com/rel/tipsi",
"href" : "http://192.168.1.5/npap/" "href" : "http://192.168.1.5/npap/"
} }
] ]
} }
While this example is fictitious, you can imagine that perhaps the While this example is fictitious, you can imagine that perhaps the
Transport Independent, Printer/System Interface [14] may be enhanced Transport Independent, Printer/System Interface [15] may be enhanced
with a web interface that allows a device that understands the TIP/SI with a web interface that allows a device that understands the TIP/SI
web interface specification to query the printer for toner levels. web interface specification to query the printer for toner levels.
5. WebFinger Protocol 5. WebFinger Protocol
WebFinger is a simple HTTP-based web service that utilizes the JSON WebFinger is a simple HTTP-based web service that utilizes the JSON
Resource Descriptor (JRD) document format and the Cross-Origin Resource Descriptor (JRD) document format and the Cross-Origin
Resource Sharing (CORS) [10] specification. Resource Sharing (CORS) [10] specification.
5.1. Performing a WebFinger Query 5.1. Performing a WebFinger Query
skipping to change at page 9, line 22 skipping to change at page 10, line 13
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 RECOMMENDED on the Support for the "rel" parameter is OPTIONAL, but RECOMMENDED on the
server. server.
For illustrative purposes, the following example presents the same The following example presents the same example as found in section
example as found in section 4.1, but uses the "rel" parameter in 4.1, but uses the "rel" parameter in order to select two link
order to select two link relations: relations:
GET /.well-known/webfinger? GET /.well-known/webfinger?
resource=acct%3Abob%40example.com resource=acct%3Abob%40example.com&
rel=http%3A%2F%2Fwebfinger.net%2Frel%2Fprofile-page& rel=http%3A%2F%2Fwebfinger.net%2Frel%2Fprofile-page&
rel=vcard HTTP/1.1 rel=vcard HTTP/1.1
Host: example.com Host: example.com
The server might then respond with a message like this: In this example, the client requests the link relations of type
"http://webfinger.net/rel/profile-page" and "vcard". The server then
responds 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/json; charset=UTF-8 Content-Type: application/json; charset=UTF-8
{ {
"expires" : "2012-11-16T19:41:35Z", "expires" : "2012-11-16T19:41:35Z",
"subject" : "acct:bob@example.com", "subject" : "acct:bob@example.com",
"aliases" : "aliases" :
[ [
skipping to change at page 10, line 4 skipping to change at page 10, line 47
], ],
"properties" : "properties" :
{ {
"http://example.com/rel/role/" : "employee" "http://example.com/rel/role/" : "employee"
}, },
"links" : "links" :
[ [
{ {
"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" : "vcard", "rel" : "vcard",
"href" : "http://www.example.com/~bob/bob.vcf" "href" : "http://www.example.com/~bob/bob.vcf"
} }
] ]
} }
As you can see, the server returned only the link relations requested
by the client, but also included the other parts of the JSON resource
Descriptor document.
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. In the returned JRD, the "links" array MAY be absent, returned. In the returned JRD, the "links" array MAY be absent,
empty, or contain only links that did match a provided "rel" value. empty, or contain only links that did match a provided "rel" value.
The server MUST NOT return a 404 status code when a particular link The server MUST NOT return a 404 status code when a particular link
relation specified via "rel" is not defined for the resource, as a relation specified via "rel" is not defined for the resource, as a
404 status code is reserved for indicating that the resource itself 404 status code is reserved for indicating that the resource itself
(e.g., either /.well-known/webfinger or the resource indicated via (e.g., either /.well-known/webfinger or the resource indicated via
the "resource" parameter) does not exist. the "resource" parameter) does not exist.
skipping to change at page 10, line 44 skipping to change at page 11, line 43
"mailto" URI scheme is associated with email. Since not every host "mailto" URI scheme is associated with email. Since not every host
offers email service, using the "mailto" URI scheme [9] is not ideal offers email service, using the "mailto" URI scheme [9] is not ideal
for identifying user accounts on all hosts. 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. mail server configuration information for a user.
A host 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. The only elements in the set of link relations and properties. The only elements in the
response that MAY be different include "subject", "expires", and response that MAY be different include "subject", "expires", and
"aliases". In addition, the server SHOULD include the entire list "aliases". In addition, the server SHOULD include the entire list
aliases for the user's account in the JRD returned when querying the aliases for the user's account in the JRD returned when querying the
LRDD resource or when utilizing the "resource" parameter. LRDD resource or when utilizing the "resource" parameter.
5.5. "webfinger" Subdomain
It may be difficult or impossible for some hosts wanting to support
WebFinger requests to make a WebFinger server available for the host
at the path /.well-known/webfinger. For instance, in the case of
hosted domains, no web server may be running on the host at all.
For that reason, WebFinger servers for a host MAY be located on a
specific subdomain named "webfinger". For example, the WebFinger
server for the host example.com MAY be located at the URI
https://webfinger.example.com/.well-known/webfinger.
Note that a WebFinger service can operate on any host, such as
bldg6.hq.example.com. As such, the alternate location for the
WebFinger service in that example would be at the host named
webfinger.bldg6.hq.example.com.
WebFinger clients MUST first attempt to make a WebFinger request to
the host's /.well-known/webfinger endpoint, and then if that fails,
clients MUST then attempt to make the request to the WebFinger
endpoint at the "webfinger" subdomain of that host.
It should be appreciated that a 4xx, 5xx, or other status code from
the web server at the host indicates that a web server is operational
and such responses MUST NOT be considered a failure for the purposes
of this section. For the sake of operational efficiency, a client
MUST query the "webfinger" subdomain only if it has reason to believe
that a web server is not operating at the host, such as when there is
a failure to establish an HTTP(S) connection to the host.
6. Cross-Origin Resource Sharing (CORS) 6. 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, including web browsers. Therefore, WebFinger on the Internet, including web browsers. Therefore, WebFinger
servers MUST support Cross-Origin Resource Sharing (CORS) [10] when servers MUST support Cross-Origin Resource Sharing (CORS) [10] by
serving content intended for public consumption. Specifically, all including the following HTTP header in responses:
queries to /.well-known/webfinger MUST include the following HTTP
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. Access-Control-Allow-Origin header.
7. Controlling Access to Information 7. Access Control
As with all web resources, access to the /.well-known/webfinger As with all web resources, access to the /.well-known/webfinger
resource MAY require authentication. Further, failure to provide resource MAY require authentication. Further, failure to provide
required credentials MAY result in the server forbidding access or required credentials MAY result in the server forbidding access or
providing a different response than had the client authenticated with providing a different response than had the client authenticated with
the server. the server.
Likewise, a server MAY provide different responses to different Likewise, a server MAY provide different responses to different
clients based on other factors, such as whether the client is inside clients based on other factors, such as whether the client is inside
or outside a corporate network. As a concrete example, a query or outside a corporate network. As a concrete example, a query
skipping to change at page 12, line 11 skipping to change at page 13, line 39
email, mail servers for a domain are identified by MX records. An MX 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 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 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 those MX records point to a server in the destination domain or a
different domain. different domain.
Likewise, a domain owner might utilize the services of a third party Likewise, a domain owner might utilize the services of a third party
to provide WebFinger services on behalf of its users. Just as a 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 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) hosted email serves, the domain owner is required to redirect HTTP(S)
queries to its domain to allow for hosted WebFinger services. queries to its domain to allow for hosted WebFinger services (if a
web server is operating at the domain) or insert DNS records for the
"webfinger" subdomain described in section 5.5.
When a query is issued to /.well-known/webfinger, the target domain's When a query is issued to /.well-known/webfinger and the target host
web server MUST return a 301, 302, or 307 response status code that is operating a web server, the web server MUST return a 301, 302, or
includes a Location header pointing to the location of the hosted 307 response status code that includes a Location header pointing to
WebFinger service URL. The WebFinger service URL does not need to the location of the hosted WebFinger service URL. The WebFinger
point to /.well-known/* on the hosting service provider server. In service URL does not need to point to /.well-known/* on the hosting
fact, it should not, as that location would be reserved for queries service provider server. In fact, it should not, as that location
relating to the service provider's domain. WebFinger clients MUST would be reserved for queries relating to the service provider's
follow all 301, 302, or 307 redirection requests. 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 As an example, let's assume that example.com's WebFinger services are
hosted by example.net. Suppose a client issues a query for hosted by example.net. Suppose a client issues a query for
acct:alice@example.com like this: acct:alice@example.com like this:
GET /.well-known/webfinger? GET /.well-known/webfinger?
resource=acct%3Aalice%40example.com HTTP/1.1 resource=acct%3Aalice%40example.com HTTP/1.1
Host: example.com Host: example.com
The server might respond with this: The server might respond with this:
skipping to change at page 13, line 35 skipping to change at page 15, line 16
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.
Finally, a WebFinger server has no means of ensuring that information A WebFinger server has no means of ensuring that information provided
provided by a user is accurate. Likewise, neither the server nor the by a user is accurate. Likewise, neither the server nor the client
client can be absolutely guaranteed that information has not been can be absolutely guaranteed that information has not been
manipulated either at the server or along the communication path manipulated either at the server or along the communication path
between the client and server. Use of HTTPS helps to address some between the client and server. Use of HTTPS helps to address some
concerns with manipulation of information along the communication concerns with manipulation of information along the communication
path, but it clearly cannot address issues where the server provided path, but it clearly cannot address issues where the server provided
incorrect information, either due to being provided false information incorrect information, either due to being provided false information
or due to malicious behavior on the part of the server administrator. or due to malicious behavior on the part of the server administrator.
As with any information service available on the Internet, users As with any information service available on the Internet, users
should wary of information received from untrusted sources. should wary of information received from untrusted sources.
Because WebFinger requests for a host may be served by the
"webfinger" subdomain of the host, it should be ensured that the
"webfinger" subdomain is under the same administrative control as the
domain itself (just as one would typically expect that the "www"
subdomain should be controlled by the same authority as the domain
itself).
10. IANA Considerations 10. IANA Considerations
This specification registers the "webfinger" well-known URI in the This specification registers the "webfinger" well-known URI in the
Well-Known URI Registry as defined by [3]. Well-Known URI Registry as defined by [3].
URI suffix: webfinger URI suffix: webfinger
Change controller: IETF Change controller: IETF
Specification document(s): RFC QQQ Specification document(s): RFC QQQ
skipping to change at page 14, line 21 skipping to change at page 16, line 8
Related information: The JSON Resource Descriptor (JRD) documents Related information: The JSON Resource Descriptor (JRD) documents
obtained via the WebFinger web service are described in RFC 6415 obtained via the WebFinger web service are described in RFC 6415
Appendix A and RFC QQQ. Appendix A and RFC QQQ.
[RFC EDITOR: Please replace "QQQ" references in this section with the [RFC EDITOR: Please replace "QQQ" references in this section with the
number for this RFC.] number for this RFC.]
11. Acknowledgments 11. 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, Michael B. Jones,
Peter Saint-Andre for their invaluable input. and Peter Saint-Andre for their invaluable input.
12. References 12. References
12.1. Normative References 12.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
skipping to change at page 15, line 16 skipping to change at page 16, line 51
Scheme", RFC 6068, October 2010. Scheme", RFC 6068, October 2010.
[10] Van Kesteren, A., "Cross-Origin Resource Sharing", W3C CORS [10] 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.
[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.2. Informative References 12.2. Informative References
[12] Zimmerman, D., "The Finger User Information Protocol", RFC [12] IANA, "Link Relations", http://www.iana.org/assignments/link-
relations/.
[13] Zimmerman, D., "The Finger User Information Protocol", RFC
1288, December 1991. 1288, December 1991.
[13] Perreault, S., "vCard Format Specification", RFC 6350, August [14] Perreault, S., "vCard Format Specification", RFC 6350, August
2011. 2011.
[14] "Transport Independent, Printer/System Interface", IEEE Std [15] "Transport Independent, Printer/System Interface", IEEE Std
1284.1-1997, 1997. 1284.1-1997, 1997.
[16] Sakimura, N., Bradley, J., Jones, M., de Medeiros, B.,
Mortimore, C., and E. Jay, "OpenID Connect Messages 1.0", June
2012, http://openid.net/specs/openid-connect-messages-1_0.html.
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. 41 change blocks. 
79 lines changed or deleted 166 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/