Network Working Group Paul E. Jones Internet Draft Gonzalo Salgueiro Intended status: Standards Track Cisco Systems Expires: June 2, 2013 Joseph Smarr Google December 2, 2012 WebFinger draft-ietf-appsawg-webfinger-07.txt Abstract This specification defines the WebFinger protocol, which can be used to discover information about people or other entities on the Internet using standard HTTP methods. Status of this Memo This Internet-Draft is submitted in full conformance with the provisions of BCP 78 and BCP 79. Internet-Drafts are working documents of the Internet Engineering Task Force (IETF). Note that other groups may also distribute working documents as Internet-Drafts. The list of current Internet- Drafts is at http://datatracker.ietf.org/drafts/current/. Internet-Drafts are draft documents valid for a maximum of six months and may be updated, replaced, or obsoleted by other documents at any time. It is inappropriate to use Internet-Drafts as reference material or to cite them other than as "work in progress." This Internet-Draft will expire on June 2, 2013. Copyright Notice Copyright (c) 2012 IETF Trust and the persons identified as the document authors. All rights reserved. This document is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents (http://trustee.ietf.org/license-info) in effect on the date of publication of this document. Please review these documents carefully, as they describe your rights and restrictions with respect to this document. Code Components extracted from this document must include Simplified BSD License text as described in Section 4.e of the Trust Legal Provisions and are provided without warranty as described in the Simplified BSD License. Jones, et al. Expires June 2, 2013 [Page 1] Internet-Draft WebFinger December 2012 Table of Contents 1. Introduction...................................................2 2. Terminology....................................................3 3. Overview.......................................................3 4. Example Use of WebFinger.......................................3 4.1. Locating a User's Blog....................................3 4.2. Identity Provider Discovery for OpenID Connect............5 4.3. Auto-Configuration of Email Clients.......................6 4.4. Retrieving Device Information.............................7 5. WebFinger Protocol.............................................8 5.1. Performing a WebFinger Query..............................8 5.2. The JSON Resource Descriptor (JRD)........................9 5.2.1. expires..............................................9 5.2.2. subject.............................................10 5.2.3. aliases.............................................10 5.2.4. properties..........................................10 5.2.5. links...............................................11 5.3. The "rel" Parameter......................................13 5.4. WebFinger and URIs.......................................14 6. Cross-Origin Resource Sharing (CORS)..........................15 7. Access Control................................................15 8. Hosted WebFinger Services.....................................16 9. Security Considerations.......................................17 10. IANA Considerations..........................................18 11. Acknowledgments..............................................19 12. References...................................................19 12.1. Normative References....................................19 12.2. Informative References..................................20 Author's Addresses...............................................20 1. Introduction WebFinger is used to discover information about people or other entities on the Internet using standard HTTP [2] methods. The WebFinger server returns a JavaScript Object Notation (JSON) [5] object that describes the resource being queried. The JSON object is referred to as the JSON Resource Descriptor (JRD). The JRD contains link relations, properties, titles, and other information that is suitable for automated processing. For a person, the kinds of information that might be shared via WebFinger include a personal profile address, identity service, telephone number, or preferred avatar. For other entities on the Internet, the server might return JRDs containing link relations that allow a client to discover the amount of toner in a printer or the physical location of a server. Information returned via WebFinger might be for direct human consumption (e.g., looking up someone's phone number), or it might be Jones, et al. Expires June 2, 2013 [Page 2] Internet-Draft WebFinger December 2012 used by systems to help carry out some operation (e.g., facilitate logging into a web site by determining a user's identity service). 2. Terminology The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in RFC 2119 [1]. WebFinger makes heavy use of "Link Relations". Briefly, a Link Relation is an attribute and value pair used on the Internet wherein the attribute identifies the type of link to which the associated value refers. In Hypertext Transfer Protocol (HTTP) and Web Linking [4], the attribute is a "rel" and the value is an "href". WebFinger also uses the "rel" attribute, where the "rel" value is either a single IANA-registered link relation type [11] or a URI [6]. 3. Overview WebFinger enables the discovery of information about users, devices, and other entities that are associated with a host. Discovery involves a single HTTP GET request to the well-known [3] "webfinger" resource at the target host and receiving back a JavaScript Object Notation (JSON) [5] Resource Descriptor (JRD) (see section 5.2) containing link relations, properties, titles, and other useful information. The request MUST include the URI or IRI [7] for the entity for which information is sought as a parameter named "resource". Use of WebFinger is illustrated in the examples in Section 4, then described more formally in Section 5. 4. Example Use of WebFinger This non-normative section shows a few sample uses of WebFinger. 4.1. Locating a User's Blog Assume you receive an email from Bob and he refers to something he posted on his blog, but you do not know where Bob's blog is located. It would be simple to discover the address of Bob's blog if he makes that information available via WebFinger. Assume your email client can discover the blog for you. After receiving the message from Bob (bob@example.com), you instruct your email client to perform a WebFinger query. It does so by issuing the following HTTPS query to example.com: Jones, et al. Expires June 2, 2013 [Page 3] Internet-Draft WebFinger December 2012 GET /.well-known/webfinger? resource=acct%3Abob%40example.com HTTP/1.1 Host: example.com The server might then respond with a message like this: HTTP/1.1 200 OK Access-Control-Allow-Origin: * Content-Type: application/json; charset=UTF-8 { "expires" : "2012-11-16T19:41:35Z", "subject" : "acct:bob@example.com", "aliases" : [ "http://www.example.com/~bob/" ], "properties" : { "http://example.com/rel/role/" : "employee" }, "links" : [ { "rel" : "http://webfinger.net/rel/avatar", "type" : "image/jpeg", "href" : "http://www.example.com/~bob/bob.jpg" }, { "rel" : "http://webfinger.net/rel/profile-page", "href" : "http://www.example.com/~bob/" }, { "rel" : "blog", "type" : "text/html", "href" : "http://blogs.example.com/bob/", "titles" : { "en-us" : "The Magical World of Bob", "fr" : "Le monde magique de Bob" } }, { "rel" : "vcard", "href" : "http://www.example.com/~bob/bob.vcf" } ] } Jones, et al. Expires June 2, 2013 [Page 4] Internet-Draft WebFinger December 2012 The email client would take note of the "blog" link relation in the above JRD that refers to Bob's blog. This URL would then be presented to you so that you could then visit his blog. The email client might also note that Bob has published an avatar link relation and use that picture to represent Bob inside the email client. Lastly, the client might consider the vcard [15] link relation in order to update contact information for Bob. In the above example, an "acct" URI [8] is used in the query, though any valid alias for the user might also be used. An alias is a URI that is different from the "subject" URI that identifies the same entity. In the above example, there is one "http" alias returned, though there might have been more than one. Had the "http:" URI shown as an alias been used to query for information about Bob, the query would have appeared as: GET /.well-known/webfinger? resource=http%3A%2F%2Fwww.example.com%2F~bob%2F HTTP/1.1 Host: example.com The response would have been substantially the same, with the subject and alias information changed as necessary. Other information, such as the expiration time might also change, but the set of link relations and properties would be the same with either response. 4.2. Identity Provider Discovery for OpenID Connect Suppose Carol wishes to authenticate with a web site she visits using OpenID Connect [17]. She would provide the web site with her OpenID Connect identifier, say carol@example.com. The visited web site would perform a WebFinger query looking for the OpenID Connect Provider. Since the site is interested in only one particular link relation, the server might utilize the "rel" parameter as described in section 5.3: GET /.well-known/webfinger? resource=acct%3Acarol%40example.com& rel=http%3A%2F%2Fopenid.net%2Fspecs%2Fconnect%2F1.0%2Fissuer HTTP/1.1 Host: example.com The server might respond with a JRD like this: { "expires" : "2012-11-16T19:41:35Z", "subject" : "acct:carol@example.com", "aliases" : [ "http://www.example.com/~carol/" Jones, et al. Expires June 2, 2013 [Page 5] Internet-Draft WebFinger December 2012 ], "properties" : { "http://example.com/rel/role/" : "employee" }, "links" : [ { "rel" : "http://openid.net/specs/connect/1.0/issuer", "href" : "https://openid.example.com/" } ] } Since the "rel" parameter only filters the link relations returned by the server, other name/value pairs in the response, including any aliases or properties, would be returned. Also, since support for the "rel" parameter is optional, the client must not assume the "links" array will contain only the requested link relation. 4.3. Auto-Configuration of Email Clients WebFinger could be used to auto-provision an email client with basic configuration data. Suppose that sue@example.com wants to configure her email client. Her email client might issue the following query: GET /.well-known/webfinger? resource=mailto%3Asue%40example.com HTTP/1.1 Host: example.com The response from the server would contain entries for the various protocols, transport options, and security options. If there are multiple options, the server might return a link relation that for each of the valid options and the client or Sue might select which option to choose. Since JRDs list link relations in a specific order, then the most-preferred choices could be presented first. Consider this response: { "subject" : "mailto:sue@example.com", "links" : [ { "rel" : "http://example.net/rel/smtp-server", "properties" : { "http://example.net/email/host" : "smtp.example.com", "http://example.net/email/port" : "587", "http://example.net/email/login-required" : "yes", Jones, et al. Expires June 2, 2013 [Page 6] Internet-Draft WebFinger December 2012 "http://example.net/email/transport" : "starttls" } }, { "rel" : "http://example.net/rel/imap-server", "properties" : { "http://example.net/email/host" : "imap.example.com", "http://example.net/email/port" : "993", "http://example.net/email/transport" : "ssl" } } ] } In this example, you can see that the WebFinger server advertises an SMTP service and an IMAP service. In this example, the "href" entries associated with the link relation are absent. This is valid when there is no external reference that needs to be made. 4.4. Retrieving Device Information As another example, suppose there are printers on the network and you would like to check the current toner level for a particular printer identified via the URI device:p1.example.com. While the "device" URI scheme is not presently specified, we use it here for illustrative purposes. Following the procedures similar to those above, a query may be issued to get link relations specific to this URI like this: GET /.well-known/webfinger?resource= device%3Ap1.example.com HTTP/1.1 Host: example.com The link relations that are returned for a device may be quite different than those for user accounts. Perhaps we may see a response like this: HTTP/1.1 200 OK Access-Control-Allow-Origin: * Content-Type: application/json; charset=UTF-8 { "subject" : "device:p1.example.com", "links" : [ { "rel" : "http://example.com/rel/tipsi", Jones, et al. Expires June 2, 2013 [Page 7] Internet-Draft WebFinger December 2012 "href" : "http://192.168.1.5/npap/" } ] } While this example is fictitious, you can imagine that perhaps the Transport Independent, Printer/System Interface [16] may be enhanced with a web interface that allows a device that understands the TIP/SI web interface specification to query the printer for toner levels. 5. WebFinger Protocol WebFinger is a simple HTTP-based web service that returns a JSON Resource Descriptor (JRD) to convey information about an entity on the Internet and the Cross-Origin Resource Sharing (CORS) [10] specification to facilitate queries made via a web browser. This specification defines URI parameters that are passed from the client to the server when issuing a request. These parameters, "resource" and "rel", and the parameter values are included in the "query" component of the URI (see Section 3.4 of RFC 3986). To construct the "query" component, the client performs the following 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 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 percent-encoded parameter value. The client MUST NOT insert any spaces while constructing the string. The order in which the client places each parameter and its corresponding parameter value is unspecified. 5.1. Performing a WebFinger Query WebFinger clients issue queries to the well-known resource /.well- known/webfinger. All queries MUST include the "resource" parameter exactly once and set to the value of the URI for which information is being sought. If the "resource" parameter is absent or malformed, the WebFinger server MUST return a 400 status code. Clients MUST query the server using HTTPS and utilize HTTP only if an HTTPS connection cannot be established, and then only if the client issuing the query will not utilize information in the response in such a way as to compromise user security or privacy. As an example, a client using WebFinger to facilitate logging into a web site MUST only utilize HTTPS to ensure that a user is not misdirected to a rogue web site that might steal the user's credentials. If the HTTPS server has an invalid certificate or returns an HTTP status code Jones, et al. Expires June 2, 2013 [Page 8] Internet-Draft WebFinger December 2012 indicating some error, including a 4xx or 5xx, the client MUST NOT use HTTP in attempt to complete the discovery. WebFinger servers MUST return a JRD as the representation for the resource if the client requests no format explicitly via the HTTP "Accept" header. A client MAY include the "Accept" header to indicate a desired representation, though no other representation is defined in this specification. The media type used for the JSON Resource Descriptor (JRD) is "application/json" [5]. If the client queries the WebFinger server and provides a URI for which the server has no information, the server MUST return a 404 status code. WebFinger servers can include cache validators in a response to enable conditional requests by clients and/or expiration times as per RFC 2616 section 13. 5.2. The JSON Resource Descriptor (JRD) The JSON Resource Descriptor (JRD) is a JSON object that is comprised of name/value pairs appearing in this RECOMMENDED order: o expires o subject o aliases o properties o links The members "expires" and "subject" are name/value pairs whose value are strings, "aliases" is an array of strings, "properties" is an object comprised of name/value pairs whose values are strings, and "links" is an array of objects that contain link relation information. When processing a JRD, the client MUST ignore any unknown member and not treat the presence of an unknown member as an error. Below, each of these members of the JRD is described in more detail. 5.2.1. expires The value of the "expires" member is a string that indicates the date and time after which the JRD SHOULD be considered expired and no longer utilized. The format of the date/time string is: YYYY-MM-DDTHH:MM:SSZ Jones, et al. Expires June 2, 2013 [Page 9] Internet-Draft WebFinger December 2012 Here, "YYYY" indicates the four-digit year, "MM" indicates the two- digit month (in the range of 01 to 12), and "DD" indicates the two- digit day of the month (in the range of 01 to 31). The "T" is literally an ASCII "T" that exists merely as a separator between the date and the time. The "HH" indicates the two-digit hour of the day (in the range of 01 to 12), "MM" indicates the two-digit minute of the day (in the range of 00 to 59), and "SS" indicates the two-digit number of seconds (in the range of 00 to 59). A colon (":") character MUST separate the hours, minutes, and seconds values, and a hyphen ("-") MUST separate the year, month, and day in the string. The "Z" at the end of the string is literally an ASCII "Z" that indicates UTC time and MUST be present. The "expires" string MUST utilize UTC time. An example of the "expires" member is: "expires" : "2012-11-16T19:41:35Z" The server MAY include the "expires" header in a JRD and clients SHOULD honor the value if present. 5.2.2. subject The value of the "subject" member is a string that MUST be set to the same value as the "resource" parameter in the client request. This is a URI that identifies the entity for which the client queried the server. The "subject" member MUST be included in the JRD. 5.2.3. aliases The "aliases" array is an array of zero or more URI strings that identify the same entity as the "subject" URI. Each URI must be an absolute URI. The server MAY include the "aliases" array in the JRD. 5.2.4. properties The "properties" object is comprised of zero or more name/value pairs whose names are absolute URIs and whose values are strings or null. Properties are used to convey additional information about the subject of the JRD. As an example, consider this use of "properties": "properties" : { "http://webfinger.net/rel/name" : "Bob Smith" } The server MAY include the "properties" member in the JRD. Jones, et al. Expires June 2, 2013 [Page 10] Internet-Draft WebFinger December 2012 5.2.5. links The "links" array contains zero or more elements that contain the link relation information. Each element of the array is an object comprised of the following name/value pairs in this RECOMMENDED order: o rel o type o href o titles o properties The members "rel", "type", and "href" are a name/value pairs whose values are strings, "titles" and "properties" are objects comprised of name/value pairs whose values are strings. The order of elements in the "links" array indicates an order of preference. Thus, if there are two or more link relations having the same "rel" value, the first link relation would indicate the user's preferred link relation. Servers MAY include the "links" array in the JRD. Below, each of the members of the objects found in the "links" array is described in more detail. Each object in the "links" array, referred to as a "link relation object", is completely independent from any other object in the array; any requirement on the server to include a given member in the link relation object refers only to that particular object. 5.2.5.1. rel The value of the "rel" member is a string that is either an absolute URI or a registered relation type [11] (see RFC 5988 [4]). The value of the "rel" member MUST contain exactly one URI string or registered relation type and MUST NOT contain a space-separated list of URIs or registered relation types. The URI or registered relation type identifies the type of the link relation. The other members of the object have meaning only once the type of link relation is understood. In some instances, the link relation will have associated semantics that allow a client to query for other resources on the Internet. In other instances, the link relation will have associated semantics that allow the client to utilize the other members of the link relation object without fetching additional external resources. Servers MUST include the "rel" member in the link relation object. Jones, et al. Expires June 2, 2013 [Page 11] Internet-Draft WebFinger December 2012 5.2.5.2. type The value of the "type" member is a string that indicates the media type [12] of the linked resource (see RFC 4288 [13]). Servers MAY include the "type" member in the link relation object. 5.2.5.3. href The value of the "href" member is a string that contains a URI pointing to the linked resource. Servers MAY include the "href" member in the link relation object. 5.2.5.4. titles The "titles" object is comprised of zero or more name/value pairs whose name is a language tag [14] or the string "default". The string is human-readable and describes the link relation. More than one title for the link relation MAY be provided for the benefit of users who utilize the link relation and, if used, a language identifier SHOULD be duly used as the name. If the language is unknown or unspecified, then the name is "default". A server SHOULD NOT include more than one title named with the same language tag (or "default") within the link relation object. The client behavior is undefined if a link relation object includes more than one title named with the same language tag (or "default"), though the client MUST NOT treat this as an error. The client can select whichever title or titles it wishes to utilize. Here is an example of the titles object: "titles" : { "en-us" : "The Magical World of Bob", "fr" : "Le monde magique de Bob" } The server MAY include the "titles" member in the link relation object. 5.2.5.5. properties The "properties" object within the link relation object is comprised of zero or more name/value pairs whose names are absolute URIs and whose values are strings or null. Properties are used to convey additional information about the link relation. As an example, consider this use of "properties": Jones, et al. Expires June 2, 2013 [Page 12] Internet-Draft WebFinger December 2012 "properties" : { "http://example.net/mail/port" : "993" } The server MAY include the "properties" member in the link relation object. 5.3. The "rel" Parameter When issuing a request to the server, the client MAY utilize the "rel" parameter to request only a subset of the information that would otherwise be returned without the "rel" parameter. When the "rel" parameter is used, only the link relations that match the link relations provided via "rel" are included in the array of links returned in the JRD. All other information normally present in a resource descriptor is present in the resource descriptor, even when "rel" is employed. The "rel" parameter MAY be transmitted to the server multiple times in order to request multiple types of link relations. The purpose of the "rel" parameter is to return a subset of resource's link relations. Use of the parameter might reduce processing requirements on either the client or server, and it might also reduce the bandwidth required to convey the partial resource descriptor, especially if there are numerous link relation values to convey for a given resource. Support for the "rel" parameter is OPTIONAL, but RECOMMENDED on the server. Should the server not support the "rel" parameter, it MUST ignore it and process the request as if no "rel" parameter values were present. The following example presents the same example as found in section 4.1, but uses the "rel" parameter in order to select two link relations: GET /.well-known/webfinger? resource=acct%3Abob%40example.com& rel=http%3A%2F%2Fwebfinger.net%2Frel%2Fprofile-page& rel=vcard HTTP/1.1 Host: example.com In this example, the client requests the link relations of type "http://webfinger.net/rel/profile-page" and "vcard". The server then responds with a message like this: HTTP/1.1 200 OK Access-Control-Allow-Origin: * Content-Type: application/json; charset=UTF-8 Jones, et al. Expires June 2, 2013 [Page 13] Internet-Draft WebFinger December 2012 { "expires" : "2012-11-16T19:41:35Z", "subject" : "acct:bob@example.com", "aliases" : [ "http://www.example.com/~bob/" ], "properties" : { "http://example.com/rel/role/" : "employee" }, "links" : [ { "rel" : "http://webfinger.net/rel/profile-page", "href" : "http://www.example.com/~bob/" }, { "rel" : "vcard", "href" : "http://www.example.com/~bob/bob.vcf" } ] } As you can see, the server returned only the link relations requested by the client, but also included the other parts of the JRD. In the event that a client requests links for link relations that are not defined for the specified resource, a resource descriptor MUST be returned. In the returned JRD, the "links" array MAY be absent, empty, or contain only links that did match a provided "rel" value. The server MUST NOT return a 404 status code when a particular link relation specified via "rel" is not defined for the resource, as a 404 status code is reserved for indicating that the resource itself (e.g., either /.well-known/webfinger or the resource indicated via the "resource" parameter) does not exist. 5.4. WebFinger and URIs WebFinger requests can include a parameter specifying the URI of an account, device, or other entity. WebFinger is agnostic regarding the scheme of such a URI: it could be an "acct" URI [7], an "http" or "https" URI, a "mailto" URI, or some other scheme. For resources associated with a user account at a host, use of the "acct" URI scheme is RECOMMENDED, since it explicitly identifies an account accessible via WebFinger. Further, the "acct" URI scheme is not associated with other protocols as, by way of example, the "mailto" URI scheme is associated with email. Since not every host Jones, et al. Expires June 2, 2013 [Page 14] Internet-Draft WebFinger December 2012 offers email service, using the "mailto" URI scheme [9] is not ideal for identifying user accounts on all hosts. That said, use of the "mailto" URI scheme would be ideal for use with WebFinger to discover mail server configuration information for a user. 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 WebFinger server MUST return substantially the same response to both an "acct" URI and any alias URI for the account, including the same set of link relations and properties. The only name/value pairs in the response that MAY be different include "subject", "expires", and "aliases". In addition, the server SHOULD include the entire list aliases for the user's account in the JRD returned when querying the LRDD resource or when utilizing the "resource" parameter. 6. Cross-Origin Resource Sharing (CORS) WebFinger resources might not be accessible from a web browser due to "Same-Origin" policies. The current best practice is to make resources available to browsers through Cross-Origin Resource Sharing (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: * There are cases where defaulting to the least restrictive setting is not appropriate, for example a WebFinger server on an intranet that 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 As with all web resources, access to the /.well-known/webfinger resource MAY require authentication. Further, failure to provide required credentials MAY result in the server forbidding access or providing a different response than had the client authenticated with the server. Likewise, a server MAY provide different responses to different clients based on other factors, such as whether the client is inside or outside a corporate network. As a concrete example, a query performed on the internal corporate network might return link relations to employee pictures, whereas link relations for employee pictures might not be provided to external entities. Jones, et al. Expires June 2, 2013 [Page 15] Internet-Draft WebFinger December 2012 Further, link relations provided in a WebFinger server response MAY point to web resources that impose access restrictions. For example, the aforementioned corporate server may provide both internal and external entities with URIs to employee pictures, but further authentication might be required in order for the client to access the picture resources if the request comes from outside the corporate network. The decisions made with respect to what set of link relations a WebFinger server provides to one client versus another and what resources require further authentication, as well as the specific authentication mechanisms employed, are outside the scope of this document. 8. Hosted WebFinger Services As with most services provided on the Internet, it is possible for a domain owner to utilize "hosted" WebFinger services. By way of example, a domain owner might control most aspects of their domain, 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 record points to the mail server to which mail for the domain should be delivered. It does not matter to the sending mail server whether those MX records point to a server in the destination domain or a different domain. Likewise, a domain owner might utilize the services of a third party 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 hosted email serves, the domain owner is required to redirect HTTP(S) queries to its domain to allow for hosted WebFinger services. When a query is issued to /.well-known/webfinger, the web server MUST return a 301, 302, or 307 response status code that includes a Location header pointing to the location of the hosted WebFinger service URL. The WebFinger service URL does not need to point to /.well-known/* on the hosting service provider server. WebFinger clients MUST follow all 301, 302, or 307 redirection requests. As an example, assume that example.com's WebFinger services are hosted by example.net. Suppose a client issues a query for acct:alice@example.com like this: GET /.well-known/webfinger? resource=acct%3Aalice%40example.com HTTP/1.1 Host: example.com The server might respond with this: Jones, et al. Expires June 2, 2013 [Page 16] Internet-Draft WebFinger December 2012 HTTP/1.1 307 Temporary Redirect Location: http://wf.example.net/example.com/webfinger? resource=acct%3Aalice%40example.com HTTP/1.1 The client MUST follow the redirection, re-issuing the request to the URL provided in the Location header. 9. Security Considerations Since this specification utilizes Cross-Origin Resource Sharing (CORS) [10], all of the security considerations applicable CORS are also applicable to this specification. The recommended use of HTTPS is to ensure that information is not 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 on the Internet accessible through WebFinger means that any user can access that information. While WebFinger can be an extremely useful tool for allowing quick and easy access to one's avatar, blog, or other personal information, users should understand the risks, too. If one does not wish to share certain information with the world, do not allow that information to be freely accessible through WebFinger and do not use any service supporting WebFinger. Further, WebFinger servers MUST NOT be used to provide any personal information to any party unless explicitly or implicitly authorized by the person whose information is being shared. Implicit authorization can be 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 with respect to dynamic information one might wish to share, such as the current location of a user. WebFinger can be a powerful tool used to assemble information about a person all in one place, but service providers and users should be mindful of the nature of that information shared and the fact that it might be available for the Jones, et al. Expires June 2, 2013 [Page 17] Internet-Draft WebFinger December 2012 entire world to see. Sharing location information, for example, would potentially put a person in danger from any individual who might seek to inflict harm on that person. 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 information available via WebFinger, such as a WebFinger server for use inside a corporate network, the network administrator must take measures necessary to limit access from outside the network. Using standard methods for securing web resources, network administrators do have the ability to control access to resources that might return sensitive information. Further, WebFinger servers can be employed in such a way as to require authentication and prevent disclosure of information to unauthorized entities. Finally, a WebFinger server has no means of ensuring that information provided by a user is accurate. Likewise, neither the server nor the client can be absolutely guaranteed that information has not been manipulated either at the server or along the communication path between the client and server. Use of HTTPS helps to address some concerns with manipulation of information along the communication path, but it clearly cannot address issues where the server provided incorrect information, either due to being provided false information or due to malicious behavior on the part of the server administrator. As with any information service available on the Internet, users should wary of information received from untrusted sources. 10. IANA Considerations This specification registers the "webfinger" well-known URI in the Well-Known URI Registry as defined by [3]. URI suffix: webfinger Change controller: IETF Specification document(s): RFC QQQ Related information: The response from WebFinger server will be a JSON Resource Descriptor (JRD) as described in Section 5.2 of RFC QQQ. [RFC EDITOR: Please replace "QQQ" references in this section with the number for this RFC.] Jones, et al. Expires June 2, 2013 [Page 18] Internet-Draft WebFinger December 2012 11. Acknowledgments The authors would like to acknowledge Eran Hammer-Lahav, Blaine Cook, Brad Fitzpatrick, Laurent-Walter Goix, Joe Clarke, Michael B. Jones, Peter Saint-Andre, Dick Hardt, Tim Bray, and Joe Gregorio for their invaluable input. 12. References 12.1. Normative References [1] Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, March 1997. [2] Fielding, R., Gettys, J., Mogul, J., Frystyk, H., Masinter, L., Leach, P., and T. Berners-Lee, "Hypertext Transfer Protocol -- HTTP/1.1", RFC 2616, June 1999. [3] Nottingham, M., Hammer-Lahav, E., "Defining Well-Known Uniform Resource Identifiers (URIs)", RFC 5785, April 2010. [4] Nottingham, M., "Web Linking", RFC 5988, October 2010. [5] Crockford, D., "The application/json Media Type for JavaScript Object Notation (JSON)", RFC 4627, July 2006. [6] Berners-Lee, T., Fielding, R., and Masinter, L., "Uniform Resource Identifier (URI): Generic Syntax", STD 66, RFC 3986, January 2005. [7] Duerst, M., "Internationalized Resource Identifiers (IRIs)", RFC 3987, January 2005. [8] Saint-Andre, P., "The 'acct' URI Scheme", draft-ietf-appsawg- acct-uri-01, October 2012. [9] Duerst, M., Masinter, L., and J. Zawinski, "The 'mailto' URI Scheme", RFC 6068, October 2010. [10] Van Kesteren, A., "Cross-Origin Resource Sharing", W3C CORS http://www.w3.org/TR/cors/, July 2010. [11] IANA, "Link Relations", http://www.iana.org/assignments/link- relations/. [12] IANA, "MIME Media Types", http://www.iana.org/assignments/media-types/index.html. Jones, et al. Expires June 2, 2013 [Page 19] Internet-Draft WebFinger December 2012 [13] Freed, N., Klensin, J., "Media Type Specifications and Registration Procedures", RFC 4288, December 2005. [14] Phillips, A., Davis, M., "Tags for Identifying Languages", RFC 5646, January 2001. 12.2. Informative References [15] Perreault, S., "vCard Format Specification", RFC 6350, August 2011. [16] "Transport Independent, Printer/System Interface", IEEE Std 1284.1-1997, 1997. [17] Sakimura, N., Bradley, J., Jones, M., de Medeiros, B., Mortimore, C., and E. Jay, "OpenID Connect Messages 1.0", June 2012, http://openid.net/specs/openid-connect-messages-1_0.html. Author's Addresses Paul E. Jones Cisco Systems, Inc. 7025 Kit Creek Rd. Research Triangle Park, NC 27709 USA Phone: +1 919 476 2048 Email: paulej@packetizer.com IM: xmpp:paulej@packetizer.com Gonzalo Salgueiro Cisco Systems, Inc. 7025 Kit Creek Rd. Research Triangle Park, NC 27709 USA Phone: +1 919 392 3266 Email: gsalguei@cisco.com IM: xmpp:gsalguei@cisco.com Joseph Smarr Google Email: jsmarr@google.com Jones, et al. Expires June 2, 2013 [Page 20]