draft-ietf-appsawg-webfinger-15.txt   draft-ietf-appsawg-webfinger-16.txt 
Network Working Group Paul E. Jones Network Working Group Paul E. Jones
Internet Draft Gonzalo Salgueiro Internet Draft Gonzalo Salgueiro
Intended status: Standards Track Cisco Systems Intended status: Standards Track Cisco Systems
Expires: January 4, 2014 Joseph Smarr Expires: January 15, 2014 Joseph Smarr
Google Google
July 4, 2013 July 15, 2013
WebFinger WebFinger
draft-ietf-appsawg-webfinger-15.txt draft-ietf-appsawg-webfinger-16.txt
Abstract Abstract
This specification defines the WebFinger protocol, which can be used This specification defines the WebFinger protocol, which can be used
to discover information about people or other entities on the to discover information about people or other entities on the
Internet using standard HTTP methods. WebFinger discovers Internet using standard HTTP methods. WebFinger discovers
information for a URI that might not be usable as a locator information for a URI that might not be usable as a locator
otherwise, such as account or email URIs. otherwise, such as account or email URIs.
Status of this Memo Status of this Memo
skipping to change at page 1, line 36 skipping to change at page 1, line 36
Internet-Drafts are working documents of the Internet Engineering Internet-Drafts are working documents of the Internet Engineering
Task Force (IETF). Note that other groups may also distribute Task Force (IETF). Note that other groups may also distribute
working documents as Internet-Drafts. The list of current Internet- working documents as Internet-Drafts. The list of current Internet-
Drafts is at http://datatracker.ietf.org/drafts/current/. Drafts is at http://datatracker.ietf.org/drafts/current/.
Internet-Drafts are draft documents valid for a maximum of six months Internet-Drafts are draft documents valid for a maximum of six months
and may be updated, replaced, or obsoleted by other documents at any and may be updated, replaced, or obsoleted by other documents at any
time. It is inappropriate to use Internet-Drafts as reference time. It is inappropriate to use Internet-Drafts as reference
material or to cite them other than as "work in progress." material or to cite them other than as "work in progress."
This Internet-Draft will expire on January 4, 2014. This Internet-Draft will expire on January 15, 2014.
Copyright Notice Copyright Notice
Copyright (c) 2013 IETF Trust and the persons identified as the Copyright (c) 2013 IETF Trust and the persons identified as the
document authors. All rights reserved. document authors. All rights reserved.
This document is subject to BCP 78 and the IETF Trust's Legal This document is subject to BCP 78 and the IETF Trust's Legal
Provisions Relating to IETF Documents Provisions Relating to IETF Documents
(http://trustee.ietf.org/license-info) in effect on the date of (http://trustee.ietf.org/license-info) in effect on the date of
publication of this document. Please review these documents publication of this document. Please review these documents
skipping to change at page 2, line 17 skipping to change at page 2, line 17
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. Identity Provider Discovery for OpenID Connect............3 3.1. Identity Provider Discovery for OpenID Connect............3
3.2. Getting Author and Copyright Information for a Web Page...4 3.2. Getting Author and Copyright Information for a Web Page...4
4. WebFinger Protocol.............................................5 4. WebFinger Protocol.............................................5
4.1. Constructing the Query Component of the Request URI.......6 4.1. Constructing the Query Component of the Request URI.......6
4.2. Performing a WebFinger Query..............................7 4.2. Performing a WebFinger Query..............................7
4.3. The "rel" Parameter.......................................8 4.3. The "rel" Parameter.......................................8
4.4. The JSON Resource Descriptor (JRD)........................9 4.4. The JSON Resource Descriptor (JRD)........................9
4.4.1. subject..............................................9 4.4.1. subject.............................................10
4.4.2. aliases.............................................10 4.4.2. aliases.............................................10
4.4.3. properties..........................................10 4.4.3. properties..........................................10
4.4.4. links...............................................10 4.4.4. links...............................................10
4.5. WebFinger and URIs.......................................12 4.5. WebFinger and URIs.......................................12
5. Cross-Origin Resource Sharing (CORS)..........................12 5. Cross-Origin Resource Sharing (CORS)..........................12
6. Access Control................................................13 6. Access Control................................................13
7. Hosted WebFinger Services.....................................13 7. Hosted WebFinger Services.....................................13
8. Security Considerations.......................................14 8. Security Considerations.......................................14
8.1. Transport-Related Issues.................................14 8.1. Transport-Related Issues.................................14
8.2. User Privacy Considerations..............................15 8.2. User Privacy Considerations..............................15
8.3. Abuse Potential..........................................16 8.3. Abuse Potential..........................................16
8.4. Information Reliability..................................16 8.4. Information Reliability..................................17
9. IANA Considerations...........................................17 9. IANA Considerations...........................................17
9.1. Well-Known URI...........................................17 9.1. Well-Known URI...........................................17
9.2. JSON Resource Descriptor (JRD) Media Type................17 9.2. JSON Resource Descriptor (JRD) Media Type................17
10. Acknowledgments..............................................19 10. Acknowledgments..............................................19
11. References...................................................19 11. References...................................................19
11.1. Normative References....................................19 11.1. Normative References....................................19
11.2. Informative References..................................20 11.2. Informative References..................................20
Author's Addresses...............................................21 Author's Addresses...............................................21
1. Introduction 1. Introduction
skipping to change at page 3, line 7 skipping to change at page 3, line 7
For a person, the kinds of information that might be discoverable via For a person, the kinds of information that might be discoverable via
WebFinger include a personal profile address, identity service, WebFinger include a personal profile address, identity service,
telephone number, or preferred avatar. For other entities on the telephone number, or preferred avatar. For other entities on the
Internet, a WebFinger resource might return JRDs containing link Internet, a WebFinger resource might return JRDs containing link
relations [9] that enable a client to discover, for example, the that relations [9] that enable a client to discover, for example, the that
a printer can print in color on A4 paper, the physical location of a a printer can print in color on A4 paper, the physical location of a
server, or other static information. server, or other static information.
Information returned via WebFinger might be for direct human Information returned via WebFinger might be for direct human
consumption (e.g., looking up someone's phone number), or it might be consumption (e.g., looking up someone's phone number), or it might be
used by systems to help carry out some operation (e.g., facilitate used by systems to help carry out some operation (e.g., facilitate,
logging into a web site by determining a user's identity service). with additional security mechanisms, logging into a web site by
The information is intended to be static in nature and, as such, determining a user's identity service). The information is intended
WebFinger is not intended to be used to return dynamic information to be static in nature and, as such, WebFinger is not intended to be
like the temperature of a CPU or the current toner level in a laser used to return dynamic information like the temperature of a CPU or
printer. the current toner level in a laser printer.
The WebFinger protocol is designed to be used across many The WebFinger protocol is designed to be used across many
applications. Applications that wish to utilize WebFinger will need applications. Applications that wish to utilize WebFinger will need
to specify properties, titles, and link relation types that are to specify properties, titles, and link relation types that are
appropriate for the application. Further, applications will need to appropriate for the application. Further, applications will need to
define the appropriate URI scheme to utilize for the query target. define the appropriate URI scheme to utilize for the query target.
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.
skipping to change at page 7, line 18 skipping to change at page 7, line 18
constructing the string. The order in which the client places each constructing the string. The order in which the client places each
attribute-and-value pair within the query component does not matter attribute-and-value pair within the query component does not matter
in the interpretation of the query component. in the interpretation of the query component.
4.2. Performing a WebFinger Query 4.2. Performing a WebFinger Query
A WebFinger client issues a query using the GET method to the well- A WebFinger client issues a query using the GET method to the well-
known [3] resource identified by the URI whose path component is known [3] resource identified by the URI whose path component is
"/.well-known/webfinger" and whose query component MUST include the "/.well-known/webfinger" and whose query component MUST include the
"resource" parameter exactly once and set to the value of the URI for "resource" parameter exactly once and set to the value of the URI for
which information is being sought. If the "resource" parameter is which information is being sought.
absent or malformed, the WebFinger resource MUST indicate that the
request is bad as per Section 10.4.1 of RFC 2616 [2]. If the "resource" parameter is absent or malformed, the WebFinger
resource MUST indicate that the request is bad as per Section 10.4.1
of RFC 2616 [2].
If the "resource" parameter is a value for which the server has no
information, the server MUST indicate that it was unable to match the
request as per Section 10.4.5 of RFC 2616.
A client MUST query the WebFinger resource using HTTPS only. If the A client MUST query the WebFinger resource using HTTPS only. If the
client determines that the resource has an invalid certificate, the client determines that the resource has an invalid certificate, the
resource 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, then the client MUST accept cannot be established for any reason, then the client MUST accept
that the WebFinger query has failed and MUST NOT attempt to reissue that the WebFinger query has failed and MUST NOT attempt to reissue
the WebFinger request using HTTP over a non-secure connection. the WebFinger request using HTTP over a non-secure connection.
A WebFinger resource MUST return a JRD as the representation for the A WebFinger resource MUST return a JRD as the representation for the
resource if the client requests no other supported format explicitly resource if the client requests no other supported format explicitly
skipping to change at page 7, line 44 skipping to change at page 7, line 50
resource MUST silently ignore any requested representations that it resource MUST silently ignore any requested representations that it
does not understand and support. The media type used for the JSON does not understand and support. The media type used for the JSON
Resource Descriptor (JRD) is "application/jrd+json" (see Section Resource Descriptor (JRD) is "application/jrd+json" (see Section
9.2). 9.2).
The properties, titles, and link relation types returned by the The properties, titles, and link relation types returned by the
server in a JRD might be varied and numerous. For example, the server in a JRD might be varied and numerous. For example, the
server might return information about a person's blog, vCard [14], server might return information about a person's blog, vCard [14],
avatar, OpenID Connect provider, RSS or ATOM feed, and so forth in a avatar, OpenID Connect provider, RSS or ATOM feed, and so forth in a
reply. Likewise, if a server has no information to provide it might reply. Likewise, if a server has no information to provide it might
return a JRD with an empty links array or no links array. return a JRD with an empty links array or no links array.
A WebFinger resource MAY redirect the client; if it does, the A WebFinger resource MAY redirect the client; if it does, the
redirection MUST only be to an "https" URI and the client MUST redirection MUST only be to an "https" URI and the client MUST
perform certificate validation again when redirected. perform certificate validation again when redirected.
A WebFinger resource can include cache validators in a response to A WebFinger resource can include cache validators in a response to
enable conditional requests by the client and/or expiration times as enable conditional requests by the client and/or expiration times as
per Section 13 of RFC 2616. per Section 13 of RFC 2616.
4.3. The "rel" Parameter 4.3. The "rel" Parameter
skipping to change at page 8, line 37 skipping to change at page 8, line 41
values to convey for a given "resource" value. Note that if a client values to convey for a given "resource" value. Note that if a client
requests a particular link relation type for which the server has no requests a particular link relation type for which the server has no
information, the server MAY return a JRD with an empty links array or information, the server MAY return a JRD with an empty links array or
no links array. no links array.
WebFinger resources SHOULD support the "rel" parameter. If the WebFinger resources SHOULD support the "rel" parameter. If the
resource does not support the "rel" parameter, it MUST ignore the resource does not support the "rel" parameter, it MUST ignore the
parameter and process the request as if no "rel" parameter values parameter and process the request as if no "rel" parameter values
were present. were present.
The following example presents the same example as found in Section The following example uses the "rel" parameter to request links for
3.1, but uses the "rel" parameter to select two link relations: two link relation types:
GET /.well-known/webfinger? GET /.well-known/webfinger?
resource=acct%3Abob%40example.com& resource=acct%3Abob%40example.com&
rel=http%3A%2F%2Fwebfinger.example%2Frel%2Fprofile-page& rel=http%3A%2F%2Fwebfinger.example%2Frel%2Fprofile-page&
rel=http://webfinger.example/rel/businesscard 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.example/rel/profile-page" and "http://webfinger.example/rel/profile-page" and
"http://webfinger.example/rel/businesscard". The server then "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/jrd+json Content-Type: application/jrd+json
{ {
"subject" : "acct:bob@example.com", "subject" : "acct:bob@example.com",
"aliases" : "aliases" :
[ [
"http://www.example.com/~bob/" "https://www.example.com/~bob/"
], ],
"properties" : "properties" :
{ {
"http://example.com/ns/role/" : "employee" "http://example.com/ns/role/" : "employee"
}, },
"links" : "links" :
[ [
{ {
"rel" : "http://webfinger.example/rel/profile-page", "rel" : "http://webfinger.example/rel/profile-page",
"href" : "http://www.example.com/~bob/" "href" : "https://www.example.com/~bob/"
}, },
{ {
"rel" : "http://webfinger.example/rel/businesscard", "rel" : "http://webfinger.example/rel/businesscard",
"href" : "http://www.example.com/~bob/bob.vcf" "href" : "https://www.example.com/~bob/bob.vcf"
} }
] ]
} }
As you can see in the response, the resource representation contains As you can see in the response, the resource representation contains
only the link relations requested by the client, but the other parts only the links of the types requested by the client and for which the
of the JRD are still present. server had information, but the other parts of the JRD are still
present. Note also in the above example that the links returned in
the links array all use HTTPS, which is important if the data
indirectly obtained via WebFinger needs to returned securely.
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
[16] and based on the Extensible Resource Descriptor (XRD) format [16] and based on the Extensible Resource Descriptor (XRD) format
[17], is a JSON object that comprises the following name/value pairs: [17], is a JSON object that comprises the following name/value pairs:
o subject o subject
o aliases o aliases
o properties o properties
skipping to change at page 16, line 41 skipping to change at page 16, line 48
botnets or other distributed systems. The reason these mitigation botnets or other distributed systems. The reason these mitigation
strategies are not mandatory is that the correct choice of mitigation strategies are not mandatory is that the correct choice of mitigation
strategy (if any) depends greatly on the context. Implementers strategy (if any) depends greatly on the context. Implementers
should not construe this as meaning that they do not need to consider should not construe this as meaning that they do not need to consider
whether to use a mitigation strategy, and, if so, what strategy to whether to use a mitigation strategy, and, if so, what strategy to
use. use.
WebFinger client developers should also be aware of potential abuse WebFinger client developers should also be aware of potential abuse
by spammers or those phishing for information about users. As an by spammers or those phishing for information about users. As an
example, suppose a mail client was configured to automatically example, suppose a mail client was configured to automatically
perform a WebFinger query as discussed in the example in Section 3.1. perform a WebFinger query on the sender of each received mail
If a spammer sent an email using a unique identifier in the 'From' message. If a spammer sent an email using a unique identifier in the
header, then when the WF query was performed the spammer would be 'From' header, then when the WF query was performed the spammer would
able to associate the request with a particular user's email address. be able to associate the request with a particular user's email
This would provide information to the spammer, including the user's address. This would provide information to the spammer, including
IP address, the fact the user just checked email, what kind of the user's IP address, the fact the user just checked email, what
WebFinger client the user utilized, and so on. For this reason, it kind of WebFinger client the user utilized, and so on. For this
is strongly advised that clients not perform WebFinger queries unless reason, it is strongly advised that clients not perform WebFinger
authorized by the user to do so. queries unless authorized by the user to do so.
8.4. Information Reliability 8.4. Information Reliability
A WebFinger resource has no means of ensuring that information A WebFinger resource has no means of ensuring that information
provided by a user is accurate. Likewise, neither the resource nor provided by a user is accurate. Likewise, neither the resource nor
the client can be absolutely guaranteed that information has not been the client can be absolutely guaranteed that information has not been
manipulated either at the server or along the communication path manipulated either at the server or along the communication path
between the client and server. Use of HTTPS helps to address some between the client and server. Use of HTTPS helps to address some
concerns with manipulation of information along the communication concerns with manipulation of information along the communication
path, but it clearly cannot address issues where the resource path, but it clearly cannot address issues where the resource
skipping to change at page 19, line 17 skipping to change at page 19, line 20
Provisional registration? (standards tree only): N/A Provisional registration? (standards tree only): N/A
10. Acknowledgments 10. Acknowledgments
This document has benefited from extensive discussion and review of This document has benefited from extensive discussion and review of
many of the members of the APPSAWG working group. The authors would many of the members of the APPSAWG working group. The authors would
like to especially acknowledge the invaluable input of Eran Hammer- like to especially acknowledge the invaluable input of Eran Hammer-
Lahav, Blaine Cook, Brad Fitzpatrick, Laurent-Walter Goix, Joe Lahav, Blaine Cook, Brad Fitzpatrick, Laurent-Walter Goix, Joe
Clarke, Michael B. Jones, Peter Saint-Andre, Dick Hardt, Tim Bray, Clarke, Michael B. Jones, Peter Saint-Andre, Dick Hardt, Tim Bray,
James Snell, Melvin Carvalho, Evan Prodromou, Mark Nottingham, Barry James Snell, Melvin Carvalho, Evan Prodromou, Mark Nottingham, Barry
Leiba, Elf Pavlik, Bjoern Hoehrmann, SM, Joe Gregorio and others that Leiba, Elf Pavlik, Bjoern Hoehrmann, Subramanian Moonesamy, Joe
we have undoubtedly, but inadvertently, missed. Special thanks go to Gregorio and others that we have undoubtedly, but inadvertently,
the chairs of APPSAWG, especially Salvatore Loreto for his assistance missed. Special thanks go to the chairs of APPSAWG, especially
in shepherding this document. 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 --
 End of changes. 16 change blocks. 
36 lines changed or deleted 45 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/