draft-ietf-appsawg-webfinger-16.txt   draft-ietf-appsawg-webfinger-17.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 15, 2014 Joseph Smarr Expires: February 9, 2014 Joseph Smarr
Google Google
July 15, 2013 August 9, 2013
WebFinger WebFinger
draft-ietf-appsawg-webfinger-16.txt draft-ietf-appsawg-webfinger-17.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. WebFinger discovers Internet using standard HTTP methods. WebFinger discovers
information for a URI that might not be usable as a locator information for a URI that might not be usable as a locator
otherwise, such as account or email URIs. otherwise, such as account or email URIs.
Status of this Memo Status of this Memo
skipping to change at page 1, line 36 skipping to change at page 1, line 36
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 15, 2014. This Internet-Draft will expire on February 9, 2014.
Copyright Notice Copyright Notice
Copyright (c) 2013 IETF Trust and the persons identified as the Copyright (c) 2013 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
carefully, as they describe your rights and restrictions with respect carefully, as they describe your rights and restrictions with respect
to this document. Code Components extracted from this document must to this document. Code Components extracted from this document must
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. Example Uses of WebFinger......................................3 3. Example Uses of WebFinger......................................4
3.1. Identity Provider Discovery for OpenID Connect............3 3.1. Identity Provider Discovery for OpenID Connect............4
3.2. Getting Author and Copyright Information for a Web Page...4 3.2. Getting Author and Copyright Information for a Web Page...5
4. WebFinger Protocol.............................................5 4. WebFinger Protocol.............................................6
4.1. Constructing the Query Component of the Request URI.......6 4.1. Constructing the Query Component of the Request URI.......7
4.2. Performing a WebFinger Query..............................7 4.2. Performing a WebFinger Query..............................7
4.3. The "rel" Parameter.......................................8 4.3. The "rel" Parameter.......................................8
4.4. The JSON Resource Descriptor (JRD)........................9 4.4. The JSON Resource Descriptor (JRD).......................10
4.4.1. subject.............................................10 4.4.1. subject.............................................10
4.4.2. aliases.............................................10 4.4.2. aliases.............................................10
4.4.3. properties..........................................10 4.4.3. properties..........................................10
4.4.4. links...............................................10 4.4.4. links...............................................11
4.5. WebFinger and URIs.......................................12 4.5. WebFinger and URIs.......................................13
5. Cross-Origin Resource Sharing (CORS)..........................12 5. Cross-Origin Resource Sharing (CORS)..........................13
6. Access Control................................................13 6. Access Control................................................13
7. Hosted WebFinger Services.....................................13 7. Hosted WebFinger Services.....................................14
8. Security Considerations.......................................14 8. Definition of WebFinger Applications..........................15
8.1. Transport-Related Issues.................................14 8.1. Specification of the URI Scheme and URI..................15
8.2. User Privacy Considerations..............................15 8.2. Host Resolution..........................................15
8.3. Abuse Potential..........................................16 8.3. Specification of Properties..............................16
8.4. Information Reliability..................................17 8.4. Specification of Links...................................16
9. IANA Considerations...........................................17 8.5. One URI, Multiple Applications...........................16
9.1. Well-Known URI...........................................17 8.6. Registration of Link Relation Types and Properties.......17
9.2. JSON Resource Descriptor (JRD) Media Type................17 9. Security Considerations.......................................17
10. Acknowledgments..............................................19 9.1. Transport-Related Issues.................................17
11. References...................................................19 9.2. User Privacy Considerations..............................17
11.1. Normative References....................................19 9.3. Abuse Potential..........................................18
11.2. Informative References..................................20 9.4. Information Reliability..................................19
Author's Addresses...............................................21 10. IANA Considerations..........................................20
10.1. Well-Known URI..........................................20
10.2. JSON Resource Descriptor (JRD) Media Type...............20
10.3. Registering Link Relation Types.........................21
10.4. Establishment of the WebFinger Properties Registry......22
10.4.1. The Registration Template..........................22
10.4.2. The Registration Procedures........................22
11. Acknowledgments..............................................23
12. References...................................................23
12.1. Normative References....................................23
12.2. Informative References..................................24
Author's Addresses...............................................25
1. Introduction 1. Introduction
WebFinger is used to discover information about people or other WebFinger is used to discover information about people or other
entities on the Internet that are identified by a URI [6] or IRI [7] entities on the Internet that are identified by a URI [6] using
using standard Hypertext Transfer Protocol (HTTP) [2] methods over a standard Hypertext Transfer Protocol (HTTP) [2] methods over a secure
secure transport [13]. A WebFinger resource returns a JavaScript transport [12]. A WebFinger resource returns a JavaScript Object
Object Notation (JSON) [5] object describing the entity that is Notation (JSON) [5] object describing the entity that is queried.
queried. The JSON object is referred to as the JSON Resource The JSON object is referred to as the JSON Resource Descriptor (JRD).
Descriptor (JRD).
For a person, the kinds of information that might be discoverable via For a person, the kinds of information that might be discoverable via
WebFinger include a personal profile address, identity service, WebFinger include a personal profile address, identity service,
telephone number, or preferred avatar. For other entities on the telephone number, or preferred avatar. For other entities on the
Internet, a WebFinger resource might return JRDs containing link Internet, a WebFinger resource might return JRDs containing link
relations [9] that enable a client to discover, for example, the that relations [8] that enable a client to discover, for example, the that
a printer can print in color on A4 paper, the physical location of a a printer can print in color on A4 paper, the physical location of a
server, or other static information. server, or other static information.
Information returned via WebFinger might be for direct human Information returned via WebFinger might be for direct human
consumption (e.g., looking up someone's phone number), or it might be consumption (e.g., looking up someone's phone number), or it might be
used by systems to help carry out some operation (e.g., facilitate, used by systems to help carry out some operation (e.g., facilitate,
with additional security mechanisms, logging into a web site by with additional security mechanisms, logging into a web site by
determining a user's identity service). The information is intended determining a user's identity service). The information is intended
to be static in nature and, as such, WebFinger is not intended to be to be static in nature and, as such, WebFinger is not intended to be
used to return dynamic information like the temperature of a CPU or used to return dynamic information like the temperature of a CPU or
skipping to change at page 3, line 42 skipping to change at page 3, line 52
information specified in the value. In Web Linking [4], the link information specified in the value. In Web Linking [4], the link
relation is represented using an HTTP entity-header of "Link", where relation is represented using an HTTP entity-header of "Link", where
the "rel" attribute specifies the type of relationship and the "href" the "rel" attribute specifies the type of relationship and the "href"
attribute specifies the information that is linked to the entity or attribute specifies the information that is linked to the entity or
resource. In WebFinger, the same concept is represented using a JSON resource. In WebFinger, the same concept is represented using a JSON
array of "links" objects, where each member named "rel" specifies the array of "links" objects, where each member named "rel" specifies the
type of relationship and each member named "href" specifies the type of relationship and each member named "href" specifies the
information that is linked to the entity or resource. Note that information that is linked to the entity or resource. Note that
WebFinger narrows the scope of a link relation beyond what is defined WebFinger narrows the scope of a link relation beyond what is defined
for Web Linking by stipulating that the value of the "rel" member for Web Linking by stipulating that the value of the "rel" member
needs to be either a single IANA-registered link relation type [9] or needs to be either a single IANA-registered link relation type [8] or
a URI [6]. a URI [6].
The use of URIs throughout this document refers to URIs following the
syntax specified in Section 3 of RFC 3986 [6]. Relative URIs, having
syntax following that of Section 4.2 or RFC 3986, are not used with
WebFinger.
3. Example Uses of WebFinger 3. Example Uses of WebFinger
This non-normative section shows a few sample uses of WebFinger. This non-normative section shows a few sample uses of WebFinger.
3.1. Identity Provider Discovery for OpenID Connect 3.1. Identity Provider Discovery for OpenID Connect
Suppose Carol wishes to authenticate with a web site she visits using Suppose Carol wishes to authenticate with a web site she visits using
OpenID Connect [15]. She would provide the web site with her OpenID OpenID Connect [15]. She would provide the web site with her OpenID
Connect identifier, say carol@example.com. The visited web site Connect identifier, say carol@example.com. The visited web site
would perform a WebFinger query looking for the OpenID Connect would perform a WebFinger query looking for the OpenID Connect
skipping to change at page 4, line 49 skipping to change at page 5, line 17
Suppose an application would like to retrieve metadata information Suppose an application would like to retrieve metadata information
about a web page URL, such as author and copyright information. To about a web page URL, such as author and copyright information. To
do that, the application can utilize WebFinger to issue a query for do that, the application can utilize WebFinger to issue a query for
the specific URL. Suppose the URL of interest is the specific URL. Suppose the URL of interest is
http://blog.example.com/article/id/314. The application would issue http://blog.example.com/article/id/314. The application would issue
a query similar to the following: a query similar to the following:
GET /.well-known/webfinger? GET /.well-known/webfinger?
resource=http%3A%2F%2Fblog.example.com%2Farticle%2Fid%2F314 resource=http%3A%2F%2Fblog.example.com%2Farticle%2Fid%2F314
HTTP/1.1 HTTP/1.1
Host: example.com Host: blog.example.com
The server might then reply in this way: The server might then reply in this way:
HTTP/1.1 200 OK HTTP/1.1 200 OK
Access-Control-Allow-Origin: * Access-Control-Allow-Origin: *
Content-Type: application/jrd+json Content-Type: application/jrd+json
{ {
"subject" : "http://blog.example.com/article/id/314", "subject" : "http://blog.example.com/article/id/314",
"aliases" : "aliases" :
[ [
"http://blog.example.com/cool_new_thing", "http://blog.example.com/cool_new_thing",
"http://blog.example.com/steve/article/7" "http://blog.example.com/steve/article/7"
], ],
"properties" : "properties" :
{ {
"http://blgx.example.net/ns/version" : 1.3, "http://blgx.example.net/ns/version" : "1.3",
"http://blgx.example.net/ns/ext" : null "http://blgx.example.net/ns/ext" : null
}, },
"links" : "links" :
[ [
{ {
"rel" : "copyright", "rel" : "copyright",
"href" : "http://www.example.com/copyright" "href" : "http://www.example.com/copyright"
}, },
{ {
"rel" : "author", "rel" : "author",
skipping to change at page 6, line 35 skipping to change at page 6, line 55
then the client chooses a host to which it directs the query using then the client chooses a host to which it directs the query using
additional information it has. additional information it has.
The path component of a WebFinger URI MUST be the well-known path The path component of a WebFinger URI MUST be the well-known path
"/.well-known/webfinger". A WebFinger URI MUST contain a query "/.well-known/webfinger". A WebFinger URI MUST contain a query
component that encodes the query target and optional link relation component that encodes the query target and optional link relation
types as specified in Section 4.1. types as specified in Section 4.1.
The WebFinger resource returns a JSON Resource Descriptor (JRD) as The WebFinger resource returns a JSON Resource Descriptor (JRD) as
the resource representation to convey information about an entity on the resource representation to convey information about an entity on
the Internet. Also, the Cross-Origin Resource Sharing (CORS) [8] the Internet. Also, the Cross-Origin Resource Sharing (CORS) [7]
specification is utilized to facilitate queries made via a web specification is utilized to facilitate queries made via a web
browser. browser.
4.1. Constructing the Query Component of the Request URI 4.1. Constructing the Query Component of the Request URI
A WebFinger URI MUST contain a query component (see Section 3.4 of A WebFinger URI MUST contain a query component (see Section 3.4 of
RFC 3986). The query component MUST contain a "resource" parameter RFC 3986). The query component MUST contain a "resource" parameter
and MAY contain one or more "rel" parameters. The "resource" and MAY contain one or more "rel" parameters. The "resource"
parameter MUST contain the query target (URI) and the "rel" parameter MUST contain the query target (URI) and the "rel"
parameters MUST contain encoded link relation types according to the parameters MUST contain encoded link relation types according to the
skipping to change at page 10, line 21 skipping to change at page 10, line 42
the value of the "resource" parameter used in the client's request. the value of the "resource" parameter used in the client's request.
This might happen, for example, when the subject's identity changes This might happen, for example, when the subject's identity changes
(e.g., a user moves his or her account to another service) or when (e.g., a user moves his or her account to another service) or when
the resource prefers to express URIs in canonical form. the resource prefers to express URIs in canonical form.
The "subject" member SHOULD be present in the JRD. The "subject" member SHOULD be present in the JRD.
4.4.2. aliases 4.4.2. aliases
The "aliases" array is an array of zero or more URI strings that The "aliases" array is an array of zero or more URI strings that
identify the same entity as the "subject" URI. Each URI must be an identify the same entity as the "subject" URI.
absolute URI.
The "aliases" array is OPTIONAL in the JRD. The "aliases" array is OPTIONAL in the JRD.
4.4.3. properties 4.4.3. properties
The "properties" object comprises zero or more name/value pairs whose The "properties" object comprises zero or more name/value pairs whose
names are absolute URIs and whose values are strings or null. names are URIs and whose values are strings or null. Properties are
Properties are used to convey additional information about the used to convey additional information about the subject of the JRD.
subject of the JRD. As an example, consider this use of As an example, consider this use of "properties":
"properties":
"properties" : { "http://webfinger.example/ns/name" : "Bob Smith" } "properties" : { "http://webfinger.example/ns/name" : "Bob Smith" }
The "properties" member is OPTIONAL in the JRD. The "properties" member is OPTIONAL in the JRD.
4.4.4. links 4.4.4. links
The "links" array has any number of member objects, each of which The "links" array has any number of member objects, each of which
represents a link [4]. Each of these link objects can have the represents a link [4]. Each of these link objects can have the
following members: following members:
o rel o rel
o type o type
o href o href
o titles o titles
o properties o properties
The "rel" and "href" members are strings representing the link's The "rel" and "href" members are strings representing the link's
relation type and the target IRI, respectively. The context of the relation type and the target URI, respectively. The context of the
link is the "subject" (see Section 4.4.1). link is the "subject" (see Section 4.4.1).
The "type" member is a string indicating what the media type of the The "type" member is a string indicating what the media type of the
result of dereferencing the link ought to be. result of dereferencing the link ought to be.
The order of elements in the "links" array indicates an order of The order of elements in the "links" array indicates an order of
preference. Thus, if there are two or more link relations having the preference. Thus, if there are two or more link relations having the
same "rel" value, the first link relation would indicate the user's same "rel" value, the first link relation would indicate the user's
preferred link. preferred link.
skipping to change at page 11, line 21 skipping to change at page 11, line 40
Below, each of the members of the objects found in the "links" array Below, each of the members of the objects found in the "links" array
is described in more detail. Each object in the "links" array, is described in more detail. Each object in the "links" array,
referred to as a "link relation object", is completely independent referred to as a "link relation object", is completely independent
from any other object in the array; any requirement to include a from any other object in the array; any requirement to include a
given member in the link relation object refers only to that given member in the link relation object refers only to that
particular object. particular object.
4.4.4.1. rel 4.4.4.1. rel
The value of the "rel" member is a string that is either an absolute The value of the "rel" member is a string that is either a URI or a
URI or a registered relation type [9] (see RFC 5988 [4]). The value registered relation type [8] (see RFC 5988 [4]). The value of the
of the "rel" member MUST contain exactly one URI or registered "rel" member MUST contain exactly one URI or registered relation
relation type. The URI or registered relation type identifies the type. The URI or registered relation type identifies the type of the
type of the link relation. link relation.
The other members of the object have meaning only once the type of The other members of the object have meaning only once the type of
link relation is understood. In some instances, the link relation link relation is understood. In some instances, the link relation
will have associated semantics enabling the client to query for other will have associated semantics enabling the client to query for other
resources on the Internet. In other instances, the link relation resources on the Internet. In other instances, the link relation
will have associated semantics enabling the client to utilize the will have associated semantics enabling the client to utilize the
other members of the link relation object without fetching additional other members of the link relation object without fetching additional
external resources. external resources.
URI link relation type values are compared using the "Simple String URI link relation type values are compared using the "Simple String
Comparison" algorithm of section 6.2.1 of RFC 3986 [6]. Comparison" algorithm of section 6.2.1 of RFC 3986.
The "rel" member MUST be present in the link relation object. The "rel" member MUST be present in the link relation object.
4.4.4.2. type 4.4.4.2. type
The value of the "type" member is a string that indicates the media The value of the "type" member is a string that indicates the media
type [10] of the target resource (see RFC 6838 [11]). type [9] of the target resource (see RFC 6838 [10]).
The "type" member is OPTIONAL in the link relation object. The "type" member is OPTIONAL in the link relation object.
4.4.4.3. href 4.4.4.3. href
The value of the "href" member is a string that contains a URI The value of the "href" member is a string that contains a URI
pointing to the target resource. pointing to the target resource.
The "href" member is OPTIONAL in the link relation object. The "href" member is OPTIONAL in the link relation object.
4.4.4.4. titles 4.4.4.4. titles
The "titles" object comprises zero or more name/value pairs whose The "titles" object comprises zero or more name/value pairs whose
name is a language tag [12] or the string "und". The string is name is a language tag [11] or the string "und". The string is
human-readable and describes the link relation. More than one title human-readable and describes the link relation. More than one title
for the link relation MAY be provided for the benefit of users who for the link relation MAY be provided for the benefit of users who
utilize the link relation and, if used, a language identifier SHOULD utilize the link relation and, if used, a language identifier SHOULD
be duly used as the name. If the language is unknown or unspecified, be duly used as the name. If the language is unknown or unspecified,
then the name is "und". then the name is "und".
A JRD SHOULD NOT include more than one title identified with the same A JRD SHOULD NOT include more than one title identified with the same
language tag (or "und") within the link relation object. Meaning is language tag (or "und") within the link relation object. Meaning is
undefined if a link relation object includes more than one title undefined if a link relation object includes more than one title
named with the same language tag (or "und"), though this MUST NOT be named with the same language tag (or "und"), though this MUST NOT be
skipping to change at page 12, line 35 skipping to change at page 12, line 51
{ {
"en-us" : "The Magical World of Steve", "en-us" : "The Magical World of Steve",
"fr" : "Le Monde Magique de Steve" "fr" : "Le Monde Magique de Steve"
} }
The "titles" member is OPTIONAL in the link relation object. The "titles" member is OPTIONAL in the link relation object.
4.4.4.5. properties 4.4.4.5. properties
The "properties" object within the link relation object comprises The "properties" object within the link relation object comprises
zero or more name/value pairs whose names are absolute URIs and whose zero or more name/value pairs whose names are URIs and whose values
values are strings or null. Properties are used to convey additional are strings or null. Properties are used to convey additional
information about the link relation. As an example, consider this information about the link relation. As an example, consider this
use of "properties": use of "properties":
"properties" : { "http://webfinger.example/mail/port" : "993" } "properties" : { "http://webfinger.example/mail/port" : "993" }
The "properties" member is OPTIONAL in the link relation object. The "properties" member is OPTIONAL in the link relation object.
4.5. WebFinger and URIs 4.5. WebFinger and URIs
WebFinger requests include a "resource" parameter (see Section 4.1) WebFinger requests include a "resource" parameter (see Section 4.1)
specifying the URI for which the client requests information. specifying the query target (URI) for which the client requests
WebFinger is neutral regarding the scheme of such a URI: it could be information. WebFinger is neutral regarding the scheme of such a
an "acct" URI [18], an "http" or "https" URI, a "mailto" URI [19], or URI: it could be an "acct" URI [18], an "http" or "https" URI, a
some other scheme. "mailto" URI [19], or some other scheme.
5. Cross-Origin Resource Sharing (CORS) 5. Cross-Origin Resource Sharing (CORS)
WebFinger resources might not be accessible from a web browser due to WebFinger resources might not be accessible from a web browser due to
"Same-Origin" policies. The current best practice is to make "Same-Origin" policies. The current best practice is to make
resources available to browsers through Cross-Origin Resource Sharing resources available to browsers through Cross-Origin Resource Sharing
(CORS) [8], and servers MUST include the Access-Control-Allow-Origin (CORS) [7], and servers MUST include the Access-Control-Allow-Origin
HTTP header in responses. Servers SHOULD support the least HTTP header in responses. Servers SHOULD support the least
restrictive setting by allowing any domain access to the WebFinger restrictive setting by allowing any domain access to the WebFinger
resource: resource:
Access-Control-Allow-Origin: * Access-Control-Allow-Origin: *
There are cases where defaulting to the least restrictive setting is There are cases where defaulting to the least restrictive setting is
not appropriate, for example a server on an intranet that provides not appropriate, for example a server on an intranet that provides
sensitive company information SHOULD NOT allow CORS requests from any sensitive company information SHOULD NOT allow CORS requests from any
domain, as that could allow leaking of that sensitive information. A domain, as that could allow leaking of that sensitive information. A
skipping to change at page 14, line 42 skipping to change at page 15, line 5
Access-Control-Allow-Origin: * Access-Control-Allow-Origin: *
Location: https://wf.example.net/example.com/webfinger? Location: https://wf.example.net/example.com/webfinger?
resource=acct%3Aalice%40example.com resource=acct%3Aalice%40example.com
The client can then follow the redirection, re-issuing the request to The client can then follow the redirection, re-issuing the request to
the URI provided in the Location header. Note that the server will the URI provided in the Location header. Note that the server will
include any required URI parameters in the Location header value, include any required URI parameters in the Location header value,
which could be different than the URI parameters the client which could be different than the URI parameters the client
originally used. originally used.
8. Security Considerations 8. Definition of WebFinger Applications
8.1. Transport-Related Issues This specification details the protocol syntax used to query a domain
for information about a URI, the syntax of the JSON Resource
Descriptor (JRD) that is returned in response to that query, security
requirements and considerations, hosted WebFinger services, various
expected HTTP status codes, and so forth. However, this
specification does not enumerate the various possible properties or
link relation types that might be used in conjunction with WebFinger
for a particular application, nor does it define what properties or
link relation types one might expect to see in response to querying
for a particular URI or URI scheme. Nonetheless, all of these
unspecified elements are important in order to implement an
interoperable application that utilizes the WebFinger protocol and
MUST be specified in the relevant document(s) defining the particular
application making use of the WebFinger protocol according to the
procedures described in this section.
8.1. Specification of the URI Scheme and URI
Any application that uses WebFinger MUST specify the URI scheme(s)
and, to the extent appropriate, what forms the URI(s) might take.
For example, when querying for information about a user's account at
some domain, it might make sense to specify the use of the acct URI
scheme [18]. When trying to obtain the copyright information for a
web page, it makes sense to specify the use of the web page URI
(either http or https).
The examples in Sections 3.1 and 3.2 illustrate the use of different
URI schemes with WebFinger applications. In the example in Section
3.1, WebFinger is used to retrieve information pertinent to OpenID
Connect. In the example in Section 3.2, WebFinger is used to
discover metadata information about a web page, including author and
copyright information. Each of these applications of WebFinger needs
to be fully specified to ensure interoperability.
8.2. Host Resolution
As explained in Section 4, the host to which a WebFinger query is
issued is significant. In general, WebFinger applications would
adhere to the procedures described in Section 4 in order to properly
direct a WebFinger query.
However, some URI schemes do not have host portions and there might
be some applications of WebFinger for which the host portion of a URI
cannot or should not be utilized. In such instances, the application
specification MUST clearly define the host resolution procedures,
which might include provisioning a "default" host within the client
to which queries are directed.
8.3. Specification of Properties
WebFinger defines both subject-specific properties (i.e., properties
related to the URI that for which information is queried) and link-
specific properties. This section refers to subject-specific
properties.
Properties are name/value pairs whose names are URIs and whose values
are strings or null. Applications that utilize subject-specific
properties MUST define the URIs used in identifying those properties,
along with valid property values.
Consider this portion of the JRD found in the example in Section 3.2.
"properties" :
{
"http://blgx.example.net/ns/version" : "1.3",
"http://blgx.example.net/ns/ext" : null
}
Here, two properties are returned in the WebFinger response. Each of
these would be defined in a WebFinger application specification.
These two properties might be defined in the same WebFinger
application specification or separately in different specifications.
Since the latter is possible, it is important that WebFinger clients
not assume that one property has any specific relationship with
another property unless some relationship is explicitly defined in
the particular WebFinger application specification.
8.4. Specification of Links
The links returned in a WebFinger response are each comprised of
several pieces of information, some of which are optional (refer to
Section 4.4.4). The WebFinger application specification MUST define
each link and any values associated with a link, including the link
relation type ("rel"), the expected media type ("type"), properties,
and titles.
The target URI to which the link refers (i.e., the "href"), if
present, would not normally be specified in an application
specification. However, the URI scheme or any special
characteristics of the URI would usually be specified. If a
particular link does not require an external reference, then all of
the semantics related to the use of that link MUST be defined within
the application specification. Such links might rely only on
properties or titles in the link to convey meaning.
8.5. One URI, Multiple Applications
It is important to be mindful of the fact that different WebFinger
applications might specify the use of the same URI scheme and, in
effect, the same URI for different purposes. That should not be a
problem, since each of property identifier and link relation type
would be uniquely defined for a specific application.
It should be noted that when a client requests information about a
particular URI and receives a response with a number of different
property identifiers or link relation types that the response is
providing information about the URI without any particular semantics.
How the client interprets the information SHOULD be in accordance
with the particular application specification or set of
specifications the client implements.
Any syntactically valid properties or links the client receives and
that are not fully understood SHOULD be ignored and MUST NOT cause
the client to report an error.
8.6. Registration of Link Relation Types and Properties
Application specifications MAY define a simple token as a link
relation type for a link. In that case, the link relation type MUST
be registered with IANA as specified in Sections 10.3.
Further, any defined properties MUST be registered with IANA as
described in Section 10.4.
9. Security Considerations
9.1. Transport-Related Issues
Since this specification utilizes Cross-Origin Resource Sharing Since this specification utilizes Cross-Origin Resource Sharing
(CORS) [8], all of the security considerations applicable to CORS are (CORS) [7], all of the security considerations applicable to CORS are
also applicable to this specification. also applicable to this specification.
The use of HTTPS is REQUIRED to ensure that information is not The use of HTTPS is REQUIRED to ensure that information is not
modified during transit. It should be appreciated that in modified during transit. It should be appreciated that in
environments where a web server is normally available, there exists environments where a web server is normally available, there exists
the possibility that a compromised network might have its WebFinger the possibility that a compromised network might have its WebFinger
resource operating on HTTPS replaced with one operating only over resource operating on HTTPS replaced with one operating only over
HTTP. As such, clients MUST NOT issue queries over a non-secure HTTP. As such, clients MUST NOT issue queries over a non-secure
connection. connection.
Clients MUST verify that the certificate used on an HTTPS connection Clients MUST verify that the certificate used on an HTTPS connection
is valid (as defined in [13]) and accept a response only if the is valid (as defined in [12]) and accept a response only if the
certificate is valid. certificate is valid.
8.2. User Privacy Considerations 9.2. User Privacy Considerations
Service providers and users should be aware that placing information Service providers and users should be aware that placing information
on the Internet means that any user can access that information and on the Internet means that any user can access that information and
WebFinger can be used to make it even easier to discover that WebFinger can be used to make it even easier to discover that
information. While WebFinger can be an extremely useful tool for information. While WebFinger can be an extremely useful tool for
discovering one's avatar, blog, or other personal data, users should discovering one's avatar, blog, or other personal data, users should
understand the risks, too. understand the risks, too.
Systems or services that expose personal data via WebFinger MUST Systems or services that expose personal data via WebFinger MUST
provide an interface by which users can select which data elements provide an interface by which users can select which data elements
skipping to change at page 16, line 16 skipping to change at page 18, line 53
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 WebFinger resources for information available via WebFinger, such as WebFinger resources for
use inside a corporate network, the network administrator needs to use inside a corporate network, the network administrator needs to
take necessary measures to limit access from outside the network. take necessary measures to limit access from outside the network.
Using standard methods for securing web resources, network Using standard methods for securing web resources, network
administrators do have the ability to control access to resources administrators do have the ability to control access to resources
that might return sensitive information. Further, a server can be that might return sensitive information. Further, a server can be
employed in such a way as to require authentication and prevent employed in such a way as to require authentication and prevent
disclosure of information to unauthorized entities. disclosure of information to unauthorized entities.
8.3. Abuse Potential 9.3. Abuse Potential
Service providers should be mindful of the potential for abuse using Service providers should be mindful of the potential for abuse using
WebFinger. WebFinger.
As one example, one might query a WebFinger server only to discover As one example, one might query a WebFinger server only to discover
whether a given URI is valid or not. With such a query, the person whether a given URI is valid or not. With such a query, the person
may deduce that an email identifier is valid, for example. Such an may deduce that an email identifier is valid, for example. Such an
approach could help spammers maintain a current list of known email approach could help spammers maintain a current list of known email
addresses and to discover new ones. addresses and to discover new ones.
skipping to change at page 17, line 5 skipping to change at page 19, line 42
perform a WebFinger query on the sender of each received mail perform a WebFinger query on the sender of each received mail
message. If a spammer sent an email using a unique identifier in the message. If a spammer sent an email using a unique identifier in the
'From' header, then when the WF query was performed the spammer would 'From' header, then when the WF query was performed the spammer would
be able to associate the request with a particular user's email be able to associate the request with a particular user's email
address. This would provide information to the spammer, including address. This would provide information to the spammer, including
the user's IP address, the fact the user just checked email, what the user's IP address, the fact the user just checked email, what
kind of WebFinger client the user utilized, and so on. For this kind of WebFinger client the user utilized, and so on. For this
reason, it is strongly advised that clients not perform WebFinger reason, it is strongly advised that clients not perform WebFinger
queries unless authorized by the user to do so. queries unless authorized by the user to do so.
8.4. Information Reliability 9.4. Information Reliability
A WebFinger resource has no means of ensuring that information A WebFinger resource has no means of ensuring that information
provided by a user is accurate. Likewise, neither the resource nor provided by a user is accurate. Likewise, neither the resource nor
the client can be absolutely guaranteed that information has not been the client 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 resource path, but it clearly cannot address issues where the resource
provided incorrect information, either due to being provided false provided incorrect information, either due to being provided false
information or due to malicious behavior on the part of the server information or due to malicious behavior on the part of the server
administrator. As with any information service available on the administrator. As with any information service available on the
Internet, users should be wary of information received from untrusted Internet, users should be wary of information received from untrusted
sources. sources.
9. IANA Considerations 10. IANA Considerations
9.1. Well-Known URI 10.1. Well-Known URI
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 XXXX Specification document(s): RFC XXXX
Related information: The query to the WebFinger resource will Related information: The query to the WebFinger resource will
include one or more parameters in the query string; see Section 4.1 include one or more parameters in the query string; see Section 4.1
of RFCXXXX. Resources at this location are able to return a JSON of RFCXXXX. Resources at this location are able to return a JSON
Resource Descriptor (JRD) as described in Section 4.4 of RFCXXXX. Resource Descriptor (JRD) as described in Section 4.4 of RFCXXXX.
[RFC EDITOR: Please replace "XXXX" references in this section and the [RFC EDITOR: Please replace "XXXX" references in this section and the
following section with the number for this RFC.] following section with the number for this RFC.]
9.2. JSON Resource Descriptor (JRD) Media Type 10.2. JSON Resource Descriptor (JRD) Media Type
This specification registers the media type application/jrd+json for This specification registers the media type application/jrd+json for
use with WebFinger in accordance with media type registration use with WebFinger in accordance with media type registration
procedures defined in [11]. procedures defined in [10].
Type name: application Type name: application
Subtype name: jrd+json Subtype name: jrd+json
Required parameters: N/A Required parameters: N/A
Optional parameters: N/A Optional parameters: N/A
In particular, because RFC 4627 already defines the character In particular, because RFC 4627 already defines the character
skipping to change at page 19, line 4 skipping to change at page 21, line 41
Macintosh file type code(s): N/A Macintosh file type code(s): N/A
Person & email address to contact for further information: Person & email address to contact for further information:
Paul E. Jones <paulej@packetizer.com> Paul E. Jones <paulej@packetizer.com>
Intended usage: COMMON Intended usage: COMMON
Restrictions on usage: N/A Restrictions on usage: N/A
Author: Paul E. Jones <paulej@packetizer.com> Author: Paul E. Jones <paulej@packetizer.com>
Change controller: Change controller:
IESG has change control over this registration. IESG has change control over this registration.
Provisional registration? (standards tree only): N/A Provisional registration? (standards tree only): N/A
10. Acknowledgments 10.3. Registering Link Relation Types
RFC 5988 established a Link Relation Type Registry that is re-used by
WebFinger applications.
Link relation types used by WebFinger applications are registered in
the Link Relations Type Registry as per the procedures of Section
6.2.1 of RFC 5988. The "Notes" entry for the registration SHOULD
indicate if property values associated with the link relation type
are registered in the WebFinger Properties registry with a link to
the registry.
10.4. Establishment of the WebFinger Properties Registry
WebFinger utilizes URIs to identify properties of a subject or link
and the associated values (see Section 8.3 and Section 8.6). This
specification establishes a new "WebFinger Properties" registry to
record property identifiers.
10.4.1. The Registration Template
The registration template for WebFinger properties is:
o Property URI:
o Link Type:
o Description:
o Reference:
o Notes: [optional]
The "Property URI" must be a URI that identifies the property being
registered.
The "Link Type" contains the name of a Link Relation Type with which
this property identifier is used. If the property is a subject-
specific property, then this field is specified as "N/A".
The "Description" is intended to explaining the purpose of the
property.
The "Reference" field points to the specification that defines the
registered property.
The optional "Notes" field is for conveying any useful information
about the property that might be of value to implementers.
10.4.2. The Registration Procedures
The IETF has created a mailing list, webfinger@ietf.org, which can be
used for public discussion of the WebFinger protocol and any
applications that use it. Prior to registration of a WebFinger
property, discussion on the mailing list is strongly encouraged. The
IESG has appointed Designated Experts who will monitor the
webfinger@ietf.org mailing list and review registrations.
A WebFinger property is registered with a Specification Required (see
RFC 5226 [13]) after a two-week review period by the Designated
Expert(s). However, the Designated Expert(s) may approve a
registration prior to publication of a specification once the
Designated Expert(s) are satisfied that such a specification will be
published. In evaluating registration requests, the Designated
Expert(s) should make an effort to avoid registering two different
properties that have the same meaning. Where a proposed property is
similar to an already-defined property, Designated Expert(s) should
insist that enough text be included in the description or notes
section of the template to sufficiently differentiate the new
property from an existing one.
The registration procedure begins when a completed registration
template (as defined above) sent to webfinger@ietf.org and
iana@iana.org. IANA will track the review process and communicate
the results to the registrant. The WebFinger mailing list provides
an opportunity for community discussion and input, and the Designated
Expert(s) may use that input to inform their review. Denials should
include an explanation and, if applicable, suggestions as to how to
make the request successful if re-submitted.
The specification registering the WebFinger property MUST include the
completed registration template shown above. Once the registration
procedure concludes successfully, IANA creates or modifies the
corresponding record in the "WebFinger Properties" registry.
11. Acknowledgments
This document has benefited from extensive discussion and review of This document has benefited from extensive discussion and review of
many of the members of the APPSAWG working group. The authors would many of the members of the APPSAWG working group. The authors would
like to especially acknowledge the invaluable input of Eran Hammer- like to especially acknowledge the invaluable input of Eran Hammer-
Lahav, Blaine Cook, Brad Fitzpatrick, Laurent-Walter Goix, Joe Lahav, Blaine Cook, Brad Fitzpatrick, Laurent-Walter Goix, Joe
Clarke, Michael B. Jones, Peter Saint-Andre, Dick Hardt, Tim Bray, Clarke, Michael B. Jones, Peter Saint-Andre, Dick Hardt, Tim Bray,
James Snell, Melvin Carvalho, Evan Prodromou, Mark Nottingham, Barry James Snell, Melvin Carvalho, Evan Prodromou, Mark Nottingham, Barry
Leiba, Elf Pavlik, Bjoern Hoehrmann, Subramanian Moonesamy, Joe Leiba, Elf Pavlik, Bjoern Hoehrmann, Subramanian Moonesamy, Joe
Gregorio and others that we have undoubtedly, but inadvertently, Gregorio, John Bradley, Pete Resnick and others that we have
missed. Special thanks go to the chairs of APPSAWG, especially undoubtedly, but inadvertently, missed. Special thanks go to the
Salvatore Loreto for his assistance in shepherding this document. chairs of APPSAWG, especially Salvatore Loreto for his assistance in
shepherding this document.
11. References 12. References
11.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., Masinter, L., [2] Fielding, R., Gettys, J., Mogul, J., Frystyk, H., Masinter, L.,
Leach, P., and T. Berners-Lee, "Hypertext Transfer Protocol -- Leach, P., and T. Berners-Lee, "Hypertext Transfer Protocol --
HTTP/1.1", RFC 2616, June 1999. 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 JavaScript [5] Crockford, D., "The application/json Media Type for JavaScript
Object Notation (JSON)", RFC 4627, July 2006. 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] Duerst, M., "Internationalized Resource Identifiers (IRIs)", [7] Van Kesteren, A., "Cross-Origin Resource Sharing", W3C CORS
RFC 3987, January 2005.
[8] 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.
[9] IANA, "Link Relations", http://www.iana.org/assignments/link- [8] IANA, "Link Relations", http://www.iana.org/assignments/link-
relations/. relations/.
[10] IANA, "MIME Media Types", [9] IANA, "MIME Media Types",
http://www.iana.org/assignments/media-types/index.html. http://www.iana.org/assignments/media-types/index.html.
[11] Freed, N., Klensin, J., Hansen, T., "Media Type Specifications [10] Freed, N., Klensin, J., Hansen, T., "Media Type Specifications
and Registration Procedures", RFC 6838, January 2013. and Registration Procedures", RFC 6838, January 2013.
[12] Phillips, A., Davis, M., "Tags for Identifying Languages", RFC [11] Phillips, A., Davis, M., "Tags for Identifying Languages", RFC
5646, January 2009. 5646, January 2009.
[13] Rescorla, E., "HTTP Over TLS", RFC 2818, May 2000. [12] Rescorla, E., "HTTP Over TLS", RFC 2818, May 2000.
11.2. Informative References [13] Narten, T. and H. Alvestrand, "Guidelines for Writing an, IANA
Considerations Section in RFCs", BCP 26, RFC 5226, May 2008.
12.2. Informative References
[14] Perreault, S., "vCard Format Specification", RFC 6350, August [14] Perreault, S., "vCard Format Specification", RFC 6350, August
2011. 2011.
[15] Sakimura, N., Bradley, J., Jones, M., de Medeiros, B., [15] Sakimura, N., Bradley, J., Jones, M., de Medeiros, B.,
Mortimore, C., and E. Jay, "OpenID Connect Messages 1.0", Mortimore, C., and E. Jay, "OpenID Connect Messages 1.0",
January 2013, http://openid.net/specs/openid-connect-messages- January 2013, http://openid.net/specs/openid-connect-messages-
1_0.html. 1_0.html.
[16] Hammer-Lahav, E. and Cook, B., "Web Host Metadata", RFC 6415, [16] Hammer-Lahav, E. and Cook, B., "Web Host Metadata", RFC 6415,
 End of changes. 49 change blocks. 
87 lines changed or deleted 314 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/