draft-ietf-appsawg-webfinger-09.txt   draft-ietf-appsawg-webfinger-10.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: July 28, 2013 Joseph Smarr Expires: August 8, 2013 Joseph Smarr
Google Google
January 28, 2013 February 8, 2013
WebFinger WebFinger
draft-ietf-appsawg-webfinger-09.txt draft-ietf-appsawg-webfinger-10.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. WebFinger discovers
information for a URI that might not be usable as a locator
otherwise, such as account or email URIs.
Status of this Memo Status of this Memo
This Internet-Draft is submitted in full conformance with the This Internet-Draft is submitted in full conformance with the
provisions of BCP 78 and BCP 79. provisions of BCP 78 and BCP 79.
Internet-Drafts are working documents of the Internet Engineering Internet-Drafts are working documents of the Internet Engineering
Task Force (IETF). Note that other groups may also distribute Task Force (IETF). Note that other groups may also distribute
working documents as Internet-Drafts. The list of current Internet- working documents as Internet-Drafts. The list of current Internet-
Drafts is at http://datatracker.ietf.org/drafts/current/. Drafts is at http://datatracker.ietf.org/drafts/current/.
Internet-Drafts are draft documents valid for a maximum of six months Internet-Drafts are draft documents valid for a maximum of six months
and may be updated, replaced, or obsoleted by other documents at any and may be updated, replaced, or obsoleted by other documents at any
time. It is inappropriate to use Internet-Drafts as reference time. It is inappropriate to use Internet-Drafts as reference
material or to cite them other than as "work in progress." material or to cite them other than as "work in progress."
This Internet-Draft will expire on July 28, 2013. This Internet-Draft will expire on August 8, 2013.
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 14 skipping to change at page 2, line 16
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. Locating a User's Blog....................................3
3.2. Identity Provider Discovery for OpenID Connect............5 3.2. Identity Provider Discovery for OpenID Connect............5
3.3. Auto-Configuration of Email Clients.......................6 3.3. Auto-Configuration of Email Clients.......................6
3.4. Retrieving Device Information.............................7 3.4. Retrieving Device Information.............................7
4. WebFinger Protocol.............................................7 4. WebFinger Protocol.............................................8
4.1. Constructing a WebFinger Query............................8 4.1. Constructing a WebFinger Request URI......................8
4.2. Performing a WebFinger Query..............................8 4.2. Performing a WebFinger Query..............................9
4.3. The "rel" Parameter.......................................9 4.3. The "rel" Parameter.......................................9
4.4. The JSON Resource Descriptor (JRD).......................10 4.4. The JSON Resource Descriptor (JRD).......................11
4.4.1. expires.............................................11 4.4.1. subject.............................................11
4.4.2. subject.............................................11 4.4.2. aliases.............................................12
4.4.3. aliases.............................................11 4.4.3. properties..........................................12
4.4.4. properties..........................................11 4.4.4. links...............................................12
4.4.5. links...............................................12
4.5. WebFinger and URIs.......................................14 4.5. WebFinger and URIs.......................................14
5. Cross-Origin Resource Sharing (CORS)..........................14 5. Cross-Origin Resource Sharing (CORS)..........................14
6. Access Control................................................15 6. Access Control................................................15
7. Hosted WebFinger Services.....................................15 7. Hosted WebFinger Services.....................................15
8. Security Considerations.......................................16 8. Security Considerations.......................................16
9. IANA Considerations...........................................17 9. IANA Considerations...........................................18
10. Acknowledgments..............................................18 9.1. Well-Known URI...........................................18
11. References...................................................18 9.2. JSON Resource Descriptor (JRD) Media Type................18
11.1. Normative References....................................18 10. Acknowledgments..............................................20
11.2. Informative References..................................19 11. References...................................................20
Author's Addresses...............................................20 11.1. Normative References....................................20
11.2. Informative References..................................21
Author's Addresses...............................................22
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 server returns a JavaScript secure transport [14]. A WebFinger resource returns a JavaScript
Object Notation (JSON) [5] object that describes a resource 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 server might return JRDs containing link Internet, a WebFinger resource might return JRDs containing link
relations that allow a client to discover, for example, the amount of relations [10] that enable a client to discover, for example, the
toner in a printer or the physical location of a server. 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).
Use of WebFinger is illustrated in the examples in Section 3 and Use of WebFinger is illustrated in the examples in Section 3 and
described more formally in Section 4. described more formally in Section 4.
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". A Link Relation is an
Relation is an attribute and value pair used on the Internet wherein attribute-and-value pair in which the attribute identifies the type
the attribute identifies the type of link to which the associated of relationship between the linked entity or resource and the
value refers. In HTTP and Web Linking [4], the attribute is a "rel" information specified in the value. In Web Linking [4], the link
and the value is an "href". WebFinger also uses the "rel" attribute, relation is represented using an HTTP entity-header of "Link", where
where the "rel" value is either a single IANA-registered link the "rel" attribute specifies the type of relationship and the "href"
relation type [10] or a URI [6]. attribute specifies the information that is linked to the entity or
resource. In WebFinger, the same concept is represented using a JSON
array of "links" objects, where each member named "rel" specifies the
type of relationship and each member named "href" specifies the
information that is linked to the entity or resource. Note that
WebFinger narrows the scope of a link relation beyond what is defined
for Web Linking by stipulating that the value of the "rel" member
needs to be either a single IANA-registered link relation type [10]
or 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. Locating a User's Blog
Assume you receive an email from Bob and he refers to something he Assume you receive an email from Bob and he refers to something he
posted on his blog, but you do not know where Bob's blog is located. posted on his blog, but you do not know where Bob's blog is located.
It would be simple to discover the address of Bob's blog if he makes It would be simple to discover the address of Bob's blog if he made
that information available via WebFinger. that information available via WebFinger.
Assume your email client can discover the blog for you. After Assume your email client can discover the blog for you. After
receiving the message from Bob (bob@example.com), you instruct your receiving the message from Bob (bob@example.com), your email client
email client to perform a WebFinger query. It does so by issuing the performs a WebFinger query either automatically or at your command.
following HTTPS [14] query to example.com: It does so by issuing the following HTTPS [14] query to example.com:
GET /.well-known/webfinger? GET /.well-known/webfinger?
resource=acct%3Abob%40example.com HTTP/1.1 resource=acct%3Abob%40example.com HTTP/1.1
Host: example.com Host: example.com
The server might then respond with a message like this: The server might then respond with a message like this:
HTTP/1.1 200 OK HTTP/1.1 200 OK
Access-Control-Allow-Origin: * Access-Control-Allow-Origin: *
Content-Type: application/json; charset=UTF-8 Content-Type: application/jrd+json
{ {
"expires" : "2012-11-16T19:41:35Z",
"subject" : "acct:bob@example.com", "subject" : "acct:bob@example.com",
"aliases" : "aliases" :
[ [
"http://www.example.com/~bob/" "http://www.example.com/~bob/"
], ],
"properties" : "properties" :
{ {
"http://example.com/ns/role/" : "employee" "http://example.com/ns/role/" : "employee"
}, },
"links" : "links" :
[ [
{ {
"rel" : "http://webfinger.net/rel/avatar", "rel" : "http://webfinger.example/rel/avatar",
"type" : "image/jpeg", "type" : "image/jpeg",
"href" : "http://www.example.com/~bob/bob.jpg" "href" : "http://www.example.com/~bob/bob.jpg"
}, },
{ {
"rel" : "http://webfinger.net/rel/profile-page", "rel" : "http://webfinger.example/rel/profile-page",
"href" : "http://www.example.com/~bob/" "href" : "http://www.example.com/~bob/"
}, },
{ {
"rel" : "blog", "rel" : "http://webfinger.example/rel/blog",
"type" : "text/html", "type" : "text/html",
"href" : "http://blogs.example.com/bob/", "href" : "http://blogs.example.com/bob/",
"titles" : "titles" :
{ {
"en-us" : "The Magical World of Bob", "en-us" : "The Magical World of Bob",
"fr" : "Le monde magique de Bob" "fr" : "Le Monde Magique de Bob"
} }
}, },
{ {
"rel" : "vcard", "rel" : "http://webfinger.example/rel/businesscard",
"href" : "https://www.example.com/~bob/bob.vcf" "href" : "https://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 link relation in the above
above JRD that refers to Bob's blog. This URL would then be 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 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 [16] link relation in Lastly, the client might automatically retrieve the data located at
order to update contact information for Bob. 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 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 any valid alias for the user might also be used. See Section 4.5 for
more information on WebFinger and URIs. more information on WebFinger and URIs.
An alias is a URI that is different from the "subject" URI that An alias is a URI that is different from the "subject" URI, yet
identifies the same entity. In the above example, there is one identifies the same entity. In the above example, there is one
"http" alias returned, though there might have been more than 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 Had the "http:" URI shown as an alias been used to query for
information about Bob, the query would have appeared as: information about Bob, the query would have appeared as:
GET /.well-known/webfinger? GET /.well-known/webfinger?
resource=http%3A%2F%2Fwww.example.com%2F~bob%2F HTTP/1.1 resource=http%3A%2F%2Fwww.example.com%2F~bob%2F HTTP/1.1
Host: www.example.com Host: www.example.com
Note that the host queried in this example is different than for the 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 acct URI example, since the URI refers to a different host. Either
this host would provide a response, or it would redirect the client this host would provide a response, or it would redirect the client
to another host (e.g., redirect back to example.com). Either way, to another host (e.g., redirect back to example.com). Either way,
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.
as the expiration time might also change, but the set of link
relations and properties would be the same with either response.
3.2. Identity Provider Discovery for OpenID Connect 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 [18]. 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 WebFinger resource might utilize the "rel" parameter as
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
Host: example.com Host: example.com
The server might respond with a JRD like this: The server might respond like this:
HTTP/1.1 200 OK
Access-Control-Allow-Origin: *
Content-Type: application/jrd+json
{ {
"expires" : "2012-11-16T19:41:35Z",
"subject" : "acct:carol@example.com", "subject" : "acct:carol@example.com",
"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"
} }
] ]
} }
Since the "rel" parameter only filters the link relations returned by Since the "rel" parameter only serves to filter the link relations
the server, other name/value pairs in the response, including any returned by the resource, other name/value pairs in the response,
aliases or properties, would be returned. Also, since support for including any aliases or properties, would be returned. Also, since
the "rel" parameter is optional, the client must not assume the support for the "rel" parameter is OPTIONAL, the client must not
"links" array will contain only the requested link relation. assume the "links" array will contain only the requested link
relation.
3.3. Auto-Configuration of Email Clients 3.3. Auto-Configuration of Email Clients
WebFinger could be used to auto-provision an email client with basic WebFinger could be used to auto-provision an email client with basic
configuration data. Suppose that sue@example.com wants to configure configuration data. Suppose that sue@example.com wants to configure
her email client. Her email client might issue the following query: her email client. Her email client might issue the following query:
GET /.well-known/webfinger? GET /.well-known/webfinger?
resource=mailto%3Asue%40example.com HTTP/1.1 resource=mailto%3Asue%40example.com HTTP/1.1
Host: example.com Host: example.com
The response from the server would contain entries for the various The returned resource representation would contain entries for the
protocols, transport options, and security options. If there are various protocols, transport options, and security options. If there
multiple options, the server might return a link relation that for are multiple options, the resource representation might include a
each of the valid options and the client or Sue might select which link relation for each of the valid options, and the client or Sue
option to choose. Since JRDs list link relations in a specific might select which option to choose. Since JRDs list link relations
order, then the most-preferred choices could be presented first. in a specific order, then the most-preferred choices could be
Consider this response: presented first. Consider this response:
{ HTTP/1.1 200 OK
"subject" : "mailto:sue@example.com", Access-Control-Allow-Origin: *
"links" : Content-Type: application/jrd+json
[
{ {
"rel" : "http://example.net/rel/smtp-server", "subject" : "mailto:sue@example.com",
"properties" : "links" :
[
{ {
"http://example.net/email/host" : "smtp.example.com", "rel" : "http://webfinger.example/rel/smtp-server",
"http://example.net/email/port" : "587", "properties" :
"http://example.net/email/login-required" : "yes", {
"http://example.net/email/transport" : "starttls" "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://example.net/rel/imap-server", }
"properties" : },
{ {
"http://example.net/email/host" : "imap.example.com", "rel" : "http://webfinger.example/rel/imap-server",
"http://example.net/email/port" : "993", "properties" :
"http://example.net/email/transport" : "ssl" {
"http://webfinger.example/email/host" : "imap.example.com",
"http://webfinger.example/email/port" : "993",
"http://webfinger.example/email/transport" : "ssl"
}
} }
} ]
] }
}
In this example, you can see that the WebFinger server advertises an In this example, you can see that the WebFinger resource
SMTP service and an IMAP service. In this example, the "href" representation advertises an SMTP service and an IMAP service. In
entries associated with the link relation are absent. This is valid this example, the "href" entries associated with the link relation
when there is no external reference that needs to be made. are absent. This is valid when there is no additional reference that
needs to be made.
3.4. Retrieving Device Information 3.4. Retrieving Device Information
As another example, suppose there are printers on the network and you As another example, suppose there are printers on the network and you
would like to check the current toner level for a particular printer would like to check the current toner level for a particular printer
identified via the URI device:p1.example.com. While the "device" URI identified via the URI device:p1.example.com. While the "device" URI
scheme is not presently specified, we use it here for illustrative scheme is not presently specified, we use it here for illustrative
purposes. purposes.
Following the procedures similar to those above, a query may be Following the procedures similar to those above, a query may be
skipping to change at page 7, line 30 skipping to change at page 7, line 52
GET /.well-known/webfinger? GET /.well-known/webfinger?
resource=device%3Ap1.example.com HTTP/1.1 resource=device%3Ap1.example.com HTTP/1.1
Host: p1.example.com Host: p1.example.com
The link relations that are returned for a device may be quite The link relations that are returned for a device may be quite
different than those for user accounts. Perhaps we may see a different than those for user accounts. Perhaps we may see a
response like this: response like this:
HTTP/1.1 200 OK HTTP/1.1 200 OK
Access-Control-Allow-Origin: * Access-Control-Allow-Origin: *
Content-Type: application/json; charset=UTF-8 Content-Type: application/jrd+json
{ {
"subject" : "device:p1.example.com", "subject" : "device:p1.example.com",
"links" : "links" :
[ [
{ {
"rel" : "http://example.com/rel/tipsi", "rel" : "http://webfinger.example/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 [17] may be enhanced Transport Independent, Printer/System Interface [17] may be enhanced
with a web interface that allows a device that understands the TIP/SI with a web interface enabling 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.
4. WebFinger Protocol 4. WebFinger Protocol
WebFinger is a simple HTTP-based web service that returns a JSON A WebFinger resource is a well-known URI [3] using the HTTPS scheme.
Resource Descriptor (JRD) to convey information about an entity on WebFinger resources MUST NOT be served with any other URI scheme
the Internet and the Cross-Origin Resource Sharing (CORS) [9] (such as HTTP).
specification to facilitate queries made via a web browser.
4.1. Constructing a WebFinger Query GET requests to a WebFinger resource convey the URI to perform the
query upon in the URI's query string; see Section 4.1 for details.
This specification defines URI parameters that are passed from the The WebFinger resource returns a JSON Resource Descriptor (JRD) as
client to the server when issuing a request. These parameters, the resource representation to convey information about an entity on
"resource" and "rel", and the parameter values are included in the the Internet. Also, the Cross-Origin Resource Sharing (CORS) [9]
"query" component of the URI (see Section 3.4 of RFC 3986). To specification is utilized to facilitate queries made via a web
construct the "query" component, the client performs the following browser.
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 4.1. Constructing a WebFinger Request URI
in the query component by concatenating the name of the first
parameter together with an equal sign ("=") and the percent-encoded This specification defines parameters that can be passed from the
parameter value. For any subsequent parameters, the client appends client to the WebFinger resource when issuing a request. These
an ampersand ("&") to the string, the name of the next parameter, an parameters, "resource" and "rel", and the parameter values are
equal sign, and percent-encoded parameter value. The client MUST NOT included in the query component of the URI (see Section 3.4 of RFC
insert any spaces while constructing the string. The order in which 3986). To construct the query component, the client performs the
the client places each parameter and its corresponding parameter following steps. First, each parameter value is percent-encoded, as
value is unspecified. per Section 2.1 of RFC 3986, so that it conforms to the query
production in Section 3.4 of that specification, and additionally any
instances of the "=" and "&" characters are also percent-encoded.
Next, the client constructs a string to be placed in the query
component by concatenating the name of the first parameter together
with an equal sign ("=") and the percent-encoded parameter value.
For any subsequent parameters, the client appends an ampersand ("&")
to the string, the name of the next parameter, an equal sign, and the
parameter value. The client MUST NOT insert any spaces while
constructing the string. The order in which the client places each
attribute-and-value pair within the query component is unspecified.
4.2. Performing a WebFinger Query 4.2. Performing a WebFinger Query
A WebFinger client issues a query to the well-known [3] resource A WebFinger client issues a query to the well-known [3] resource
/.well-known/webfinger. A query MUST include the "resource" identified by the URI whose path component begins with "/.well-
parameter exactly once and set to the value of the URI for which known/webfinger" and whose query component MUST include the
information is being sought. If the "resource" parameter is absent "resource" parameter exactly once and set to the value of the URI for
or malformed, the WebFinger server MUST indicate that the request is which information is being sought. If the "resource" parameter is
bad as per Section 10.4.1 of RFC 2616 [2]. absent or malformed, the WebFinger resource MUST indicate that the
request is bad as per Section 10.4.1 of RFC 2616 [2].
A client MUST query the WebFinger server using HTTPS only. If the A client MUST query the WebFinger resource using HTTPS only. If the
client determines that the server has an invalid certificate, the client determines that the resource has an invalid certificate, the
server returns a 4xx or 5xx status code, or the HTTPS connection resource returns a 4xx or 5xx status code, or the HTTPS connection
cannot be established for any reason, the client MUST accept that the cannot be established for any reason, then the client MUST accept
WebFinger query has failed and MUST NOT attempt to reissue the that the WebFinger query has failed and MUST NOT attempt to reissue
WebFinger request using HTTP over a non-secure connection. the WebFinger request using HTTP over a non-secure connection.
A WebFinger server 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, though no other header to indicate a desired representation, though no other
representation than JRD is defined in this specification. The media representation than JRD is defined in this specification. The media
type used for the JSON Resource Descriptor (JRD) is type used for the JSON Resource Descriptor (JRD) is
"application/json" [5]. "application/jrd+json" (see Section 9.2).
A WebFinger server MAY redirect the client, but MUST only redirect A WebFinger resource MAY redirect the client, but MUST only redirect
the client to an HTTPS URI. the client to an HTTPS URI.
A WebFinger server 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
When issuing a request to the server, the client MAY utilize the When issuing a request to a WebFinger resource, the client MAY
"rel" parameter to request only a subset of the information that utilize the "rel" parameter to request only a subset of the
would otherwise be returned without the "rel" parameter. When the information that would otherwise be returned without the "rel"
"rel" parameter is used, only the link relations that match the link parameter. When the "rel" parameter is used, only the link relations
relations provided via "rel" are included in the array of links that match the link relations provided via the "rel" parameter are
returned in the JRD. All other information normally present in a included in the array of links returned in the JRD. All other
resource descriptor is present in the resource descriptor, even when information present in a resource descriptor remains present, even
"rel" is employed. when "rel" is employed.
The "rel" parameter MAY be transmitted to the server multiple times The "rel" parameter MAY be transmitted to the WebFinger resource
in order to request multiple types of link relations. multiple times 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 "link
resource's link relations. Use of the parameter might reduce relation objects" (see Section 4.4.4) that would otherwise be
processing requirements on either the client or server, and it might returned in the resource descriptor. Use of the parameter might
also reduce the bandwidth required to convey the partial resource reduce processing requirements on either the client or server, and it
descriptor, especially if there are numerous link relation values to might also reduce the bandwidth required to convey the partial
convey for a given resource. resource descriptor, especially if there are numerous link relation
values to convey for a given "resource" value.
Support for the "rel" parameter is OPTIONAL, but RECOMMENDED on the WebFinger resources SHOULD support the "rel" parameter. If the
server. Should the server not support the "rel" parameter, it MUST resource does not support the "rel" parameter, it MUST ignore the
ignore it 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 in order to select two link 3.1, but uses the "rel" parameter 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.example%2Frel%2Fprofile-page&
rel=vcard HTTP/1.1 rel=http://webfinger.example/rel/businesscard HTTP/1.1
Host: example.com Host: example.com
In this example, the client requests the link relations of type In this example, the client requests the link relations of type
"http://webfinger.net/rel/profile-page" and "vcard". The server then "http://webfinger.example/rel/profile-page" and
"http://webfinger.example/rel/businesscard". The server then
responds with a message like this: responds with a message like this:
HTTP/1.1 200 OK HTTP/1.1 200 OK
Access-Control-Allow-Origin: * Access-Control-Allow-Origin: *
Content-Type: application/json; charset=UTF-8 Content-Type: application/jrd+json
{ {
"expires" : "2012-11-16T19:41:35Z",
"subject" : "acct:bob@example.com", "subject" : "acct:bob@example.com",
"aliases" : "aliases" :
[ [
"http://www.example.com/~bob/" "http://www.example.com/~bob/"
], ],
"properties" : "properties" :
{ {
"http://example.com/ns/role/" : "employee" "http://example.com/ns/role/" : "employee"
}, },
"links" : "links" :
[ [
{ {
"rel" : "http://webfinger.net/rel/profile-page", "rel" : "http://webfinger.example/rel/profile-page",
"href" : "http://www.example.com/~bob/" "href" : "http://www.example.com/~bob/"
}, },
{ {
"rel" : "vcard", "rel" : "http://webfinger.example/rel/businesscard",
"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 in the response, the resource representation contains
by the client, but also included the other parts of the JRD. only the link relations requested by the client, but the other parts
of the JRD are still present.
In the event that a client requests links for link relations that are In the event that a client requests link relation types that are not
not defined for the specified resource, a resource descriptor MUST be 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.
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 [19] and based on the Extensible Resource Descriptor (XRD) format
[20], is a JSON object that is comprised of the following name/value [20], is a JSON object that is comprised of the following name/value
pairs: pairs:
o expires
o subject o subject
o aliases o aliases
o properties o properties
o links o links
The members "expires" and "subject" are name/value pairs whose value The member "subject" is a name/value pair whose value is a string,
are strings, "aliases" is an array of strings, "properties" is an "aliases" is an array of strings, "properties" is an object comprised
object comprised of name/value pairs whose values are strings, and of name/value pairs whose values are strings, and "links" is an array
"links" is an array of objects that contain link relation of objects that contain link relation information.
information.
When processing a JRD, the client MUST ignore any unknown member and When processing a JRD, the client MUST ignore any unknown member and
not treat the presence of an unknown member as an error. not treat the presence of an unknown member as an error.
Below, each of these members of the JRD is described in more detail. Below, each of these members of the JRD is described in more detail.
4.4.1. expires 4.4.1. subject
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.
This format is formally defined in RFC 3339 [15].
The "expires" member MUST NOT use fractional seconds and MUST express
time only Universal Coordinate Time via the "Z" designation on the
end of the string.
An example of the "expires" member is:
"expires" : "2012-11-16T19:41:35Z"
The "expires" member is optional in a JRD, but SHOULD be honored if
present.
4.4.2. subject
The value of the "subject" member is a URI that identifies the entity The value of the "subject" member is a URI that identifies the entity
that the JRD describes. that the JRD describes.
The "subject" value returned by a WebFinger server MAY differ from The "subject" value returned by a WebFinger resource MAY differ from
the value of the "resource" parameter used in the client's request. the value of the "resource" parameter used in the client's request.
This may happen, for example, when the subject's identity changes This might happen, for example, when the subject's identity changes
(e.g., a user moves his or her account to another service) or when (e.g., a user moves his or her account to another service) or when
the server prefers to express URIs in canonical form. the resource prefers to express URIs in canonical form.
The "subject" member MUST be present. The "subject" member MUST be present in the JRD.
4.4.3. aliases 4.4.2. aliases
The "aliases" array is an array of zero or more URI strings that The "aliases" array is an array of zero or more URI strings that
identify the same entity as the "subject" URI. Each URI must be an identify the same entity as the "subject" URI. Each URI must be an
absolute URI. absolute URI.
The "aliases" array is optional. The "aliases" array is OPTIONAL in the JRD.
4.4.4. properties 4.4.3. properties
The "properties" object is comprised of zero or more name/value pairs The "properties" object is comprised of zero or more name/value pairs
whose names are absolute URIs and whose values are strings or null. whose names are absolute URIs and whose values are strings or null.
Properties are used to convey additional information about the Properties are used to convey additional information about the
subject of the JRD. As an example, consider this use of subject of the JRD. As an example, consider this use of
"properties": "properties":
"properties" : { "http://webfinger.net/ns/name" : "Bob Smith" } "properties" : { "http://webfinger.example/ns/name" : "Bob Smith" }
The "properties" member is optional. The "properties" member is OPTIONAL in the JRD.
4.4.5. links 4.4.4. links
The "links" array contains zero or more elements that contain the The "links" array has any number of member objects, each of which
link relation information. Each element of the array is an object represents a link [4]. Each of these link objects can have the
comprised of the following name/value pairs: following members:
o rel o rel
o type o type
o href o href
o titles o titles
o properties o properties
The members "rel", "type", and "href" are a name/value pairs whose The "rel" and "href" members are strings representing the link's
values are strings, "titles" and "properties" are objects comprised relation type and the target IRI, respectively. The context of the
of name/value pairs whose values are strings. link is the "subject" (see Section 4.4.1).
The "type" member is a string indicating what the media type of the
result of dereferencing the link ought to be.
The order of elements in the "links" array indicates an order of The order of elements in the "links" array indicates an order of
preference. Thus, if there are two or more link relations having the preference. Thus, if there are two or more link relations having the
same "rel" value, the first link relation would indicate the user's same "rel" value, the first link relation would indicate the user's
preferred link relation. preferred link.
The "links" array is optional in the JRD. The "links" array is OPTIONAL in the JRD.
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.5.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 [10] (see RFC 5988 [4]). The value
of the "rel" member MUST contain exactly one URI string or registered of the "rel" member MUST contain exactly one URI or registered
relation type and MUST NOT contain a space-separated list of URIs or relation type. The URI or registered relation type identifies the
registered relation types. The URI or registered relation type type of the link relation. The other members of the object have
identifies the type of the link relation. The other members of the meaning only once the type of link relation is understood. In some
object have meaning only once the type of link relation is instances, the link relation will have associated semantics enabling
understood. In some instances, the link relation will have the client to query for other resources on the Internet. In other
associated semantics that allow a client to query for other resources instances, the link relation will have associated semantics enabling
on the Internet. In other instances, the link relation will have the client to utilize the other members of the link relation object
associated semantics that allow the client to utilize the other without fetching additional external resources.
members of the link relation object without fetching additional
external resources.
The "rel" member MUST be present in the link relation object. The "rel" member MUST be present in the link relation object.
4.4.5.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 linked resource (see RFC 4288 [12]). type [11] of the target resource (see RFC 6838 [12]).
The "type" member is optional in the link relation object. The "type" member is OPTIONAL in the link relation object.
4.4.5.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 linked 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.5.4. titles 4.4.4.4. titles
The "titles" object is comprised of zero or more name/value pairs The "titles" object is comprised of zero or more name/value pairs
whose name is a language tag [13] or the string "default". The whose name is a language tag [13] or the string "default". The
string is human-readable and describes the link relation. More than string is human-readable and describes the link relation. More than
one title for the link relation MAY be provided for the benefit of one title for the link relation MAY be provided for the benefit of
users who utilize the link relation and, if used, a language users who utilize the link relation and, if used, a language
identifier SHOULD be duly used as the name. If the language is identifier SHOULD be duly used as the name. If the language is
unknown or unspecified, then the name is "default". unknown or unspecified, then the name is "default".
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 "default") within the link relation object. Meaning language tag (or "default") within the link relation object. Meaning
is undefined if a link relation object includes more than one title is undefined if a link relation object includes more than one title
named with the same language tag (or "default"), though this MUST NOT named with the same language tag (or "default"), though this MUST NOT
treat this as an error. A client MAY select whichever title or be treated as an error. A client MAY select whichever title or
titles it wishes to utilize. titles 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 Bob",
"fr" : "Le monde magique de Bob" "fr" : "Le Monde Magique de Bob"
} }
The "titles" member is optional in the link relation object. The "titles" member is OPTIONAL in the link relation object.
4.4.5.5. properties 4.4.4.5. properties
The "properties" object within the link relation object is comprised The "properties" object within the link relation object is comprised
of zero or more name/value pairs whose names are absolute URIs and of zero or more name/value pairs whose names are absolute URIs and
whose values are strings or null. Properties are used to convey whose values are strings or null. Properties are used to convey
additional information about the link relation. As an example, additional information about the link relation. As an example,
consider this use of "properties": consider this use of "properties":
"properties" : { "http://example.net/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 can include a parameter specifying the URI of an WebFinger requests can include a "resource" parameter (see Section
account, device, or other entity. WebFinger is agnostic regarding 4.1) specifying the URI of an account, device, or other entity.
the scheme of such a URI: it could be an "acct" URI [7], an "http" or WebFinger is neutral regarding the scheme of such a URI: it could be
"https" URI, a "mailto" URI [21], or some other scheme. an "acct" URI [7], an "http" or "https" URI, a "mailto" URI [21], or
some other scheme.
For resources associated with a user account at a host, use of the To perform a WebFinger lookup on an account specific to the host
"acct" URI scheme is RECOMMENDED, since it explicitly identifies an being queried, use of the "acct" URI scheme is RECOMMENDED, since it
account accessible via WebFinger. Further, the "acct" URI scheme is explicitly identifies an account accessible via WebFinger. Further,
not associated with other protocols as, by way of example, the the "acct" URI scheme is not associated with other protocols as, by
"mailto" URI scheme is associated with email. Since not every host way of example, the "mailto" URI scheme is associated with email.
offers email service, using the "mailto" URI scheme is not ideal for Since not every host offers email service, using the "mailto" URI
identifying user accounts on all hosts. That said, use of the scheme is not ideal for identifying user accounts on all hosts. That
"mailto" URI scheme would be ideal for use with WebFinger to discover said, use of the "mailto" URI scheme would be ideal for use with
mail server configuration information for a user. 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) [9], 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
resources: 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 WebFinger server on an intranet that not appropriate, for example a server on an intranet that provides
provides sensitive company information should not allow CORS requests sensitive company information SHOULD NOT allow CORS requests from any
from any domain, as that could allow leaking of that sensitive domain, as that could allow leaking of that sensitive information. A
information. A WebFinger server that wishes to restrict access to server that wishes to restrict access to information from external
information from external entities SHOULD use a more restrictive entities SHOULD use a more restrictive Access-Control-Allow-Origin
Access-Control-Allow-Origin header. header.
6. Access Control 6. Access Control
As with all web resources, access to the /.well-known/webfinger As with all web resources, access to the WebFinger resource MAY
resource MAY require authentication. Further, failure to provide require authentication. Further, failure to provide required
required credentials MAY result in the server forbidding access or credentials MAY result in the server forbidding access or providing a
providing a different response than had the client authenticated with different response than had the client authenticated with the server.
the server.
Likewise, a server MAY provide different responses to different Likewise, a WebFinger resource MAY provide different responses to
clients based on other factors, such as whether the client is inside different clients based on other factors, such as whether the client
or outside a corporate network. As a concrete example, a query is inside or outside a corporate network. As a concrete example, a
performed on the internal corporate network might return link query performed on the internal corporate network might return link
relations to employee pictures, whereas link relations for employee relations to employee pictures, whereas link relations for employee
pictures might not be provided to external entities. pictures might not be provided to external entities.
Further, link relations provided in a WebFinger server response MAY Further, link relations provided in a WebFinger resource
point to web resources that impose access restrictions. For example, representation MAY point to web resources that impose access
the aforementioned corporate server may provide both internal and restrictions. For example, the aforementioned corporate server may
external entities with URIs to employee pictures, but further provide both internal and external entities with URIs to employee
authentication might be required in order for the client to access pictures, but further authentication might be required in order for
the picture resources if the request comes from outside the corporate the client to access the picture resources if the request comes from
network. outside the corporate network.
The decisions made with respect to what set of link relations a The decisions made with respect to what set of link relations a
WebFinger server provides to one client versus another and what WebFinger resource provides to one client versus another and what
resources require further authentication, as well as the specific resources require further authentication, as well as the specific
authentication mechanisms employed, are outside the scope of this authentication mechanisms employed, are outside the scope of this
document. document.
7. Hosted WebFinger Services 7. Hosted WebFinger Services
As with most services provided on the Internet, it is possible for a As with most services provided on the Internet, it is possible for a
domain owner to utilize "hosted" WebFinger services. By way of domain owner to utilize "hosted" WebFinger services. By way of
example, a domain owner might control most aspects of their domain, example, a domain owner might control most aspects of their domain,
but use a third-party hosting service for email. In the case of but use a third-party hosting service for email. In the case of
email, mail servers for a domain are identified by MX records. An MX email, MX records identify mail servers for a domain. An MX record
record points to the mail server to which mail for the domain should points to the mail server to which mail for the domain should be
be delivered. It does not matter to the sending mail server whether delivered. It does not matter to the sending mail server whether
those MX records point to a server in the destination domain or a those MX records point to a server in the destination domain or a
different domain. different domain.
Likewise, a domain owner might utilize the services of a third party Likewise, a domain owner might utilize the services of a third party
to provide WebFinger services on behalf of its users. Just as a to provide WebFinger services on behalf of its users. Just as a
domain owner was required to insert MX records into DNS to allow for domain owner was required to insert MX records into DNS to allow for
hosted email serves, the domain owner is required to redirect HTTP hosted email serves, the domain owner is required to redirect HTTP
queries to its domain to allow for hosted WebFinger services. queries to its domain to allow for hosted WebFinger services.
When a query is issued to /.well-known/webfinger, the web server MUST When a query is issued to the WebFinger resource, the web server MUST
return a response with a redirection status code that includes a return a response with a redirection status code that includes a
Location header pointing to the location of the hosted WebFinger Location header pointing to the location of the hosted WebFinger
service URL. The WebFinger service URL does not need to point to service URI. This WebFinger service URI does not need to point to
/.well-known/* on the hosting service provider server. the well-known WebFinger location on the hosting service provider
server.
As an example, assume that example.com's WebFinger services are As an example, assume that example.com's WebFinger services are
hosted by example.net. Suppose a client issues a query for hosted by wf.example.net. Suppose a client issues a query for
acct:alice@example.com like this: acct:alice@example.com like this:
GET /.well-known/webfinger? GET /.well-known/webfinger?
resource=acct%3Aalice%40example.com HTTP/1.1 resource=acct%3Aalice%40example.com HTTP/1.1
Host: example.com Host: example.com
The server might respond with this: The server might respond with this:
HTTP/1.1 307 Temporary Redirect HTTP/1.1 307 Temporary Redirect
Access-Control-Allow-Origin: * Access-Control-Allow-Origin: *
Location: https://wf.example.net/example.com/webfinger? Location: https://wf.example.net/example.com/webfinger?
resource=acct%3Aalice%40example.com HTTP/1.1 resource=acct%3Aalice%40example.com HTTP/1.1
The client can then follow the redirection, re-issuing the request to The client can then follow the redirection, re-issuing the request to
the URL 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
Since this specification utilizes Cross-Origin Resource Sharing Since this specification utilizes Cross-Origin Resource Sharing
(CORS) [9], all of the security considerations applicable CORS are (CORS) [9], all of the security considerations applicable to CORS are
also applicable to this specification. also applicable to this specification.
The required use of HTTPS is 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
server operating on HTTPS replaced with one operating only over HTTP. resource operating on HTTPS replaced with one operating only over
As such, clients MUST NOT issue queries over a non-secure connection. HTTP. As such, clients MUST NOT issue queries over a non-secure
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 and accept a response only if the certificate is valid. is valid (as defined in [14]) and accept a response only if the
certificate is valid.
Service providers and users should be aware that placing information Service providers and users should be aware that placing information
on the Internet accessible through WebFinger means that any user can on the Internet means that any user can access that information and
access that information. While WebFinger can be an extremely useful WebFinger can be used to make it even easier to discover that
tool for allowing quick and easy access to one's avatar, blog, or information. While WebFinger can be an extremely useful tool for
other personal information, users should understand the risks, too. discovering one's avatar, blog, or other personal information, users
If one does not wish to share certain information with the world, do should understand the risks, too. If one does not wish to share
not allow that information to be freely accessible through WebFinger certain information with the world, do not allow that information to
and do not use any service supporting WebFinger. Further, a be freely accessible on the Internet or discoverable via WebFinger.
WebFinger server MUST NOT be used to provide any personal information Further, WebFinger MUST NOT be used to provide any personal
to any party unless explicitly or implicitly authorized by the person information to any party unless explicitly or implicitly authorized
whose information is being shared. Implicit authorization can be by the person whose information is being shared.
determined by the user's voluntary utilization of a service as
defined by that service's relevant terms of use or published privacy
policy.
The aforementioned word of caution is perhaps worth emphasizing again The aforementioned word of caution is perhaps worth emphasizing again
with respect to dynamic information one might wish to share, such as with respect to information that might reveal a user's current
the current location of a user. WebFinger can be a powerful tool context (e.g., the user's location). The power of WebFinger comes
used to assemble information about a person all in one place, but from providing a single place where others can find pointers to
service providers and users should be mindful of the nature of that information about a person, but service providers and users should be
information shared and the fact that it might be available for the mindful of the nature of that information shared and the fact that it
entire world to see. Sharing location information, for example, might be available for the entire world to see. Sharing location
would potentially put a person in danger from any individual who information, for example, would potentially put a person in danger
might seek to inflict harm on that person. from any individual who might seek to inflict harm on that person.
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 a WebFinger server for information available via WebFinger, such as WebFinger resources for
use inside a corporate network, the network administrator must take use inside a corporate network, the network administrator needs to
measures necessary to limit access from outside the network. Using take necessary measures to limit access from outside the network.
standard methods for securing web resources, network administrators Using standard methods for securing web resources, network
do have the ability to control access to resources that might return administrators do have the ability to control access to resources
sensitive information. Further, a WebFinger server can be employed that might return sensitive information. Further, a server can be
in such a way as to require authentication and prevent disclosure of employed in such a way as to require authentication and prevent
information to unauthorized entities. disclosure of information to unauthorized entities.
Finally, a WebFinger server has no means of ensuring that information Finally, a WebFinger resource has no means of ensuring that
provided by a user is accurate. Likewise, neither the server nor the information provided by a user is accurate. Likewise, neither the
client can be absolutely guaranteed that information has not been resource nor the client can be absolutely guaranteed that information
manipulated either at the server or along the communication path has not been manipulated either at the server or along the
between the client and server. Use of HTTPS helps to address some communication path between the client and server. Use of HTTPS helps
concerns with manipulation of information along the communication to address some concerns with manipulation of information along the
path, but it clearly cannot address issues where the server provided communication path, but it clearly cannot address issues where the
incorrect information, either due to being provided false information resource provided incorrect information, either due to being provided
or due to malicious behavior on the part of the server administrator. false information or due to malicious behavior on the part of the
As with any information service available on the Internet, users server administrator. As with any information service available on
should wary of information received from untrusted sources. the Internet, users should be wary of information received from
untrusted sources.
9. IANA Considerations 9. IANA Considerations
9.1. Well-Known URI
This specification registers the "webfinger" well-known URI in the This specification registers the "webfinger" well-known URI in the
Well-Known URI Registry as defined by [3]. Well-Known URI Registry as defined by [3].
URI suffix: webfinger URI suffix: webfinger
Change controller: IETF Change controller: IETF
Specification document(s): RFC QQQ
Related information: The response from WebFinger server will be a Specification document(s): RFC XXXX
JSON Resource Descriptor (JRD) as described in section 4.4 of RFC
QQQ.
[RFC EDITOR: Please replace "QQQ" references in this section with the Related information: The response representation returned by a
number for this RFC.] WebFinger resource will be a JSON Resource Descriptor (JRD) as
described in Section 4.4 of RFC XXXX.
[RFC EDITOR: Please replace "XXXX" references in this section and the
following section with the number for this RFC.]
9.2. JSON Resource Descriptor (JRD) Media Type
This specification registers the media type application/jrd+json for
use with WebFinger in accordance with media type registration
procedures defined in [12].
Type name: application
Subtype name: jrd+json
Required parameters: N/A
Optional parameters: N/A
In particular, because RFC 4627 already defines the character
encoding for JSON, no "charset" parameter is used.
Encoding considerations: See RFC 6839, section 3.1.
Security considerations:
The JSON Resource Descriptor (JRD) is a JavaScript Object Notation
(JSON) object. It is a text format that must be parsed by entities
that wish to utilize the format. Depending on the language and
mechanism used to parse a JSON object, it is possible for an
attacker to inject behavior into a running program. Therefore,
care must be taken to properly parse a received JRD to ensure that
only a valid JSON object is present and that no JavaScript or other
code is injected or executed unexpectedly.
Interoperability considerations:
This media type is a JavaScript Object Notation (JSON) object and
can be consumed by any software application that can consume JSON
objects.
Published specification: RFC XXXX
Applications that use this media type:
The JSON Resource Descriptor (JRD) is used by the WebFinger
protocol (RFC XXXX) to enable the exchange of information between a
client and a WebFinger resource over HTTPS.
Fragment identifier considerations:
The syntax and semantics of fragment identifiers SHOULD be as
specified for "application/json". (At publication of this
document, there is no fragment identification syntax defined for
"application/json".)
Additional information:
Deprecated alias names for this type: N/A
Magic number(s): N/A
File extension(s): jrd
Macintosh file type code(s): N/A
Person & email address to contact for further information:
Paul E. Jones <paulej@packetizer.com>
Intended usage: COMMON
Restrictions on usage: N/A
Author: Paul E. Jones <paulej@packetizer.com>
Change controller:
IESG has change control over this registration.
Provisional registration? (standards tree only): N/A
10. Acknowledgments 10. Acknowledgments
The authors would like to acknowledge Eran Hammer-Lahav, Blaine Cook, This document has benefited from extensive discussion and review of
Brad Fitzpatrick, Laurent-Walter Goix, Joe Clarke, Michael B. Jones, many of the members of the APPSAWG working group. The authors would
Peter Saint-Andre, Dick Hardt, Tim Bray, and Joe Gregorio for their like to especially acknowledge the invaluable input of Eran Hammer-
invaluable input. Lahav, Blaine Cook, Brad Fitzpatrick, Laurent-Walter Goix, Joe
Clarke, Michael B. Jones, Peter Saint-Andre, Dick Hardt, Tim Bray,
James Snell, Melvin Carvalho, Evan Prodromou, Mark Nottingham, Barry
Leiba, Elf Pavlik, Bjoern Hoehrmann, SM, Joe Gregorio and others that
we have undoubtedly, but inadvertently, missed. Special thanks go to
the chairs of APPSAWG, especially Salvatore Loreto for his assistance
in shepherding this document.
11. References 11. References
11.1. Normative References 11.1. Normative References
[1] Bradner, S., "Key words for use in RFCs to Indicate Requirement [1] Bradner, S., "Key words for use in RFCs to Indicate Requirement
Levels", BCP 14, RFC 2119, March 1997. Levels", BCP 14, RFC 2119, March 1997.
[2] Fielding, R., Gettys, J., Mogul, J., Frystyk, H., Masinter, L., [2] Fielding, R., Gettys, J., Mogul, J., Frystyk, H., Masinter, L.,
Leach, P., and T. Berners-Lee, "Hypertext Transfer Protocol -- Leach, P., and T. Berners-Lee, "Hypertext Transfer Protocol --
skipping to change at page 19, line 11 skipping to change at page 21, line 11
[9] Van Kesteren, A., "Cross-Origin Resource Sharing", W3C CORS [9] Van Kesteren, A., "Cross-Origin Resource Sharing", W3C CORS
http://www.w3.org/TR/cors/, July 2010. http://www.w3.org/TR/cors/, July 2010.
[10] IANA, "Link Relations", http://www.iana.org/assignments/link- [10] IANA, "Link Relations", http://www.iana.org/assignments/link-
relations/. relations/.
[11] IANA, "MIME Media Types", [11] 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., "Media Type Specifications and [12] Freed, N., Klensin, J., Hansen, T., "Media Type Specifications
Registration Procedures", RFC 4288, December 2005. and Registration Procedures", RFC 6838, January 2013.
[13] Phillips, A., Davis, M., "Tags for Identifying Languages", RFC [13] Phillips, A., Davis, M., "Tags for Identifying Languages", RFC
5646, January 2001. 5646, January 2001.
[14] Rescorla, E., "HTTP Over TLS", RFC 2818, May 2000. [14] Rescorla, E., "HTTP Over TLS", RFC 2818, May 2000.
[15] Klyne, G., Newman, C., "Date and Time on the Internet: [15] Klyne, G., Newman, C., "Date and Time on the Internet:
Timestamps", RFC 3339, July 2002. Timestamps", RFC 3339, July 2002.
11.2. Informative References 11.2. Informative References
[16] Perreault, S., "vCard Format Specification", RFC 6350, August [16] Perreault, S., "vCard Format Specification", RFC 6350, August
2011. 2011.
[17] "Transport Independent, Printer/System Interface", IEEE Std [17] "Transport Independent, Printer/System Interface", IEEE Std
1284.1-1997, 1997. 1284.1-1997, 1997.
[18] Sakimura, N., Bradley, J., Jones, M., de Medeiros, B., [18] 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",
2012, http://openid.net/specs/openid-connect-messages-1_0.html. January 2013, http://openid.net/specs/openid-connect-messages-
1_0.html.
[19] Hammer-Lahav, E. and Cook, B., "Web Host Metadata", RFC 6415, [19] 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 [20] 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 [21] Duerst, M., Masinter, L., and J. Zawinski, "The 'mailto' URI
Scheme", RFC 6068, October 2010. Scheme", RFC 6068, October 2010.
 End of changes. 120 change blocks. 
340 lines changed or deleted 439 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/