draft-ietf-appsawg-webfinger-06.txt   draft-ietf-appsawg-webfinger-07.txt 
Network Working Group Paul E. Jones Network Working Group Paul E. Jones
Internet Draft Gonzalo Salgueiro Internet Draft Gonzalo Salgueiro
Intended status: Standards Track Cisco Systems Intended status: Standards Track Cisco Systems
Expires: May 29, 2013 Joseph Smarr Expires: June 2, 2013 Joseph Smarr
Google Google
November 29, 2012 December 2, 2012
WebFinger WebFinger
draft-ietf-appsawg-webfinger-06.txt draft-ietf-appsawg-webfinger-07.txt
Abstract Abstract
This specification defines the WebFinger protocol, which can be used This specification defines the WebFinger protocol, which can be used
to discover information about people or other entities on the to discover information about people or other entities on the
Internet using standard HTTP methods. Internet using standard HTTP methods.
Status of this Memo Status of this Memo
This Internet-Draft is submitted in full conformance with the This Internet-Draft is submitted in full conformance with the
skipping to change at page 1, line 34 skipping to change at page 1, line 34
Internet-Drafts are working documents of the Internet Engineering Internet-Drafts are working documents of the Internet Engineering
Task Force (IETF). Note that other groups may also distribute Task Force (IETF). Note that other groups may also distribute
working documents as Internet-Drafts. The list of current Internet- working documents as Internet-Drafts. The list of current Internet-
Drafts is at http://datatracker.ietf.org/drafts/current/. Drafts is at http://datatracker.ietf.org/drafts/current/.
Internet-Drafts are draft documents valid for a maximum of six months Internet-Drafts are draft documents valid for a maximum of six months
and may be updated, replaced, or obsoleted by other documents at any and may be updated, replaced, or obsoleted by other documents at any
time. It is inappropriate to use Internet-Drafts as reference time. It is inappropriate to use Internet-Drafts as reference
material or to cite them other than as "work in progress." material or to cite them other than as "work in progress."
This Internet-Draft will expire on May 29, 2013. This Internet-Draft will expire on June 2, 2013.
Copyright Notice Copyright Notice
Copyright (c) 2012 IETF Trust and the persons identified as the Copyright (c) 2012 IETF Trust and the persons identified as the
document authors. All rights reserved. document authors. All rights reserved.
This document is subject to BCP 78 and the IETF Trust's Legal This document is subject to BCP 78 and the IETF Trust's Legal
Provisions Relating to IETF Documents Provisions Relating to IETF Documents
(http://trustee.ietf.org/license-info) in effect on the date of (http://trustee.ietf.org/license-info) in effect on the date of
publication of this document. Please review these documents publication of this document. Please review these documents
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....................................................2 2. Terminology....................................................3
3. Overview.......................................................3 3. Overview.......................................................3
4. Example Use of WebFinger.......................................3 4. Example Use of WebFinger.......................................3
4.1. Locating a User's Blog....................................3 4.1. Locating a User's Blog....................................3
4.2. Identity Provider Discovery for OpenID Connect............5 4.2. Identity Provider Discovery for OpenID Connect............5
4.3. Auto-Configuration of Email Clients.......................6 4.3. Auto-Configuration of Email Clients.......................6
4.4. Retrieving Device Information.............................7 4.4. Retrieving Device Information.............................7
5. WebFinger Protocol.............................................8 5. WebFinger Protocol.............................................8
5.1. Performing a WebFinger Query..............................8 5.1. Performing a WebFinger Query..............................8
5.2. The JSON Resource Descriptor (JRD) Document...............9 5.2. The JSON Resource Descriptor (JRD)........................9
5.3. The "rel" Parameter.......................................9 5.2.1. expires..............................................9
5.4. WebFinger and URIs.......................................11 5.2.2. subject.............................................10
6. Cross-Origin Resource Sharing (CORS)..........................12 5.2.3. aliases.............................................10
7. Access Control................................................12 5.2.4. properties..........................................10
8. Hosted WebFinger Services.....................................13 5.2.5. links...............................................11
9. Security Considerations.......................................13 5.3. The "rel" Parameter......................................13
10. IANA Considerations..........................................15 5.4. WebFinger and URIs.......................................14
11. Acknowledgments..............................................15 6. Cross-Origin Resource Sharing (CORS)..........................15
12. References...................................................15 7. Access Control................................................15
12.1. Normative References....................................15 8. Hosted WebFinger Services.....................................16
12.2. Informative References..................................16 9. Security Considerations.......................................17
Author's Addresses...............................................17 10. IANA Considerations..........................................18
11. Acknowledgments..............................................19
12. References...................................................19
12.1. Normative References....................................19
12.2. Informative References..................................20
Author's Addresses...............................................20
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 using standard HTTP [2] methods. The entities on the Internet using standard HTTP [2] methods. The
WebFinger server returns a structured document that contains link WebFinger server returns a JavaScript Object Notation (JSON) [5]
relations, properties, and/or other information that is suitable for object that describes the resource being queried. The JSON object is
automated processing. For a person, the kinds of information that referred to as the JSON Resource Descriptor (JRD). The JRD contains
might be shared via WebFinger include a personal profile address, link relations, properties, titles, and other information that is
identity service, telephone number, or preferred avatar. For other suitable for automated processing. For a person, the kinds of
entities on the Internet, the server might return documents information that might be shared via WebFinger include a personal
containing link relations that allow a client to discover the amount profile address, identity service, telephone number, or preferred
of toner in a printer or the physical location of a server. avatar. For other entities on the Internet, the server might return
JRDs containing link relations that allow a client to discover the
amount of toner in a printer or the physical location of a server.
Information returned via WebFinger might be for direct human Information returned via WebFinger might be for direct human
consumption (e.g., 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).
2. Terminology 2. Terminology
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
"SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this
document are to be interpreted as described in RFC 2119 [1]. document are to be interpreted as described in RFC 2119 [1].
WebFinger makes heavy use of "Link Relations". Briefly, a Link WebFinger makes heavy use of "Link Relations". Briefly, a Link
Relation is an attribute and value pair used on the Internet wherein Relation is an attribute and value pair used on the Internet wherein
the attribute identifies the type of link to which the associated the attribute identifies the type of link to which the associated
value refers. In Hypertext Transfer Protocol (HTTP) and Web Linking value refers. In Hypertext Transfer Protocol (HTTP) and Web Linking
[4], the attribute is a "rel" and the value is an "href". WebFinger [4], the attribute is a "rel" and the value is an "href". WebFinger
also uses the "rel" attribute, where the "rel" value is either a also uses the "rel" attribute, where the "rel" value is either a
single IANA-registered link relation type [12] or a URI [6]. single IANA-registered link relation type [11] or a URI [6].
3. Overview 3. Overview
WebFinger enables the discovery of information about users, devices, WebFinger enables the discovery of information about users, devices,
and other entities that are associated with a host. Discovery and other entities that are associated with a host. Discovery
involves a single HTTP GET request to the well-known [3] "webfinger" involves a single HTTP GET request to the well-known [3] "webfinger"
resource at the target host and receiving back a JavaScript Object resource at the target host and receiving back a JavaScript Object
Notation (JSON) [5] Resource Descriptor (JRD) document [11] Notation (JSON) [5] Resource Descriptor (JRD) (see section 5.2)
containing link relations. The request MUST include the URI or IRI containing link relations, properties, titles, and other useful
[7] for the entity for which information is sought as a parameter information. The request MUST include the URI or IRI [7] for the
named "resource". entity for which information is sought as a parameter named
"resource".
Use of WebFinger is illustrated in the examples in Section 4, then Use of WebFinger is illustrated in the examples in Section 4, then
described more formally in Section 5. described more formally in Section 5.
4. Example Use of WebFinger 4. Example Use of WebFinger
This non-normative section shows a few sample uses of WebFinger. This non-normative section shows a few sample uses of WebFinger.
4.1. Locating a User's Blog 4.1. Locating a User's Blog
skipping to change at page 4, line 43 skipping to change at page 5, line 6
} }
}, },
{ {
"rel" : "vcard", "rel" : "vcard",
"href" : "http://www.example.com/~bob/bob.vcf" "href" : "http://www.example.com/~bob/bob.vcf"
} }
] ]
} }
The email client would take note of the "blog" link relation in the The email client would take note of the "blog" link relation in the
above JRD document that refers to Bob's blog. This URL would then be above JRD that refers to Bob's blog. This URL would then be
presented to you so that you could then visit his blog. The email 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 client might also note that Bob has published an avatar link relation
and use that picture to represent Bob inside the email client. and use that picture to represent Bob inside the email client.
Lastly, the client might consider the vcard [14] link relation in Lastly, the client might consider the vcard [15] link relation in
order to update contact information for Bob. order to update contact information for Bob.
In the above example, an "acct" URI [8] is used in the query, though In the above example, an "acct" URI [8] is used in the query, though
any valid alias for the user might also be used. An alias is a URI any valid alias for the user might also be used. An alias is a URI
that is different from the "subject" URI that identifies the same that is different from the "subject" URI that identifies the same
entity. In the above example, there is one "http" alias returned, entity. In the above example, there is one "http" alias returned,
though there might have been more than one. Had the "http:" URI though there might have been more than one. Had the "http:" URI
shown as an alias been used to query for information about Bob, the shown as an alias been used to query for information about Bob, the
query would have appeared as: query would have appeared as:
skipping to change at page 5, line 21 skipping to change at page 5, line 33
Host: example.com Host: example.com
The response would have been substantially the same, with the subject The response would have been substantially the same, with the subject
and alias information changed as necessary. Other information, such and alias information changed as necessary. Other information, such
as the expiration time might also change, but the set of link as the expiration time might also change, but the set of link
relations and properties would be the same with either response. relations and properties would be the same with either response.
4.2. Identity Provider Discovery for OpenID Connect 4.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 [16]. She would provide the web site with her OpenID OpenID Connect [17]. 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 server might utilize the "rel" parameter as described relation, the server might utilize the "rel" parameter as described
in section 5.3: in section 5.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
Host: example.com Host: example.com
The server might respond with a JSON Resource Descriptor document The server might respond with a JRD like this:
like this:
{ {
"expires" : "2012-11-16T19:41:35Z", "expires" : "2012-11-16T19:41:35Z",
"subject" : "acct:carol@example.com", "subject" : "acct:carol@example.com",
"aliases" : "aliases" :
[ [
"http://www.example.com/~carol/" "http://www.example.com/~carol/"
], ],
"properties" : "properties" :
{ {
"http://example.com/rel/role/" : "employee" "http://example.com/rel/role/" : "employee"
}, },
"links" : "links" :
[ [
{ {
"rel" : "http://openid.net/specs/connect/1.0/issuer", "rel" : "http://openid.net/specs/connect/1.0/issuer",
"href" : "https://openid.example.com/" "href" : "https://openid.example.com/"
skipping to change at page 6, line 29 skipping to change at page 6, line 39
her email client. Her email client might issue the following query: her email client. Her email client might issue the following query:
GET /.well-known/webfinger? GET /.well-known/webfinger?
resource=mailto%3Asue%40example.com HTTP/1.1 resource=mailto%3Asue%40example.com HTTP/1.1
Host: example.com Host: example.com
The response from the server would contain entries for the various The response from the server would contain entries for the various
protocols, transport options, and security options. If there are protocols, transport options, and security options. If there are
multiple options, the server might return a link relation that for multiple options, the server might return a link relation that for
each of the valid options and the client or Sue might select which each of the valid options and the client or Sue might select which
option to choose. Since JRD documents list link relations in a option to choose. Since JRDs list link relations in a specific
specific order, then the most-preferred choices could be presented order, then the most-preferred choices could be presented first.
first. Consider this response: Consider this response:
{ {
"subject" : "mailto:sue@example.com", "subject" : "mailto:sue@example.com",
"links" : "links" :
[ [
{ {
"rel" : "http://example.net/rel/smtp-server", "rel" : "http://example.net/rel/smtp-server",
"properties" : "properties" :
{ {
"host" : "smtp.example.com", "http://example.net/email/host" : "smtp.example.com",
"port" : "587", "http://example.net/email/port" : "587",
"login-required" : "yes", "http://example.net/email/login-required" : "yes",
"transport" : "starttls" "http://example.net/email/transport" : "starttls"
} }
}, },
{ {
"rel" : "http://example.net/rel/imap-server", "rel" : "http://example.net/rel/imap-server",
"properties" : "properties" :
{ {
"host" : "imap.example.com", "http://example.net/email/host" : "imap.example.com",
"port" : "993", "http://example.net/email/port" : "993",
"transport" : "ssl" "http://example.net/email/transport" : "ssl"
} }
} }
] ]
} }
In this example, you can see that the WebFinger server advertises an In this example, you can see that the WebFinger server advertises an
SMTP service and an IMAP service. In this example, the "href" SMTP service and an IMAP service. In this example, the "href"
entries associated with the link relation are absent. This is valid entries associated with the link relation are absent. This is valid
when there is no external reference that needs to be made. when there is no external reference that needs to be made.
skipping to change at page 7, line 50 skipping to change at page 8, line 10
"links" : "links" :
[ [
{ {
"rel" : "http://example.com/rel/tipsi", "rel" : "http://example.com/rel/tipsi",
"href" : "http://192.168.1.5/npap/" "href" : "http://192.168.1.5/npap/"
} }
] ]
} }
While this example is fictitious, you can imagine that perhaps the While this example is fictitious, you can imagine that perhaps the
Transport Independent, Printer/System Interface [15] may be enhanced Transport Independent, Printer/System Interface [16] may be enhanced
with a web interface that allows a device that understands the TIP/SI with a web interface that allows a device that understands the TIP/SI
web interface specification to query the printer for toner levels. web interface specification to query the printer for toner levels.
5. WebFinger Protocol 5. WebFinger Protocol
WebFinger is a simple HTTP-based web service that utilizes the JSON WebFinger is a simple HTTP-based web service that returns a JSON
Resource Descriptor (JRD) document format and the Cross-Origin Resource Descriptor (JRD) to convey information about an entity on
Resource Sharing (CORS) [10] specification. the Internet and the Cross-Origin Resource Sharing (CORS) [10]
specification to facilitate queries made via a web browser.
This specification defines URI parameters that are passed from the This specification defines URI parameters that are passed from the
client to the server when issuing a request. These parameters, client to the server when issuing a request. These parameters,
"resource" and "rel", and the parameter values are included in the "resource" and "rel", and the parameter values are included in the
"query" component of the URI (see Section 3.4 of RFC 3986). To "query" component of the URI (see Section 3.4 of RFC 3986). To
construct the "query" component, the client performs the following construct the "query" component, the client performs the following
steps. First, each parameter value is percent-encoded as per Section steps. First, each parameter value is percent-encoded as per Section
2.1 of RFC 3986. Next, the client constructs a string to be placed 2.1 of RFC 3986. Next, the client constructs a string to be placed
in the query component by concatenating the name of the first in the query component by concatenating the name of the first
parameter together with an equal sign ("=") and the percent-encoded parameter together with an equal sign ("=") and the percent-encoded
skipping to change at page 8, line 35 skipping to change at page 8, line 45
value is unspecified. value is unspecified.
5.1. Performing a WebFinger Query 5.1. Performing a WebFinger Query
WebFinger clients issue queries to the well-known resource /.well- WebFinger clients issue queries to the well-known resource /.well-
known/webfinger. All queries MUST include the "resource" parameter known/webfinger. All queries MUST include the "resource" parameter
exactly once and set to the value of the URI for which information is exactly once and set to the value of the URI for which information is
being sought. If the "resource" parameter is absent or malformed, being sought. If the "resource" parameter is absent or malformed,
the WebFinger server MUST return a 400 status code. the WebFinger server MUST return a 400 status code.
Clients MUST first attempt a query the server using HTTPS and utilize Clients MUST query the server using HTTPS and utilize HTTP only if an
HTTP only if an HTTPS connection cannot be established. If the HTTPS HTTPS connection cannot be established, and then only if the client
issuing the query will not utilize information in the response in
such a way as to compromise user security or privacy. As an example,
a client using WebFinger to facilitate logging into a web site MUST
only utilize HTTPS to ensure that a user is not misdirected to a
rogue web site that might steal the user's credentials. If the HTTPS
server has an invalid certificate or returns an HTTP status code server has an invalid certificate or returns an HTTP status code
indicating some error, including a 4xx or 5xx, the client MUST NOT indicating some error, including a 4xx or 5xx, the client MUST NOT
use HTTP in attempt to complete the discovery. use HTTP in attempt to complete the discovery.
WebFinger servers MUST return JRD documents as the default WebFinger servers MUST return a JRD as the representation for the
representation for the resource. A client MAY include the "Accept" resource if the client requests no format explicitly via the HTTP
header to indicate a desired representation, though no other "Accept" header. A client MAY include the "Accept" header to
representation is defined in this specification. For the JRD indicate a desired representation, though no other representation is
document, the media type is "application/json" [5]. defined in this specification. The media type used for the JSON
Resource Descriptor (JRD) is "application/json" [5].
If the client queries the WebFinger server and provides a URI for If the client queries the WebFinger server and provides a URI for
which the server has no information, the server MUST return a 404 which the server has no information, the server MUST return a 404
status code. status code.
WebFinger servers can include cache validators in a response to WebFinger servers can include cache validators in a response to
enable conditional requests by clients and/or expiration times as per enable conditional requests by clients and/or expiration times as per
RFC 2616 section 13. RFC 2616 section 13.
5.2. The JSON Resource Descriptor (JRD) Document 5.2. The JSON Resource Descriptor (JRD)
The JSON Resource Descriptor (JRD) document is formally described in The JSON Resource Descriptor (JRD) is a JSON object that is comprised
Appendix A of [11]. There is a RECOMMENDED order of JRD name/value of name/value pairs appearing in this RECOMMENDED order:
pairs. Further, WebFinger requires some name/value pairs and some
are optional. The following list indicates the preferred order and
comments on the presence or absence of name/value pairs:
o "expires" (name/value pair) is optional o expires
o "subject" (name/value pair) is required and MUST be the value o subject
of the "resource" parameter o aliases
o "aliases" (array) is optional and absence or an empty array o properties
are semantically the same o links
o "properties" (object) is optional and absence or an empty
object are semantically the same
o "links" (array) is optional and absence or an empty array are
semantically the same
Values within the "links" array are presented by the server in order The members "expires" and "subject" are name/value pairs whose value
of preference. are strings, "aliases" is an array of strings, "properties" is an
object comprised of name/value pairs whose values are strings, and
"links" is an array of objects that contain link relation
information.
The "links" array is comprised of several name/value pairs. As When processing a JRD, the client MUST ignore any unknown member and
above, the following list indicates the preferred order within a not treat the presence of an unknown member as an error.
"links" array and comments on the presence or absence of name/value
pairs within the array:
o "rel" (name/value pair) is required Below, each of these members of the JRD is described in more detail.
o "type" (name/value pair) is optional
o "href" (name/value pair) is optional
o "template" (name/value pair) is forbidden
o "titles" (object) is optional and absence or an empty object
are semantically the same
o "properties" (object) is optional and absence or an empty
object are semantically the same
Clients MUST ignore any unknown or forbidden name/value pair received 5.2.1. expires
in the JRD document.
The value of the "expires" member is a string that indicates the date
and time after which the JRD SHOULD be considered expired and no
longer utilized. The format of the date/time string is:
YYYY-MM-DDTHH:MM:SSZ
Here, "YYYY" indicates the four-digit year, "MM" indicates the two-
digit month (in the range of 01 to 12), and "DD" indicates the two-
digit day of the month (in the range of 01 to 31). The "T" is
literally an ASCII "T" that exists merely as a separator between the
date and the time. The "HH" indicates the two-digit hour of the day
(in the range of 01 to 12), "MM" indicates the two-digit minute of
the day (in the range of 00 to 59), and "SS" indicates the two-digit
number of seconds (in the range of 00 to 59). A colon (":")
character MUST separate the hours, minutes, and seconds values, and a
hyphen ("-") MUST separate the year, month, and day in the string.
The "Z" at the end of the string is literally an ASCII "Z" that
indicates UTC time and MUST be present. The "expires" string MUST
utilize UTC time. An example of the "expires" member is:
"expires" : "2012-11-16T19:41:35Z"
The server MAY include the "expires" header in a JRD and clients
SHOULD honor the value if present.
5.2.2. subject
The value of the "subject" member is a string that MUST be set to the
same value as the "resource" parameter in the client request. This
is a URI that identifies the entity for which the client queried the
server.
The "subject" member MUST be included in the JRD.
5.2.3. aliases
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
absolute URI.
The server MAY include the "aliases" array in the JRD.
5.2.4. properties
The "properties" object is comprised of zero or more name/value pairs
whose names are absolute URIs and whose values are strings or null.
Properties are used to convey additional information about the
subject of the JRD. As an example, consider this use of
"properties":
"properties" : { "http://webfinger.net/rel/name" : "Bob Smith" }
The server MAY include the "properties" member in the JRD.
5.2.5. links
The "links" array contains zero or more elements that contain the
link relation information. Each element of the array is an object
comprised of the following name/value pairs in this RECOMMENDED
order:
o rel
o type
o href
o titles
o properties
The members "rel", "type", and "href" are a name/value pairs whose
values are strings, "titles" and "properties" are objects comprised
of name/value pairs whose values are strings.
The order of elements in the "links" array indicates an order of
preference. Thus, if there are two or more link relations having the
same "rel" value, the first link relation would indicate the user's
preferred link relation.
Servers MAY include the "links" array in the JRD.
Below, each of the members of the objects found 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
from any other object in the array; any requirement on the server to
include a given member in the link relation object refers only to
that particular object.
5.2.5.1. rel
The value of the "rel" member is a string that is either an absolute
URI or a registered relation type [11] (see RFC 5988 [4]). The value
of the "rel" member MUST contain exactly one URI string or registered
relation type and MUST NOT contain a space-separated list of URIs or
registered relation types. The URI or registered relation type
identifies the type of the link relation. The other members of the
object have meaning only once the type of link relation is
understood. In some instances, the link relation will have
associated semantics that allow a client to query for other resources
on the Internet. In other instances, the link relation will have
associated semantics that allow the client to utilize the other
members of the link relation object without fetching additional
external resources.
Servers MUST include the "rel" member in the link relation object.
5.2.5.2. type
The value of the "type" member is a string that indicates the media
type [12] of the linked resource (see RFC 4288 [13]).
Servers MAY include the "type" member in the link relation object.
5.2.5.3. href
The value of the "href" member is a string that contains a URI
pointing to the linked resource.
Servers MAY include the "href" member in the link relation object.
5.2.5.4. titles
The "titles" object is comprised of zero or more name/value pairs
whose name is a language tag [14] or the string "default". The
string is human-readable and describes the link relation. More than
one title for the link relation MAY be provided for the benefit of
users who utilize the link relation and, if used, a language
identifier SHOULD be duly used as the name. If the language is
unknown or unspecified, then the name is "default".
A server SHOULD NOT include more than one title named with the same
language tag (or "default") within the link relation object. The
client behavior is undefined if a link relation object includes more
than one title named with the same language tag (or "default"),
though the client MUST NOT treat this as an error. The client can
select whichever title or titles it wishes to utilize.
Here is an example of the titles object:
"titles" :
{
"en-us" : "The Magical World of Bob",
"fr" : "Le monde magique de Bob"
}
The server MAY include the "titles" member in the link relation
object.
5.2.5.5. properties
The "properties" object within the link relation object is comprised
of zero or more name/value pairs whose names are absolute URIs and
whose values are strings or null. Properties are used to convey
additional information about the link relation. As an example,
consider this use of "properties":
"properties" : { "http://example.net/mail/port" : "993" }
The server MAY include the "properties" member in the link relation
object.
5.3. The "rel" Parameter 5.3. The "rel" Parameter
WebFinger defines the "rel" parameter to request only a subset of the When issuing a request to the server, the client MAY utilize the
information that would otherwise be returned without the "rel" "rel" parameter to request only a subset of the information that
parameter. When the "rel" parameter is used, only the link relations would otherwise be returned without the "rel" parameter. When the
that match the link relations provided via "rel" are included in the "rel" parameter is used, only the link relations that match the link
array of links returned in the JSON Resource Descriptor document. relations provided via "rel" are included in the array of links
All other information normally present in a resource descriptor is returned in the JRD. All other information normally present in a
present in the resource descriptor, even when "rel" is employed. resource descriptor is present in the resource descriptor, even when
"rel" is employed.
The "rel" parameter MAY be transmitted to the server multiple times The "rel" parameter MAY be transmitted to the server multiple times
in order to request multiple types of link relations. in order to request multiple types of link relations.
The purpose of the "rel" parameter is to return a subset of The purpose of the "rel" parameter is to return a subset of
resource's link relations. Use of the parameter might reduce resource's link relations. Use of the parameter might reduce
processing requirements on either the client or server, and it might processing requirements on either the client or server, and it might
also reduce the bandwidth required to convey the partial resource also reduce the bandwidth required to convey the partial resource
descriptor, especially if there are numerous link relation values to descriptor, especially if there are numerous link relation values to
convey for a given resource. convey for a given resource.
Support for the "rel" parameter is OPTIONAL, but RECOMMENDED on the Support for the "rel" parameter is OPTIONAL, but RECOMMENDED on the
server. Should the server not support the "rel" parameter, it MUST server. Should the server not support the "rel" parameter, it MUST
ignore it and process the request as if any "rel" parameter values ignore it and process the request as if no "rel" parameter values
were not 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
4.1, but uses the "rel" parameter in order to select two link 4.1, but uses the "rel" parameter in order to select two link
relations: relations:
GET /.well-known/webfinger? GET /.well-known/webfinger?
resource=acct%3Abob%40example.com& resource=acct%3Abob%40example.com&
rel=http%3A%2F%2Fwebfinger.net%2Frel%2Fprofile-page& rel=http%3A%2F%2Fwebfinger.net%2Frel%2Fprofile-page&
rel=vcard HTTP/1.1 rel=vcard HTTP/1.1
Host: example.com Host: example.com
skipping to change at page 11, line 4 skipping to change at page 14, line 20
], ],
"properties" : "properties" :
{ {
"http://example.com/rel/role/" : "employee" "http://example.com/rel/role/" : "employee"
}, },
"links" : "links" :
[ [
{ {
"rel" : "http://webfinger.net/rel/profile-page", "rel" : "http://webfinger.net/rel/profile-page",
"href" : "http://www.example.com/~bob/" "href" : "http://www.example.com/~bob/"
}, },
{ {
"rel" : "vcard", "rel" : "vcard",
"href" : "http://www.example.com/~bob/bob.vcf" "href" : "http://www.example.com/~bob/bob.vcf"
} }
] ]
} }
As you can see, the server returned only the link relations requested As you can see, the server returned only the link relations requested
by the client, but also included the other parts of the JSON resource by the client, but also included the other parts of the JRD.
Descriptor document.
In the event that a client requests links for link relations that are In the event that a client requests links for link relations that are
not defined for the specified resource, a resource descriptor MUST be not defined for the specified resource, a resource descriptor MUST be
returned. In the returned JRD, the "links" array MAY be absent, returned. In the returned JRD, the "links" array MAY be absent,
empty, or contain only links that did match a provided "rel" value. empty, or contain only links that did match a provided "rel" value.
The server MUST NOT return a 404 status code when a particular link The server MUST NOT return a 404 status code when a particular link
relation specified via "rel" is not defined for the resource, as a relation specified via "rel" is not defined for the resource, as a
404 status code is reserved for indicating that the resource itself 404 status code is reserved for indicating that the resource itself
(e.g., either /.well-known/webfinger or the resource indicated via (e.g., either /.well-known/webfinger or the resource indicated via
the "resource" parameter) does not exist. the "resource" parameter) does not exist.
skipping to change at page 15, line 30 skipping to change at page 18, line 42
This specification registers the "webfinger" well-known URI in the This specification registers the "webfinger" well-known URI in the
Well-Known URI Registry as defined by [3]. Well-Known URI Registry as defined by [3].
URI suffix: webfinger URI suffix: webfinger
Change controller: IETF Change controller: IETF
Specification document(s): RFC QQQ Specification document(s): RFC QQQ
Related information: The JSON Resource Descriptor (JRD) documents Related information: The response from WebFinger server will be a
obtained via the WebFinger web service are described in RFC 6415 JSON Resource Descriptor (JRD) as described in Section 5.2 of RFC
Appendix A and RFC QQQ. QQQ.
[RFC EDITOR: Please replace "QQQ" references in this section with the [RFC EDITOR: Please replace "QQQ" references in this section with the
number for this RFC.] number for this RFC.]
11. Acknowledgments 11. Acknowledgments
The authors would like to acknowledge Eran Hammer-Lahav, Blaine Cook, The authors would like to acknowledge Eran Hammer-Lahav, Blaine Cook,
Brad Fitzpatrick, Laurent-Walter Goix, Joe Clarke, Michael B. Jones, Brad Fitzpatrick, Laurent-Walter Goix, Joe Clarke, Michael B. Jones,
Peter Saint-Andre, Dick Hardt, Tim Bray, and Joe Gregorio for their Peter Saint-Andre, Dick Hardt, Tim Bray, and Joe Gregorio for their
invaluable input. invaluable input.
skipping to change at page 16, line 33 skipping to change at page 19, line 47
[8] Saint-Andre, P., "The 'acct' URI Scheme", draft-ietf-appsawg- [8] Saint-Andre, P., "The 'acct' URI Scheme", draft-ietf-appsawg-
acct-uri-01, October 2012. acct-uri-01, October 2012.
[9] Duerst, M., Masinter, L., and J. Zawinski, "The 'mailto' URI [9] Duerst, M., Masinter, L., and J. Zawinski, "The 'mailto' URI
Scheme", RFC 6068, October 2010. Scheme", RFC 6068, October 2010.
[10] Van Kesteren, A., "Cross-Origin Resource Sharing", W3C CORS [10] Van Kesteren, A., "Cross-Origin Resource Sharing", W3C CORS
http://www.w3.org/TR/cors/, July 2010. http://www.w3.org/TR/cors/, July 2010.
[11] Hammer-Lahav, E. and Cook, B., "Web Host Metadata", RFC 6415, [11] IANA, "Link Relations", http://www.iana.org/assignments/link-
October 2011. relations/.
12.2. Informative References [12] IANA, "MIME Media Types",
http://www.iana.org/assignments/media-types/index.html.
[12] IANA, "Link Relations", http://www.iana.org/assignments/link- [13] Freed, N., Klensin, J., "Media Type Specifications and
relations/. Registration Procedures", RFC 4288, December 2005.
[13] Zimmerman, D., "The Finger User Information Protocol", RFC [14] Phillips, A., Davis, M., "Tags for Identifying Languages", RFC
1288, December 1991. 5646, January 2001.
[14] Perreault, S., "vCard Format Specification", RFC 6350, August 12.2. Informative References
[15] Perreault, S., "vCard Format Specification", RFC 6350, August
2011. 2011.
[15] "Transport Independent, Printer/System Interface", IEEE Std [16] "Transport Independent, Printer/System Interface", IEEE Std
1284.1-1997, 1997. 1284.1-1997, 1997.
[16] Sakimura, N., Bradley, J., Jones, M., de Medeiros, B., [17] Sakimura, N., Bradley, J., Jones, M., de Medeiros, B.,
Mortimore, C., and E. Jay, "OpenID Connect Messages 1.0", June Mortimore, C., and E. Jay, "OpenID Connect Messages 1.0", June
2012, http://openid.net/specs/openid-connect-messages-1_0.html. 2012, http://openid.net/specs/openid-connect-messages-1_0.html.
Author's Addresses Author's Addresses
Paul E. Jones Paul E. Jones
Cisco Systems, Inc. Cisco Systems, Inc.
7025 Kit Creek Rd. 7025 Kit Creek Rd.
Research Triangle Park, NC 27709 Research Triangle Park, NC 27709
USA USA
 End of changes. 40 change blocks. 
114 lines changed or deleted 274 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/