draft-ietf-appsawg-webfinger-14.txt   draft-ietf-appsawg-webfinger-15.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: November 26, 2013 Joseph Smarr Expires: January 4, 2014 Joseph Smarr
Google Google
May 26, 2013 July 4, 2013
WebFinger WebFinger
draft-ietf-appsawg-webfinger-14.txt draft-ietf-appsawg-webfinger-15.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 November 26, 2013. This Internet-Draft will expire on January 4, 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
skipping to change at page 2, line 10 skipping to change at page 2, line 10
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......................................3
3.1. Locating a User's Blog....................................3 3.1. Identity Provider Discovery for OpenID Connect............3
3.2. Identity Provider Discovery for OpenID Connect............5 3.2. Getting Author and Copyright Information for a Web Page...4
3.3. Auto-Configuration of Email Clients.......................6 4. WebFinger Protocol.............................................5
3.4. Retrieving Device Information.............................7 4.1. Constructing the Query Component of the Request URI.......6
4. WebFinger Protocol.............................................8 4.2. Performing a WebFinger Query..............................7
4.1. Constructing the Query Component of the Request URI.......9 4.3. The "rel" Parameter.......................................8
4.2. Performing a WebFinger Query..............................9 4.4. The JSON Resource Descriptor (JRD)........................9
4.3. The "rel" Parameter......................................10 4.4.1. subject..............................................9
4.4. The JSON Resource Descriptor (JRD).......................11 4.4.2. aliases.............................................10
4.4.1. subject.............................................12 4.4.3. properties..........................................10
4.4.2. aliases.............................................12 4.4.4. links...............................................10
4.4.3. properties..........................................12 4.5. WebFinger and URIs.......................................12
4.4.4. links...............................................12 5. Cross-Origin Resource Sharing (CORS)..........................12
4.5. WebFinger and URIs.......................................14 6. Access Control................................................13
5. Cross-Origin Resource Sharing (CORS)..........................15 7. Hosted WebFinger Services.....................................13
6. Access Control................................................15 8. Security Considerations.......................................14
7. Hosted WebFinger Services.....................................16 8.1. Transport-Related Issues.................................14
8. Security Considerations.......................................17 8.2. User Privacy Considerations..............................15
8.1. Transport-Related Issues.................................17 8.3. Abuse Potential..........................................16
8.2. User Privacy Considerations..............................17 8.4. Information Reliability..................................16
8.3. Abuse Potential..........................................18 9. IANA Considerations...........................................17
8.4. Information Reliability..................................19 9.1. Well-Known URI...........................................17
9. IANA Considerations...........................................19 9.2. JSON Resource Descriptor (JRD) Media Type................17
9.1. Well-Known URI...........................................19 10. Acknowledgments..............................................19
9.2. JSON Resource Descriptor (JRD) Media Type................20 11. References...................................................19
10. Acknowledgments..............................................21 11.1. Normative References....................................19
11. References...................................................21 11.2. Informative References..................................20
11.1. Normative References....................................21 Author's Addresses...............................................21
11.2. Informative References..................................22
Author's Addresses...............................................23
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] or IRI [7]
using standard Hypertext Transfer Protocol (HTTP) [2] methods over a using standard Hypertext Transfer Protocol (HTTP) [2] methods over a
secure transport [14]. A WebFinger resource returns a JavaScript secure transport [13]. A WebFinger resource returns a JavaScript
Object Notation (JSON) [5] object describing the entity that is Object Notation (JSON) [5] object describing the entity that is
queried. The JSON object is referred to as the JSON Resource queried. 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 [10] that enable a client to discover, for example, the relations [9] that enable a client to discover, for example, the that
that a printer can print in color on A4 paper, the physical location a printer can print in color on A4 paper, the physical location of a
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
logging into a web site by determining a user's identity service). logging into a web site by determining a user's identity service).
The information is intended to be static in nature and, as such, The information is intended to be static in nature and, as such,
WebFinger is not intended to be used to return dynamic information WebFinger is not intended to be used to return dynamic information
like the temperature of a CPU or the current toner level in a laser like the temperature of a CPU or the current toner level in a laser
printer. printer.
skipping to change at page 3, line 44 skipping to change at page 3, line 42
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 [10] needs to be either a single IANA-registered link relation type [9] or
or a URI [6]. a URI [6].
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. Locating a User's Blog 3.1. Identity Provider Discovery for OpenID Connect
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.
It would be simple to discover the address of Bob's blog if he made
that information available via WebFinger.
Assume your email client can discover the blog for you. After
receiving the message from Bob (bob@example.com), your email client
performs a WebFinger query either automatically or at your command.
(Please refer to Section 8.2 for user privacy considerations and
Section 8.3 for abuse considerations, particularly when considering
any kind of automated query feature.) It does so by issuing the
following HTTPS [14] query to example.com:
GET /.well-known/webfinger?
resource=acct%3Abob%40example.com HTTP/1.1
Host: example.com
The server might then respond with a message like this:
HTTP/1.1 200 OK
Access-Control-Allow-Origin: *
Content-Type: application/jrd+json
{
"subject" : "acct:bob@example.com",
"aliases" :
[
"http://www.example.com/~bob/"
],
"properties" :
{
"http://example.com/ns/role/" : "employee"
},
"links" :
[
{
"rel" : "http://webfinger.example/rel/avatar",
"type" : "image/jpeg",
"href" : "http://www.example.com/~bob/bob.jpg"
},
{
"rel" : "http://webfinger.example/rel/profile-page",
"href" : "http://www.example.com/~bob/"
},
{
"rel" : "http://webfinger.example/rel/blog",
"type" : "text/html",
"href" : "http://blogs.example.com/bob/",
"titles" :
{
"en-us" : "The Magical World of Bob",
"fr" : "Le Monde Magique de Bob"
}
},
{
"rel" : "http://webfinger.example/rel/businesscard",
"href" : "https://www.example.com/~bob/bob.vcf"
}
]
}
Note the assumption made in the above example is that there is an
"acct" URI for the given "mailto" URI. This may not always be the
case.
The email client would take note of the link relation in the above
JRD that refers to Bob's blog. The blog's URI would then be
presented to you so that you could then visit his blog. The email
client might also note that Bob has published an avatar link relation
and use that picture to represent Bob inside the email client.
Lastly, the client might automatically retrieve the data located at
the URI specified by the "businesscard" link relation (which might be
a vcard [16]) to update the information about Bob in its internal
address book.
In the above example, an "acct" URI [8] is used in the query, though
any valid alias for the user might also be used. See Section 4.5 for
more information on WebFinger and URIs.
An alias is a URI that is different from the "subject" URI, yet
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 query would have appeared as:
GET /.well-known/webfinger?
resource=http%3A%2F%2Fwww.example.com%2F~bob%2F HTTP/1.1
Host: www.example.com
Note that the host queried in this example is different than for the
acct URI example, since the URI refers to a different host. Either
this host would provide a response, or it would redirect the client
to another host (e.g., redirect back to example.com). Either way,
the response would have been substantially the same, with the subject
and alias information changed as necessary.
3.2. 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 [18]. 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
Provider. Since the site is interested in only one particular link Provider. Since the site is interested in only one particular link
relation, the WebFinger resource might utilize the "rel" parameter as relation, the WebFinger resource might utilize the "rel" parameter as
described in Section 4.3: described in Section 4.3:
GET /.well-known/webfinger? GET /.well-known/webfinger?
resource=acct%3Acarol%40example.com& resource=acct%3Acarol%40example.com&
rel=http%3A%2F%2Fopenid.net%2Fspecs%2Fconnect%2F1.0%2Fissuer rel=http%3A%2F%2Fopenid.net%2Fspecs%2Fconnect%2F1.0%2Fissuer
HTTP/1.1 HTTP/1.1
skipping to change at page 6, line 35 skipping to change at page 4, line 37
] ]
} }
Since the "rel" parameter only serves to filter the link relations Since the "rel" parameter only serves to filter the link relations
returned by the resource, other name/value pairs in the response, returned by the resource, other name/value pairs in the response,
including any aliases or properties, would be returned. Also, since including any aliases or properties, would be returned. Also, since
support for the "rel" parameter is not guaranteed, the client must support for the "rel" parameter is not guaranteed, the client must
not assume the "links" array will contain only the requested link not assume the "links" array will contain only the requested link
relation. relation.
3.3. Auto-Configuration of Email Clients 3.2. Getting Author and Copyright Information for a Web Page
WebFinger could be used to auto-provision an email client with basic Suppose an application would like to retrieve metadata information
configuration data. Suppose that sue@example.com wants to configure about a web page URL, such as author and copyright information. To
her email client. Her email client might issue the following query: do that, the application can utilize WebFinger to issue a query for
the specific URL. Suppose the URL of interest is
http://blog.example.com/article/id/314. The application would issue
a query similar to the following:
GET /.well-known/webfinger? GET /.well-known/webfinger?
resource=mailto%3Asue%40example.com HTTP/1.1 resource=http%3A%2F%2Fblog.example.com%2Farticle%2Fid%2F314
HTTP/1.1
Host: example.com Host: example.com
The returned resource representation would contain entries for the The server might then reply in this way:
various protocols, transport options, and security options. If there
are multiple options, the resource representation might include a
link relation for each of the valid options, and the client or Sue
might select which option to choose. Since JRDs list link relations
in a specific order, then the most-preferred choices could be
presented first. Consider this response:
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" : "mailto:sue@example.com", "subject" : "http://blog.example.com/article/id/314",
"aliases" :
[
"http://blog.example.com/cool_new_thing",
"http://blog.example.com/steve/article/7"
],
"properties" :
{
"http://blgx.example.net/ns/version" : 1.3,
"http://blgx.example.net/ns/ext" : null
},
"links" : "links" :
[ [
{ {
"rel" : "http://webfinger.example/rel/smtp-server", "rel" : "copyright",
"properties" : "href" : "http://www.example.com/copyright"
{
"http://webfinger.example/email/host" : "smtp.example.com",
"http://webfinger.example/email/port" : "587",
"http://webfinger.example/email/login-required" : "yes",
"http://webfinger.example/email/transport" : "starttls"
}
}, },
{ {
"rel" : "http://webfinger.example/rel/imap-server", "rel" : "author",
"href" : "http://blog.example.com/author/steve",
"titles" :
{
"en-us" : "The Magical World of Steve",
"fr" : "Le Monde Magique de Steve"
},
"properties" : "properties" :
{ {
"http://webfinger.example/email/host" : "imap.example.com", "http://example.com/role" : "editor"
"http://webfinger.example/email/port" : "993",
"http://webfinger.example/email/transport" : "ssl"
} }
} }
] ]
} }
In this example, you can see that the WebFinger resource In the above example, we see that the server returned a list of
representation advertises an SMTP service and an IMAP service. In aliases, properties, and links related to the subject URL. The links
this example, the "href" entries associated with the link relation contain references to information for each link relation type. For
are absent. This is valid when there is no additional reference that the author link, the server provided a reference to the author's
needs to be made. blog, along with a title for the blog in two languages. The server
also returned a single property related to the author, indicating the
3.4. Retrieving Device Information author's role as editor of the blog.
As another example, suppose there are printers on the network and you
would like to check a particular printer identified by the URI
device:p1.example.com to see if it can print in color on A4 paper.
While the "device" URI scheme is not presently specified, we use it
here for illustrative purposes.
Following the procedures similar to those above, a query may be
issued to get link relations specific to this URI like this:
GET /.well-known/webfinger?
resource=device%3Ap1.example.com HTTP/1.1
Host: p1.example.com
The link relations that are returned for a device may be quite
different than those for user accounts. Perhaps we may see a
response like this:
HTTP/1.1 200 OK
Access-Control-Allow-Origin: *
Content-Type: application/jrd+json
{
"subject" : "device:p1.example.com",
"links" :
[
{
"rel" : "http://webfinger.example/rel/tipsi",
"href" : "http://192.168.1.5/npap/"
}
]
}
While this example is fictitious, you can imagine that perhaps the It is worth noting that, while the server returned just two links in
Transport Independent, Printer/System Interface [17] may be enhanced the links array in this example, a server might return any number of
with a web interface enabling a device that understands the TIP/SI links when queried.
web interface specification to query for printer capabilities.
4. WebFinger Protocol 4. WebFinger Protocol
The WebFinger protocol is used to request information about an entity The WebFinger protocol is used to request information about an entity
identified by a query target (a URI). The client can optionally identified by a query target (a URI). The client can optionally
specify one or more link relation types for which it would like to specify one or more link relation types for which it would like to
receive information. receive information.
A WebFinger request is an HTTPS request to a WebFinger resource. A A WebFinger request is an HTTPS request to a WebFinger resource. A
WebFinger resource is a well-known URI [3] using the HTTPS scheme, WebFinger resource is a well-known URI [3] using the HTTPS scheme,
skipping to change at page 8, line 50 skipping to change at page 6, line 25
requests to a WebFinger resource convey the query target in the requests to a WebFinger resource convey the query target in the
"resource" parameter in the WebFinger URI's query string; see Section "resource" parameter in the WebFinger URI's query string; see Section
4.1 for details. 4.1 for details.
The host to which a WebFinger query is issued is significant. If the The host to which a WebFinger query is issued is significant. If the
query target contains a "host" portion (Section 3.2.2 of RFC 3986), query target contains a "host" portion (Section 3.2.2 of RFC 3986),
then the host to which the WebFinger query is issued MUST be the same then the host to which the WebFinger query is issued MUST be the same
as the "host" portion of the query target, unless the client receives as the "host" portion of the query target, unless the client receives
instructions through some out-of-band mechanism to send the query to instructions through some out-of-band mechanism to send the query to
another host. If the query target does not contain a "host" portion, another host. If the query target does not contain a "host" portion,
then the client MAY choose 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) [9] the Internet. Also, the Cross-Origin Resource Sharing (CORS) [8]
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 10 skipping to change at page 7, line 39
A WebFinger resource MUST return a JRD as the representation for the A WebFinger resource MUST return a JRD as the representation for the
resource if the client requests no other supported format explicitly resource if the client requests no other supported format explicitly
via the HTTP "Accept" header. The client MAY include the "Accept" via the HTTP "Accept" header. The client MAY include the "Accept"
header to indicate a desired representation; representations other header to indicate a desired representation; representations other
than JRD might be defined in future specifications. The WebFinger than JRD might be defined in future specifications. The WebFinger
resource MUST silently ignore any requested representations that it resource MUST silently ignore any requested representations that it
does not understand and support. The media type used for the JSON does not understand and support. The media type used for the JSON
Resource Descriptor (JRD) is "application/jrd+json" (see Section Resource Descriptor (JRD) is "application/jrd+json" (see Section
9.2). 9.2).
The properties, titles, and link relation types returned by the
server in a JRD might be varied and numerous. For example, the
server might return information about a person's blog, vCard [14],
avatar, OpenID Connect provider, RSS or ATOM feed, and so forth in a
reply. Likewise, if a server has no information to provide it might
return a JRD with an empty links array or no links array.
A WebFinger resource MAY redirect the client; if it does, the A WebFinger resource MAY redirect the client; if it does, the
redirection MUST only be to an "https" URI and the client MUST redirection MUST only be to an "https" URI and the client MUST
perform certificate validation again when redirected. perform certificate validation again when redirected.
A WebFinger resource can include cache validators in a response to A WebFinger resource can include cache validators in a response to
enable conditional requests by the client and/or expiration times as enable conditional requests by the client and/or expiration times as
per Section 13 of RFC 2616. per Section 13 of RFC 2616.
4.3. The "rel" Parameter 4.3. The "rel" Parameter
skipping to change at page 10, line 40 skipping to change at page 8, line 27
The "rel" parameter MAY be included multiple times in order to The "rel" parameter MAY be included multiple times in order to
request multiple link relation types. request multiple link relation types.
The purpose of the "rel" parameter is to return a subset of "link The purpose of the "rel" parameter is to return a subset of "link
relation objects" (see Section 4.4.4) that would otherwise be relation objects" (see Section 4.4.4) that would otherwise be
returned in the resource descriptor. Use of the parameter might returned in the resource descriptor. Use of the parameter might
reduce processing requirements on either the client or server, and it reduce processing requirements on either the client or server, and it
might also reduce the bandwidth required to convey the partial might also reduce the bandwidth required to convey the partial
resource descriptor, especially if there are numerous link relation resource descriptor, especially if there are numerous link relation
values to convey for a given "resource" value. values to convey for a given "resource" value. Note that if a client
requests a particular link relation type for which the server has no
information, the server MAY return a JRD with an empty links array or
no links array.
WebFinger resources SHOULD support the "rel" parameter. If the WebFinger resources SHOULD support the "rel" parameter. If the
resource does not support the "rel" parameter, it MUST ignore the resource does not support the "rel" parameter, it MUST ignore the
parameter and process the request as if no "rel" parameter values parameter and process the request as if no "rel" parameter values
were present. were present.
The following example presents the same example as found in Section The following example presents the same example as found in Section
3.1, but uses the "rel" parameter to select two link relations: 3.1, but uses the "rel" parameter to select two link relations:
GET /.well-known/webfinger? GET /.well-known/webfinger?
skipping to change at page 11, line 44 skipping to change at page 9, line 32
] ]
} }
As you can see in the response, the resource representation contains As you can see in the response, the resource representation contains
only the link relations requested by the client, but the other parts only the link relations requested by the client, but the other parts
of the JRD are still present. of the JRD are still present.
4.4. The JSON Resource Descriptor (JRD) 4.4. The JSON Resource Descriptor (JRD)
The JSON Resource Descriptor (JRD), originally introduced in RFC 6415 The JSON Resource Descriptor (JRD), originally introduced in RFC 6415
[19] and based on the Extensible Resource Descriptor (XRD) format [16] and based on the Extensible Resource Descriptor (XRD) format
[20], is a JSON object that comprises the following name/value pairs: [17], is a JSON object that comprises the following name/value pairs:
o subject o subject
o aliases o aliases
o properties o properties
o links o links
The member "subject" is a name/value pair whose value is a string, The member "subject" is a name/value pair whose value is a string,
"aliases" is an array of strings, "properties" is an object "aliases" is an array of strings, "properties" is an object
comprising name/value pairs whose values are strings, and "links" is comprising name/value pairs whose values are strings, and "links" is
an array of objects that contain link relation information. an array of objects that contain link relation information.
skipping to change at page 13, line 29 skipping to change at page 11, line 17
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 an absolute
URI or a registered relation type [10] (see RFC 5988 [4]). The value URI or a registered relation type [9] (see RFC 5988 [4]). The value
of the "rel" member MUST contain exactly one URI or registered of the "rel" member MUST contain exactly one URI or registered
relation type. The URI or registered relation type identifies the relation type. The URI or registered relation type identifies the
type of the link relation. type of the 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 [6].
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 [11] of the target resource (see RFC 6838 [12]). type [10] of the target resource (see RFC 6838 [11]).
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 [13] or the string "und". The string is name is a language tag [12] 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
treated as an error. A client MAY select whichever title or titles treated as an error. A client MAY select whichever title or titles
it wishes to utilize. it wishes to utilize.
Here is an example of the titles object: Here is an example of the titles object:
"titles" : "titles" :
{ {
"en-us" : "The Magical World of Bob", "en-us" : "The Magical World of Steve",
"fr" : "Le Monde Magique de Bob" "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 absolute URIs and whose
values are strings or null. Properties are used to convey additional values 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 of an account, device, or other entity. WebFinger specifying the URI for which the client requests information.
is neutral regarding the scheme of such a URI: it could be an "acct" WebFinger is neutral regarding the scheme of such a URI: it could be
URI [7], an "http" or "https" URI, a "mailto" URI [21], or some other an "acct" URI [18], an "http" or "https" URI, a "mailto" URI [19], or
scheme. some other scheme.
To perform a WebFinger lookup on an account specific to the host
being queried, use of the "acct" URI scheme is recommended, since it
explicitly identifies a generic user account that is not necessarily
bound to a specific protocol. Further, the "acct" URI scheme is not
associated with other protocols as, by way of example, the "mailto"
URI scheme is associated with email. Since not every host offers
email service, using the "mailto" URI scheme is not ideal for
identifying user accounts on all hosts. That said, use of the
"mailto" URI scheme would be ideal for use with WebFinger to discover
mail server configuration information for a user.
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) [9], and servers MUST include the Access-Control-Allow-Origin (CORS) [8], 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 17, line 16 skipping to change at page 14, line 40
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. Security Considerations
8.1. Transport-Related Issues 8.1. Transport-Related Issues
Since this specification utilizes Cross-Origin Resource Sharing Since this specification utilizes Cross-Origin Resource Sharing
(CORS) [9], all of the security considerations applicable to CORS are (CORS) [8], 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 [14]) and accept a response only if the is valid (as defined in [13]) and accept a response only if the
certificate is valid. certificate is valid.
8.2. User Privacy Considerations 8.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.
skipping to change at page 18, line 18 skipping to change at page 15, line 45
location). The power of WebFinger comes from providing a single location). The power of WebFinger comes from providing a single
place where others can find pointers to information about a person, place where others can find pointers to information about a person,
but service providers and users should be mindful of the nature of but service providers and users should be mindful of the nature of
that information shared and the fact that it might be available for that information shared and the fact that it might be available for
the entire world to see. Sharing location information, for example, the entire world to see. Sharing location information, for example,
would potentially put a person in danger from any individual who would potentially put a person in danger from any individual who
might seek to inflict harm on that person. might seek to inflict harm on that person.
Users should be aware of how easily personal data one might publish Users should be aware of how easily personal data one might publish
can be used in unintended ways. In one study relevant to WebFinger- can be used in unintended ways. In one study relevant to WebFinger-
like services, Balduzzi et al. [22] took a large set of leaked email like services, Balduzzi et al. [20] took a large set of leaked email
addresses and demonstrated a number of potential privacy concerns, addresses and demonstrated a number of potential privacy concerns,
including the ability to cross-correlate the same user's accounts including the ability to cross-correlate the same user's accounts
over multiple social networks. The authors also describe potential over multiple social networks. The authors also describe potential
mitigation strategies. mitigation strategies.
The easy access to user information via WebFinger was a design goal The easy access to user information via WebFinger was a design goal
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.
skipping to change at page 20, line 12 skipping to change at page 17, line 39
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 9.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 [12]. procedures defined in [11].
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 22, line 20 skipping to change at page 19, line 48
[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] Duerst, M., "Internationalized Resource Identifiers (IRIs)",
RFC 3987, January 2005. RFC 3987, January 2005.
[8] Saint-Andre, P., "The 'acct' URI Scheme", draft-ietf-appsawg- [8] Van Kesteren, A., "Cross-Origin Resource Sharing", W3C CORS
acct-uri-03, February 2013.
[9] Van Kesteren, A., "Cross-Origin Resource Sharing", W3C CORS
http://www.w3.org/TR/cors/, July 2010. http://www.w3.org/TR/cors/, July 2010.
[10] IANA, "Link Relations", http://www.iana.org/assignments/link- [9] IANA, "Link Relations", http://www.iana.org/assignments/link-
relations/. relations/.
[11] IANA, "MIME Media Types", [10] IANA, "MIME Media Types",
http://www.iana.org/assignments/media-types/index.html. http://www.iana.org/assignments/media-types/index.html.
[12] Freed, N., Klensin, J., Hansen, T., "Media Type Specifications [11] Freed, N., Klensin, J., Hansen, T., "Media Type Specifications
and Registration Procedures", RFC 6838, January 2013. and Registration Procedures", RFC 6838, January 2013.
[13] Phillips, A., Davis, M., "Tags for Identifying Languages", RFC [12] Phillips, A., Davis, M., "Tags for Identifying Languages", RFC
5646, January 2009. 5646, January 2009.
[14] Rescorla, E., "HTTP Over TLS", RFC 2818, May 2000. [13] Rescorla, E., "HTTP Over TLS", RFC 2818, May 2000.
[15] Klyne, G., Newman, C., "Date and Time on the Internet:
Timestamps", RFC 3339, July 2002.
11.2. Informative References 11.2. Informative References
[16] Perreault, S., "vCard Format Specification", RFC 6350, August [14] Perreault, S., "vCard Format Specification", RFC 6350, August
2011. 2011.
[17] "Transport Independent, Printer/System Interface", IEEE Std [15] Sakimura, N., Bradley, J., Jones, M., de Medeiros, B.,
1284.1-1997, 1997.
[18] 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.
[19] Hammer-Lahav, E. and Cook, B., "Web Host Metadata", RFC 6415, [16] Hammer-Lahav, E. and Cook, B., "Web Host Metadata", RFC 6415,
October 2011. October 2011.
[20] Hammer-Lahav, E. and W. Norris, "Extensible Resource Descriptor [17] Hammer-Lahav, E. and W. Norris, "Extensible Resource Descriptor
(XRD) Version 1.0", http://docs.oasis- (XRD) Version 1.0", http://docs.oasis-
open.org/xri/xrd/v1.0/xrd-1.0.html. open.org/xri/xrd/v1.0/xrd-1.0.html.
[21] Duerst, M., Masinter, L., and J. Zawinski, "The 'mailto' URI [18] Saint-Andre, P., "The 'acct' URI Scheme", draft-ietf-appsawg-
acct-uri-06, July 2013.
[19] Duerst, M., Masinter, L., and J. Zawinski, "The 'mailto' URI
Scheme", RFC 6068, October 2010. Scheme", RFC 6068, October 2010.
[22] Balduzzi, Marco, et al., "Abusing social networks for automated [20] Balduzzi, Marco, et al., "Abusing social networks for automated
user profiling", Recent Advances in Intrusion Detection, user profiling", Recent Advances in Intrusion Detection,
Springer Berlin Heidelberg, 2010, Springer Berlin Heidelberg, 2010,
https://www.eurecom.fr/en/publication/3042/download/rs-publi- https://www.eurecom.fr/en/publication/3042/download/rs-publi-
3042_1.pdf. 3042_1.pdf.
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.
 End of changes. 47 change blocks. 
260 lines changed or deleted 125 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/