draft-ietf-appsawg-webfinger-05.txt   draft-ietf-appsawg-webfinger-06.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 28, 2013 Joseph Smarr Expires: May 29, 2013 Joseph Smarr
Google Google
November 28, 2012 November 29, 2012
WebFinger WebFinger
draft-ietf-appsawg-webfinger-05.txt draft-ietf-appsawg-webfinger-06.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 28, 2013. This Internet-Draft will expire on May 29, 2013.
Copyright Notice Copyright Notice
Copyright (c) 2012 IETF Trust and the persons identified as the Copyright (c) 2012 IETF Trust and the persons identified as the
document authors. All rights reserved. document authors. All rights reserved.
This document is subject to BCP 78 and the IETF Trust's Legal This document is subject to BCP 78 and the IETF Trust's Legal
Provisions Relating to IETF Documents Provisions Relating to IETF Documents
(http://trustee.ietf.org/license-info) in effect on the date of (http://trustee.ietf.org/license-info) in effect on the date of
publication of this document. Please review these documents publication of this document. Please review these documents
skipping to change at page 2, line 22 skipping to change at page 2, line 22
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) Document...............9
5.3. The "rel" Parameter.......................................9 5.3. The "rel" Parameter.......................................9
5.4. WebFinger and URIs.......................................11 5.4. WebFinger and URIs.......................................11
6. Cross-Origin Resource Sharing (CORS)..........................12 6. Cross-Origin Resource Sharing (CORS)..........................12
7. Access Control................................................12 7. Access Control................................................12
8. Hosted WebFinger Services.....................................12 8. Hosted WebFinger Services.....................................13
9. Security Considerations.......................................13 9. Security Considerations.......................................13
10. IANA Considerations..........................................14 10. IANA Considerations..........................................15
11. Acknowledgments..............................................15 11. Acknowledgments..............................................15
12. References...................................................15 12. References...................................................15
12.1. Normative References....................................15 12.1. Normative References....................................15
12.2. Informative References..................................16 12.2. Informative References..................................16
Author's Addresses...............................................17 Author's Addresses...............................................17
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
skipping to change at page 6, line 10 skipping to change at page 6, line 10
[ [
{ {
"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 filters the link relations returned by
the server, other elements of the response, including any aliases or the server, other name/value pairs in the response, including any
properties, would be returned. Also, since support for the "rel" aliases or properties, would be returned. Also, since support for
parameter is optional, the client must not assume the "links" array the "rel" parameter is optional, the client must not assume the
will contain only the requested link relation. "links" array will contain only the requested link relation.
4.3. Auto-Configuration of Email Clients 4.3. Auto-Configuration of Email Clients
WebFinger could be used to auto-provision an email client with basic WebFinger could be used to auto-provision an email client with basic
configuration data. Suppose that sue@example.com wants to configure configuration data. Suppose that sue@example.com wants to configure
her email client. Her email client might issue the following query: her email client. Her email client might issue the following query:
GET /.well-known/webfinger? GET /.well-known/webfinger?
resource=mailto%3Asue%40example.com HTTP/1.1 resource=mailto%3Asue%40example.com HTTP/1.1
Host: example.com Host: example.com
skipping to change at page 9, line 8 skipping to change at page 9, line 8
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) Document
The JSON Resource Descriptor (JRD) document is formally described in The JSON Resource Descriptor (JRD) document is formally described in
Appendix A of [11]. There is a RECOMMENDED order of JRD elements. Appendix A of [11]. There is a RECOMMENDED order of JRD name/value
Further, WebFinger requires some elements and some are optional. The pairs. Further, WebFinger requires some name/value pairs and some
following list indicates the preferred order and comments on the are optional. The following list indicates the preferred order and
presence or absence of elements: comments on the presence or absence of name/value pairs:
o "expires" (element) is optional o "expires" (name/value pair) is optional
o "subject" (element) is required and MUST be the value of the o "subject" (name/value pair) is required and MUST be the value
"resource" parameter of the "resource" parameter
o "aliases" (array) is optional and absence or an empty array o "aliases" (array) is optional and absence or an empty array
are semantically the same are semantically the same
o "properties" (array) is optional and absence or an empty o "properties" (object) is optional and absence or an empty
array are semantically the same object are semantically the same
o "links" (array) is optional and absence or an empty array are o "links" (array) is optional and absence or an empty array are
semantically the same semantically the same
Array elements within the "links" array are presented by the server Values within the "links" array are presented by the server in order
in order of preference. of preference.
The "links" array is comprised of several elements. As above, the The "links" array is comprised of several name/value pairs. As
following list indicates the preferred order or elements within a above, the following list indicates the preferred order within a
"links" array element and comments on the presence or absence of "links" array and comments on the presence or absence of name/value
elements within the array: pairs within the array:
o "rel" (element) is required o "rel" (name/value pair) is required
o "type" (element) is optional o "type" (name/value pair) is optional
o "href" (element) is optional o "href" (name/value pair) is optional
o "template" (element) is forbidden o "template" (name/value pair) is forbidden
o "titles" (array) is optional and absence or an empty array o "titles" (object) is optional and absence or an empty object
are semantically the same are semantically the same
o "properties" (array) is optional and absence or an empty o "properties" (object) is optional and absence or an empty
array are semantically the same object are semantically the same
Clients MUST ignore any unknown or forbidden elements received in the Clients MUST ignore any unknown or forbidden name/value pair received
JRD document. in the JRD document.
5.3. The "rel" Parameter 5.3. The "rel" Parameter
WebFinger defines the "rel" parameter to request only a subset of the WebFinger defines the "rel" parameter to request only a subset of the
information that would otherwise be returned without the "rel" information that would otherwise be returned without the "rel"
parameter. When the "rel" parameter is used, only the link relations parameter. When the "rel" parameter is used, only the link relations
that match the link relations provided via "rel" are included in the that match the link relations provided via "rel" are included in the
array of links returned in the JSON Resource Descriptor document. array of links returned in the JSON Resource Descriptor document.
All other information normally present in a resource descriptor is All other information normally present in a resource descriptor is
present in the resource descriptor, even when "rel" is employed. present in the resource descriptor, even when "rel" is employed.
skipping to change at page 11, line 48 skipping to change at page 11, line 48
"mailto" URI scheme is associated with email. Since not every host "mailto" URI scheme is associated with email. Since not every host
offers email service, using the "mailto" URI scheme [9] is not ideal offers email service, using the "mailto" URI scheme [9] is not ideal
for identifying user accounts on all hosts. That said, use of the for identifying user accounts on all hosts. That said, use of the
"mailto" URI scheme would be ideal for use with WebFinger to discover "mailto" URI scheme would be ideal for use with WebFinger to discover
mail server configuration information for a user. mail server configuration information for a user.
A host MAY utilize one or more URIs that serve as aliases for the A host MAY utilize one or more URIs that serve as aliases for the
user's account, such as URIs that use the "http" URI scheme [2]. A user's account, such as URIs that use the "http" URI scheme [2]. A
WebFinger server MUST return substantially the same response to both WebFinger server MUST return substantially the same response to both
an "acct" URI and any alias URI for the account, including the same an "acct" URI and any alias URI for the account, including the same
set of link relations and properties. The only elements in the set of link relations and properties. The only name/value pairs in
response that MAY be different include "subject", "expires", and the response that MAY be different include "subject", "expires", and
"aliases". In addition, the server SHOULD include the entire list "aliases". In addition, the server SHOULD include the entire list
aliases for the user's account in the JRD returned when querying the aliases for the user's account in the JRD returned when querying the
LRDD resource or when utilizing the "resource" parameter. LRDD resource or when utilizing the "resource" parameter.
6. Cross-Origin Resource Sharing (CORS) 6. Cross-Origin Resource Sharing (CORS)
WebFinger might not be useable by code running in web browsers due to WebFinger resources might not be accessible from a web browser due to
"Same-Origin" policies. Therefore, WebFinger servers MUST support "Same-Origin" policies. The current best practice is to make
Cross-Origin Resource Sharing (CORS) [10] and SHOULD do so by resources available to browsers through Cross-Origin Resource Sharing
including the following HTTP header in responses: (CORS) [10], and servers MUST include the Access-Control-Allow-Origin
HTTP header in responses. Servers SHOULD support the least
restrictive setting by allowing any domain access to the WebFinger
resources:
Access-Control-Allow-Origin: * Access-Control-Allow-Origin: *
Enterprise WebFinger servers that wish to restrict access to There are cases where defaulting to the least restrictive setting is
information from external entities MAY use a more restrictive Access- not appropriate, for example a WebFinger server on an intranet that
Control-Allow-Origin header. provides sensitive company information should not allow CORS requests
from any domain, as that could allow leaking of that sensitive
information. WebFinger servers that wish to restrict access to
information from external entities SHOULD use a more restrictive
Access-Control-Allow-Origin header.
7. Access Control 7. Access Control
As with all web resources, access to the /.well-known/webfinger As with all web resources, access to the /.well-known/webfinger
resource MAY require authentication. Further, failure to provide resource MAY require authentication. Further, failure to provide
required credentials MAY result in the server forbidding access or required credentials MAY result in the server forbidding access or
providing a different response than had the client authenticated with providing a different response than had the client authenticated with
the server. the server.
Likewise, a server MAY provide different responses to different Likewise, a server MAY provide different responses to different
skipping to change at page 13, line 41 skipping to change at page 13, line 49
HTTP/1.1 307 Temporary Redirect HTTP/1.1 307 Temporary Redirect
Location: http://wf.example.net/example.com/webfinger? Location: http://wf.example.net/example.com/webfinger?
resource=acct%3Aalice%40example.com HTTP/1.1 resource=acct%3Aalice%40example.com HTTP/1.1
The client MUST follow the redirection, re-issuing the request to the The client MUST follow the redirection, re-issuing the request to the
URL provided in the Location header. URL provided in the Location header.
9. Security Considerations 9. Security Considerations
All of the security considerations applicable to Web Host Metadata Since this specification utilizes Cross-Origin Resource Sharing
[11] and Cross-Origin Resource Sharing [10] are also applicable to (CORS) [10], all of the security considerations applicable CORS are
this specification. Of particular importance is the recommended use also applicable to this specification.
of HTTPS to ensure that information is not modified during transit.
Clients MUST verify that the certificate used on an HTTPS connection The recommended use of HTTPS is to ensure that information is not
is valid. modified during transit. It should be appreciated that in
environments where an HTTPS server is normally available, there
exists the possibility that a compromised network might have its
WebFinger server operating on HTTPS replaced with one operating only
over HTTP. As such, clients that need to ensure data is not
compromised SHOULD NOT issue queries over a non-secure connection.
While Section 5.1 allows for clients that fail to establish an HTTPS
connection to attempt a query using HTTP, a client and any underlying
client libraries are not required to re-issue queries using HTTP and
SHOULD NOT when security for a given application that uses WebFinger
is paramount.
When using HTTPS, clients MUST verify that the certificate used on an
HTTPS connection 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 accessible through WebFinger means that any user can
access that information. While WebFinger can be an extremely useful access that information. While WebFinger can be an extremely useful
tool for allowing quick and easy access to one's avatar, blog, or tool for allowing quick and easy access to one's avatar, blog, or
other personal information, users should understand the risks, too. other personal information, users should understand the risks, too.
If one does not wish to share certain information with the world, do If one does not wish to share certain information with the world, do
not allow that information to be freely accessible through WebFinger not allow that information to be freely accessible through WebFinger
and do not use any service supporting WebFinger. Further, WebFinger and do not use any service supporting WebFinger. Further, WebFinger
servers MUST NOT be used to provide any personal information to any servers MUST NOT be used to provide any personal information to any
party unless explicitly or implicitly authorized by the person whose party unless explicitly or implicitly authorized by the person whose
information is being shared. Implicit authorization can be determined information is being shared. Implicit authorization can be determined
by the user's voluntary utilization of a service as defined by that by the user's voluntary utilization of a service as defined by that
service's relevant terms of use or published privacy policy. 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
skipping to change at page 15, line 19 skipping to change at page 15, line 41
obtained via the WebFinger web service are described in RFC 6415 obtained via the WebFinger web service are described in RFC 6415
Appendix A and RFC QQQ. Appendix A and RFC QQQ.
[RFC EDITOR: Please replace "QQQ" references in this section with the [RFC EDITOR: Please replace "QQQ" references in this section with the
number for this RFC.] number for this RFC.]
11. Acknowledgments 11. Acknowledgments
The authors would like to acknowledge Eran Hammer-Lahav, Blaine Cook, The authors would like to acknowledge Eran Hammer-Lahav, Blaine Cook,
Brad Fitzpatrick, Laurent-Walter Goix, Joe Clarke, Michael B. Jones, Brad Fitzpatrick, Laurent-Walter Goix, Joe Clarke, Michael B. Jones,
and Peter Saint-Andre for their invaluable input. Peter Saint-Andre, Dick Hardt, Tim Bray, and Joe Gregorio for their
invaluable input.
12. References 12. References
12.1. Normative References 12.1. Normative References
[1] Bradner, S., "Key words for use in RFCs to Indicate Requirement [1] Bradner, S., "Key words for use in RFCs to Indicate Requirement
Levels", BCP 14, RFC 2119, March 1997. Levels", BCP 14, RFC 2119, March 1997.
[2] Fielding, R., Gettys, J., Mogul, J., Frystyk, H., [2] Fielding, R., Gettys, J., Mogul, J., Frystyk, H.,
Masinter, L., Leach, P., and T. Berners-Lee, "Hypertext Masinter, L., Leach, P., and T. Berners-Lee, "Hypertext
 End of changes. 21 change blocks. 
51 lines changed or deleted 71 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/