GENWiki

Premier IT Outsourcing and Support Services within the UK

User Tools

Site Tools


rfc:rfc7033

Internet Engineering Task Force (IETF) P. Jones Request for Comments: 7033 G. Salgueiro Category: Standards Track Cisco Systems ISSN: 2070-1721 M. Jones

                                                             Microsoft
                                                              J. Smarr
                                                                Google
                                                        September 2013
                             WebFinger

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.  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

 This is an Internet Standards Track document.
 This document is a product of the Internet Engineering Task Force
 (IETF).  It represents the consensus of the IETF community.  It has
 received public review and has been approved for publication by the
 Internet Engineering Steering Group (IESG).  Further information on
 Internet Standards is available in Section 2 of RFC 5741.
 Information about the current status of this document, any errata,
 and how to provide feedback on it may be obtained at
 http://www.rfc-editor.org/info/rfc7033.

Copyright Notice

 Copyright (c) 2013 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. Standards Track [Page 1] RFC 7033 WebFinger September 2013

Table of Contents

 1. Introduction ....................................................3
 2. Terminology .....................................................3
 3. Example Uses of WebFinger .......................................4
    3.1. Identity Provider Discovery for OpenID Connect .............4
    3.2. Getting Author and Copyright Information for a Web Page ....5
 4. WebFinger Protocol ..............................................7
      4.1. Constructing the Query Component of the Request URI.......7
      4.2. Performing a WebFinger Query..............................8
      4.3. The "rel" Parameter.......................................9
      4.4. The JSON Resource Descriptor (JRD).......................11
         4.4.1. subject.............................................11
         4.4.2. aliases.............................................11
         4.4.3. properties..........................................12
         4.4.4. links...............................................12
      4.5. WebFinger and URIs.......................................14
 5. Cross-Origin Resource Sharing (CORS) ...........................14
 6. Access Control .................................................15
 7. Hosted WebFinger Services ......................................15
 8. Definition of WebFinger Applications ...........................16
    8.1. Specification of the URI Scheme and URI ...................17
    8.2. Host Resolution ...........................................17
    8.3. Specification of Properties ...............................17
    8.4. Specification of Links ....................................18
    8.5. One URI, Multiple Applications ............................18
    8.6. Registration of Link Relation Types and Properties ........19
 9. Security Considerations ........................................19
    9.1. Transport-Related Issues ..................................19
    9.2. User Privacy Considerations ...............................19
    9.3. Abuse Potential ...........................................21
    9.4. Information Reliability ...................................21
 10. IANA Considerations ...........................................22
    10.1. Well-Known URI ...........................................22
    10.2. JSON Resource Descriptor (JRD) Media Type ................22
    10.3. Registering Link Relation Types ..........................24
    10.4. Establishment of the "WebFinger Properties" Registry .....24
         10.4.1. The Registration Template .........................24
         10.4.2. The Registration Procedures .......................25
 11. Acknowledgments ...............................................26
 12. References ....................................................26
    12.1. Normative References .....................................26
    12.2. Informative References ...................................27

Jones, et al. Standards Track [Page 2] RFC 7033 WebFinger September 2013

1. Introduction

 WebFinger is used to discover information about people or other
 entities on the Internet that are identified by a URI [6] using
 standard Hypertext Transfer Protocol (HTTP) [2] methods over a secure
 transport [12].  A WebFinger resource returns a JavaScript Object
 Notation (JSON) [5] object describing the entity that is queried.
 The JSON object is referred to as the JSON Resource Descriptor (JRD).
 For a person, the type of information that might be discoverable via
 WebFinger includes a personal profile address, identity service,
 telephone number, or preferred avatar.  For other entities on the
 Internet, a WebFinger resource might return JRDs containing link
 relations [8] that enable a client to discover, for example, that a
 printer can print in color on A4 paper, the physical location of a
 server, or other static information.
 Information returned via WebFinger might be for direct human
 consumption (e.g., looking up someone's phone number), or it might be
 used by systems to help carry out some operation (e.g., facilitating,
 with additional security mechanisms, logging into a web site by
 determining a user's identity service).  The information is intended
 to be static in nature, and, as such, WebFinger is not intended to be
 used to return dynamic information like the temperature of a CPU or
 the current toner level in a laser printer.
 The WebFinger protocol is designed to be used across many
 applications.  Applications that wish to utilize WebFinger will need
 to specify properties, titles, and link relation types that are
 appropriate for the application.  Further, applications will need to
 define the appropriate URI scheme to utilize for the query target.
 Use of WebFinger is illustrated in the examples in Section 3 and
 described more formally in Section 4.  Section 8 describes how
 applications of WebFinger may be defined.

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".  A link relation is an
 attribute-value pair in which the attribute identifies the type of
 relationship between the linked entity or resource and the
 information specified in the value.  In Web Linking [4], the link
 relation is represented using an HTTP entity-header of "Link", where
 the "rel" attribute specifies the type of relationship and the "href"

Jones, et al. Standards Track [Page 3] RFC 7033 WebFinger September 2013

 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 [8] or
 a URI [6].
 The use of URIs throughout this document refers to URIs following the
 syntax specified in Section 3 of RFC 3986 [6].  Relative URIs, having
 syntax following that of Section 4.2 of RFC 3986, are not used with
 WebFinger.

3. Example Uses of WebFinger

 This section shows a few sample uses of WebFinger.  Any application
 of WebFinger would be specified outside of this document, as
 described in Section 8.  The examples in this section should be
 simple enough to understand without having seen the formal
 specifications of the applications.

3.1. Identity Provider Discovery for OpenID Connect

 Suppose Carol wishes to authenticate with a web site she visits using
 OpenID Connect [15].  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 WebFinger resource might utilize the "rel" parameter as
 described in Section 4.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

Jones, et al. Standards Track [Page 4] RFC 7033 WebFinger September 2013

 The server might respond like this:
   HTTP/1.1 200 OK
   Access-Control-Allow-Origin: *
   Content-Type: application/jrd+json
   {
     "subject" : "acct:carol@example.com",
     "links" :
     [
       {
         "rel" : "http://openid.net/specs/connect/1.0/issuer",
         "href" : "https://openid.example.com"
       }
     ]
   }
 Since the "rel" parameter only serves to filter the link relations
 returned by the resource, other name/value pairs in the response,
 including any aliases or properties, would be returned.  Also, since
 support for the "rel" parameter is not guaranteed, the client must
 not assume the "links" array will contain only the requested link
 relation.

3.2. Getting Author and Copyright Information for a Web Page

 Suppose an application is defined to retrieve metadata information
 about a web page URL, such as author and copyright information.  To
 retrieve that information, the client can utilize WebFinger to issue
 a query for the specific URL.  Suppose the URL of interest is
 http://blog.example.com/article/id/314.  The client would issue a
 query similar to the following:
   GET /.well-known/webfinger?
        resource=http%3A%2F%2Fblog.example.com%2Farticle%2Fid%2F314
        HTTP/1.1
   Host: blog.example.com

Jones, et al. Standards Track [Page 5] RFC 7033 WebFinger September 2013

 The server might then reply in this way:
   HTTP/1.1 200 OK
   Access-Control-Allow-Origin: *
   Content-Type: application/jrd+json
   {
     "subject" : "http://blog.example.com/article/id/314",
     "aliases" :
     [
       "http://blog.example.com/cool_new_thing",
       "http://blog.example.com/steve/article/7"
     ],
     "properties" :
     {
       "http://blgx.example.net/ns/version" : "1.3",
       "http://blgx.example.net/ns/ext" : null
     },
     "links" :
     [
       {
         "rel" : "copyright",
         "href" : "http://www.example.com/copyright"
       },
       {
         "rel" : "author",
         "href" : "http://blog.example.com/author/steve",
         "titles" :
         {
           "en-us" : "The Magical World of Steve",
           "fr" : "Le Monde Magique de Steve"
         },
         "properties" :
         {
           "http://example.com/role" : "editor"
         }
       }
     ]
   }
 In the above example, we see that the server returned a list of
 aliases, properties, and links related to the subject URL.  The links
 contain references to information for each link relation type.  For
 the author link, the server provided a reference to the author's
 blog, along with a title for the blog in two languages.  The server
 also returned a single property related to the author, indicating the
 author's role as editor of the blog.

Jones, et al. Standards Track [Page 6] RFC 7033 WebFinger September 2013

 It is worth noting that, while the server returned just two links in
 the "links" array in this example, a server might return any number
 of links when queried.

4. WebFinger Protocol

 The WebFinger protocol is used to request information about an entity
 identified by a query target (a URI).  The client can optionally
 specify one or more link relation types for which it would like to
 receive information.
 A WebFinger request is an HTTPS request to a WebFinger resource.  A
 WebFinger resource is a well-known URI [3] using the HTTPS scheme
 constructed along with the required query target and optional link
 relation types.  WebFinger resources MUST NOT be served with any
 other URI scheme (such as HTTP).
 A WebFinger resource is always given a query target, which is another
 URI that identifies the entity whose information is sought.  GET
 requests to a WebFinger resource convey the query target in the
 "resource" parameter of the WebFinger URI's query string; see Section
 4.1 for details.
 The host to which a WebFinger query is issued is significant.  If the
 query target contains a "host" portion (Section 3.2.2 of RFC 3986),
 then the host to which the WebFinger query is issued SHOULD be the
 same as the "host" portion of the query target, unless the client
 receives instructions through some out-of-band mechanism to send the
 query to another host.  If the query target does not contain a "host"
 portion, then the client chooses a host to which it directs the query
 using additional information it has.
 The path component of a WebFinger URI MUST be the well-known path
 "/.well-known/webfinger".  A WebFinger URI MUST contain a query
 component that encodes the query target and optional link relation
 types as specified in Section 4.1.
 The WebFinger resource returns a JSON Resource Descriptor (JRD) as
 the resource representation to convey information about an entity on
 the Internet.  Also, the Cross-Origin Resource Sharing (CORS) [7]
 specification is utilized to facilitate queries made via a web
 browser.

4.1. Constructing the Query Component of the Request URI

 A WebFinger URI MUST contain a query component (see Section 3.4 of
 RFC 3986).  The query component MUST contain a "resource" parameter
 and MAY contain one or more "rel" parameters.  The "resource"

Jones, et al. Standards Track [Page 7] RFC 7033 WebFinger September 2013

 parameter MUST contain the query target (URI), and the "rel"
 parameters MUST contain encoded link relation types according to the
 encoding described in this section.
 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.  The encoding is done to conform to the
 query production in Section 3.4 of that specification, with the
 addition that any instances of the "=" and "&" characters within the
 parameter values 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-value pair within the query component does not matter in
 the interpretation of the query component.

4.2. Performing a WebFinger Query

 A WebFinger client issues a query using the GET method to the well-
 known [3] resource identified by the URI whose path component is
 "/.well-known/webfinger" and whose query component 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
 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
 client determines that the resource has an invalid certificate, the
 resource returns a 4xx or 5xx status code, or if the HTTPS connection
 cannot be established for any reason, then the client MUST accept
 that the WebFinger query has failed and MUST NOT attempt to reissue
 the WebFinger request using HTTP over a non-secure connection.
 A WebFinger resource MUST return a JRD as the representation for the
 resource if the client requests no other supported format explicitly
 via the HTTP "Accept" header.  The client MAY include the "Accept"
 header to indicate a desired representation; representations other
 than JRD might be defined in future specifications.  The WebFinger

Jones, et al. Standards Track [Page 8] RFC 7033 WebFinger September 2013

 resource MUST silently ignore any requested representations that it
 does not understand or support.  The media type used for the JSON
 Resource Descriptor (JRD) is "application/jrd+json" (see Section
 10.2).
 The properties, titles, and link relation types returned by the
 server in a JRD might be varied and numerous.  For example, the
 server might return information about a person's blog, vCard [14],
 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
 return a JRD with an empty "links" array or no "links" array.
 A WebFinger resource MAY redirect the client; if it does, the
 redirection MUST only be to an "https" URI and the client MUST
 perform certificate validation again when redirected.
 A WebFinger resource can include cache validators in a response to
 enable conditional requests by the client and/or expiration times as
 per Section 13 of RFC 2616.

4.3. The "rel" Parameter

 When issuing a request to a WebFinger resource, 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 and accepted, only the
 link relation types that match the link relation type provided via
 the "rel" parameter are included in the array of links returned in
 the JRD.  If there are no matching link relation types defined for
 the resource, the "links" array in the JRD will be either absent or
 empty.  All other information present in a resource descriptor
 remains present, even when "rel" is employed.
 The "rel" parameter MAY be included multiple times in order to
 request multiple link relation types.
 The purpose of the "rel" parameter is to return a subset of "link
 relation objects" (see Section 4.4.4) that would otherwise be
 returned in the resource descriptor.  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" value.  Note that if a client
 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 no "links" array.

Jones, et al. Standards Track [Page 9] RFC 7033 WebFinger September 2013

 WebFinger resources SHOULD support the "rel" parameter.  If the
 resource does not support the "rel" parameter, it MUST ignore the
 parameter and process the request as if no "rel" parameter values
 were present.
 The following example uses the "rel" parameter to request links for
 two link relation types:
  GET /.well-known/webfinger?
      resource=acct%3Abob%40example.com&
      rel=http%3A%2F%2Fwebfinger.example%2Frel%2Fprofile-page&
      rel=http%3A%2F%2Fwebfinger.example%2Frel%2Fbusinesscard HTTP/1.1
  Host: example.com
 In this example, the client requests the link relations of type
 "http://webfinger.example/rel/profile-page" and
 "http://webfinger.example/rel/businesscard".  The server then
 responds with a message like this:
   HTTP/1.1 200 OK
   Access-Control-Allow-Origin: *
   Content-Type: application/jrd+json
   {
     "subject" : "acct:bob@example.com",
     "aliases" :
     [
       "https://www.example.com/~bob/"
     ],
     "properties" :
     {
         "http://example.com/ns/role" : "employee"
     },
     "links" :
     [
       {
         "rel" : "http://webfinger.example/rel/profile-page",
         "href" : "https://www.example.com/~bob/"
       },
       {
         "rel" : "http://webfinger.example/rel/businesscard",
         "href" : "https://www.example.com/~bob/bob.vcf"
       }
     ]
   }

Jones, et al. Standards Track [Page 10] RFC 7033 WebFinger September 2013

 As you can see in the response, the resource representation contains
 only the links of the types requested by the client and for which the
 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 be returned securely.

4.4. The JSON Resource Descriptor (JRD)

 The JSON Resource Descriptor (JRD), originally introduced in RFC 6415
 [16] and based on the Extensible Resource Descriptor (XRD) format
 [17], is a JSON object that comprises the following name/value pairs:
         o subject
         o aliases
         o properties
         o links
 The member "subject" is a name/value pair whose value is a string,
 "aliases" is an array of strings, "properties" is an object
 comprising 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.

4.4.1. subject

 The value of the "subject" member is a URI that identifies the entity
 that the JRD describes.
 The "subject" value returned by a WebFinger resource MAY differ from
 the value of the "resource" parameter used in the client's request.
 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
 the resource prefers to express URIs in canonical form.
 The "subject" member SHOULD be present in the JRD.

4.4.2. aliases

 The "aliases" array is an array of zero or more URI strings that
 identify the same entity as the "subject" URI.
 The "aliases" array is OPTIONAL in the JRD.

Jones, et al. Standards Track [Page 11] RFC 7033 WebFinger September 2013

4.4.3. properties

 The "properties" object comprises zero or more name/value pairs whose
 names are URIs (referred to as "property identifiers") 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.example/ns/name" : "Bob Smith" }
 The "properties" member is OPTIONAL in the JRD.

4.4.4. links

 The "links" array has any number of member objects, each of which
 represents a link [4].  Each of these link objects can have the
 following members:
         o rel
         o type
         o href
         o titles
         o properties
 The "rel" and "href" members are strings representing the link's
 relation type and the target URI, respectively.  The context of the
 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 MAY be interpreted as
 indicating 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.
 The "links" array is OPTIONAL 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 to include a
 given member in the link relation object refers only to that
 particular object.

Jones, et al. Standards Track [Page 12] RFC 7033 WebFinger September 2013

4.4.4.1. rel

 The value of the "rel" member is a string that is either a URI or a
 registered relation type [8] (see RFC 5988 [4]).  The value of the
 "rel" member MUST contain exactly one URI or registered relation
 type.  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 enabling the client to query for other
 resources on the Internet.  In other instances, the link relation
 will have associated semantics enabling the client to utilize the
 other members of the link relation object without fetching additional
 external resources.
 URI link relation type values are compared using the "Simple String
 Comparison" algorithm of Section 6.2.1 of RFC 3986.
 The "rel" member MUST be present in the link relation object.

4.4.4.2. type

 The value of the "type" member is a string that indicates the media
 type [9] of the target resource (see RFC 6838 [10]).
 The "type" member is OPTIONAL in the link relation object.

4.4.4.3. href

 The value of the "href" member is a string that contains a URI
 pointing to the target resource.
 The "href" member is OPTIONAL in the link relation object.

4.4.4.4. titles

 The "titles" object comprises zero or more name/value pairs whose
 names are a language tag [11] or the string "und".  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 "und".
 A JRD SHOULD NOT include more than one title identified with the same
 language tag (or "und") within the link relation object.  Meaning is
 undefined if a link relation object includes more than one title

Jones, et al. Standards Track [Page 13] RFC 7033 WebFinger September 2013

 named with the same language tag (or "und"), though this MUST NOT be
 treated as an error.  A client MAY select whichever title or titles
 it wishes to utilize.
 Here is an example of the "titles" object:
   "titles" :
   {
     "en-us" : "The Magical World of Steve",
     "fr" : "Le Monde Magique de Steve"
   }
 The "titles" member is OPTIONAL in the link relation object.

4.4.4.5. properties

 The "properties" object within the link relation object comprises
 zero or more name/value pairs whose names are URIs (referred to as
 "property identifiers") and whose values are strings or null.
 Properties are used to convey additional information about the link
 relation.  As an example, consider this use of "properties":
   "properties" : { "http://webfinger.example/mail/port" : "993" }
 The "properties" member is OPTIONAL in the link relation object.

4.5. WebFinger and URIs

 WebFinger requests include a "resource" parameter (see Section 4.1)
 specifying the query target (URI) for which the client requests
 information.  WebFinger is neutral regarding the scheme of such a
 URI: it could be an "acct" URI [18], an "http" or "https" URI, a
 "mailto" URI [19], or some other scheme.

5. 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) [7], 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
 resource:
    Access-Control-Allow-Origin: *

Jones, et al. Standards Track [Page 14] RFC 7033 WebFinger September 2013

 There are cases where defaulting to the least restrictive setting is
 not appropriate.  For example, a 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.  A
 server that wishes to restrict access to information from external
 entities SHOULD use a more restrictive Access-Control-Allow-Origin
 header.

6. Access Control

 As with all web resources, access to the WebFinger resource could
 require authentication.  Further, failure to provide required
 credentials might result in the server forbidding access or providing
 a different response than had the client authenticated with the
 server.
 Likewise, a WebFinger resource 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.
 Further, link relations provided in a WebFinger resource
 representation might 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 resource 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.

7. 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 exchange (MX) records identify mail servers for a domain.
 An MX record points to the mail server to which mail for the domain
 should be delivered.  To the sending server, it does not matter
 whether those MX records point to a server in the destination domain
 or a different domain.

Jones, et al. Standards Track [Page 15] RFC 7033 WebFinger September 2013

 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 is required to insert MX records into DNS to allow for
 hosted email services, the domain owner is required to redirect HTTP
 queries to its domain to allow for hosted WebFinger services.
 When a query is issued to the WebFinger resource, the web server MUST
 return a response with a redirection status code that includes a
 Location header pointing to the location of the hosted WebFinger
 service URI.  This WebFinger service URI does not need to point to
 the well-known WebFinger location on the hosting service provider
 server.
 As an example, assume that example.com's WebFinger services are
 hosted by wf.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:
   HTTP/1.1 307 Temporary Redirect
   Access-Control-Allow-Origin: *
   Location: https://wf.example.net/example.com/webfinger?
                 resource=acct%3Aalice%40example.com
 The client can then follow the redirection, reissuing the request to
 the URI provided in the Location header.  Note that the server will
 include any required URI parameters in the Location header value,
 which could be different than the URI parameters the client
 originally used.

8. Definition of WebFinger Applications

 This specification details the protocol syntax used to query a domain
 for information about a URI, the syntax of the JSON Resource
 Descriptor (JRD) that is returned in response to that query, security
 requirements and considerations, hosted WebFinger services, various
 expected HTTP status codes, and so forth.  However, this
 specification does not enumerate the various possible properties or
 link relation types that might be used in conjunction with WebFinger
 for a particular application, nor does it define what properties or
 link relation types one might expect to see in response to querying
 for a particular URI or URI scheme.  Nonetheless, all of these
 unspecified elements are important in order to implement an
 interoperable application that utilizes the WebFinger protocol and

Jones, et al. Standards Track [Page 16] RFC 7033 WebFinger September 2013

 MUST be specified in the relevant document(s) defining the particular
 application making use of the WebFinger protocol according to the
 procedures described in this section.

8.1. Specification of the URI Scheme and URI

 Any application that uses WebFinger MUST specify the URI scheme(s),
 and to the extent appropriate, what forms the URI(s) might take.  For
 example, when querying for information about a user's account at some
 domain, it might make sense to specify the use of the "acct" URI
 scheme [18].  When trying to obtain the copyright information for a
 web page, it makes sense to specify the use of the web page URI
 (either http or https).
 The examples in Sections 3.1 and 3.2 illustrate the use of different
 URI schemes with WebFinger applications.  In the example in Section
 3.1, WebFinger is used to retrieve information pertinent to OpenID
 Connect.  In the example in Section 3.2, WebFinger is used to
 discover metadata information about a web page, including author and
 copyright information.  Each of these WebFinger applications needs to
 be fully specified to ensure interoperability.

8.2. Host Resolution

 As explained in Section 4, the host to which a WebFinger query is
 issued is significant.  In general, WebFinger applications would
 adhere to the procedures described in Section 4 in order to properly
 direct a WebFinger query.
 However, some URI schemes do not have host portions and there might
 be some applications of WebFinger for which the host portion of a URI
 cannot or should not be utilized.  In such instances, the application
 specification MUST clearly define the host resolution procedures,
 which might include provisioning a "default" host within the client
 to which queries are directed.

8.3. Specification of Properties

 WebFinger defines both subject-specific properties (i.e., properties
 described in Section 4.4.3 that relate to the URI for which
 information is queried) and link-specific properties (see Section
 4.4.4.5).  This section refers to subject-specific properties.
 Applications that utilize subject-specific properties MUST define the
 URIs used in identifying those properties, along with valid property
 values.

Jones, et al. Standards Track [Page 17] RFC 7033 WebFinger September 2013

 Consider this portion of the JRD found in the example in Section 3.2.
     "properties" :
     {
       "http://blgx.example.net/ns/version" : "1.3",
       "http://blgx.example.net/ns/ext" : null
     }
 Here, two properties are returned in the WebFinger response.  Each of
 these would be defined in a WebFinger application specification.
 These two properties might be defined in the same WebFinger
 application specification or separately in different specifications.
 Since the latter is possible, it is important that WebFinger clients
 not assume that one property has any specific relationship with
 another property, unless some relationship is explicitly defined in
 the particular WebFinger application specification.

8.4. Specification of Links

 The links returned in a WebFinger response each comprise several
 pieces of information, some of which are optional (refer to Section
 4.4.4).  The WebFinger application specification MUST define each
 link and any values associated with a link, including the link
 relation type ("rel"), the expected media type ("type"), properties,
 and titles.
 The target URI to which the link refers (i.e., the "href"), if
 present, would not normally be specified in an application
 specification.  However, the URI scheme or any special
 characteristics of the URI would usually be specified.  If a
 particular link does not require an external reference, then all of
 the semantics related to the use of that link MUST be defined within
 the application specification.  Such links might rely only on
 properties or titles in the link to convey meaning.

8.5. One URI, Multiple Applications

 It is important to be mindful of the fact that different WebFinger
 applications might specify the use of the same URI scheme, and in
 effect, the same URI for different purposes.  That should not be a
 problem, since each of property identifier (see Sections 4.4.3 and
 4.4.4.5) and link relation type would be uniquely defined for a
 specific application.
 It should be noted that when a client requests information about a
 particular URI and receives a response with a number of different
 property identifiers or link relation types that the response is
 providing information about the URI without any particular semantics.

Jones, et al. Standards Track [Page 18] RFC 7033 WebFinger September 2013

 How the client interprets the information SHOULD be in accordance
 with the particular application specification or set of
 specifications the client implements.
 Any syntactically valid properties or links the client receives and
 that are not fully understood SHOULD be ignored and SHOULD NOT cause
 the client to report an error.

8.6. Registration of Link Relation Types and Properties

 Application specifications MAY define a simple token as a link
 relation type for a link.  In that case, the link relation type MUST
 be registered with IANA as specified in Sections 10.3.
 Further, any defined properties MUST be registered with IANA as
 described in Section 10.4.

9. Security Considerations

9.1. Transport-Related Issues

 Since this specification utilizes Cross-Origin Resource Sharing
 (CORS) [7], all of the security considerations applicable to CORS are
 also applicable to this specification.
 The use of HTTPS is REQUIRED to ensure that information is not
 modified during transit.  It should be acknowledged that in
 environments where a web server is normally available, there exists
 the possibility that a compromised network might have its WebFinger
 resource operating on HTTPS replaced with one operating only over
 HTTP.  As such, clients MUST NOT issue queries over a non-secure
 connection.
 Clients MUST verify that the certificate used on an HTTPS connection
 is valid (as defined in [12]) and accept a response only if the
 certificate is valid.

9.2. User Privacy Considerations

 Service providers and users should be aware that placing information
 on the Internet means that any user can access that information, and
 WebFinger can be used to make it even easier to discover that
 information.  While WebFinger can be an extremely useful tool for
 discovering one's avatar, blog, or other personal data, users should
 also understand the risks.

Jones, et al. Standards Track [Page 19] RFC 7033 WebFinger September 2013

 Systems or services that expose personal data via WebFinger MUST
 provide an interface by which users can select which data elements
 are exposed through the WebFinger interface.  For example, social
 networking sites might allow users to mark certain data as "public"
 and then utilize that marking as a means of determining what
 information to expose via WebFinger.  The information published via
 WebFinger would thus comprise only the information marked as public
 by the user.  Further, the user has the ability to remove information
 from publication via WebFinger by removing this marking.
 WebFinger MUST NOT be used to provide any personal data unless
 publishing that data via WebFinger by the relevant service was
 explicitly authorized by the person whose information is being
 shared.  Publishing one's personal data within an access-controlled
 or otherwise limited environment on the Internet does not equate to
 providing implicit authorization of further publication of that data
 via WebFinger.
 The privacy and security concerns with publishing personal data via
 WebFinger are worth emphasizing again with respect to personal data
 that might reveal a user's current context (e.g., the user's
 location).  The power of WebFinger comes from providing a single
 place where others can find pointers to information about a person,
 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 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.
 Users should be aware of how easily personal data that one might
 publish can be used in unintended ways.  In one study relevant to
 WebFinger-like services, Balduzzi et al. [20] took a large set of
 leaked email addresses and demonstrated a number of potential privacy
 concerns, including the ability to cross-correlate the same user's
 accounts over multiple social networks.  The authors also describe
 potential mitigation strategies.
 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 WebFinger resources for
 use inside a corporate network, the network administrator needs to
 take necessary measures 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, a server can be
 employed in such a way as to require authentication and prevent
 disclosure of information to unauthorized entities.

Jones, et al. Standards Track [Page 20] RFC 7033 WebFinger September 2013

9.3. Abuse Potential

 Service providers should be mindful of the potential for abuse using
 WebFinger.
 As one example, one might query a WebFinger server only to discover
 whether or not a given URI is valid.  With such a query, the person
 may deduce that an email identifier is valid, for example.  Such an
 approach could help spammers maintain a current list of known email
 addresses and to discover new ones.
 WebFinger could be used to associate a name or other personal data
 with an email address, allowing spammers to craft more convincing
 email messages.  This might be of particular value in phishing
 attempts.
 It is RECOMMENDED that implementers of WebFinger server software take
 steps to mitigate abuse, including malicious over-use of the server
 and harvesting of user information.  Although there is no mechanism
 that can guarantee that publicly accessible WebFinger databases won't
 be harvested, rate-limiting by IP address will prevent or at least
 dramatically slow harvest by private individuals without access to
 botnets or other distributed systems.  The reason these mitigation
 strategies are not mandatory is that the correct choice of mitigation
 strategy (if any) depends greatly on the context.  Implementers
 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
 use.
 WebFinger client developers should also be aware of potential abuse
 by spammers or those phishing for information about users.  As an
 example, suppose a mail client was configured to automatically
 perform a WebFinger query on the sender of each received mail
 message.  If a spammer sent an email using a unique identifier in the
 'From' header, then when the WebFinger query was performed, the
 spammer would be able to associate the request with a particular
 user's email address.  This would provide information to the spammer,
 including the user's IP address, the fact the user just checked
 email, what kind of WebFinger client the user utilized, and so on.
 For this reason, it is strongly advised that clients not perform
 WebFinger queries unless authorized by the user to do so.

9.4. Information Reliability

 A WebFinger resource has no means of ensuring that information
 provided by a user is accurate.  Likewise, neither the resource nor
 the client can be absolutely guaranteed that information has not been
 manipulated either at the server or along the communication path

Jones, et al. Standards Track [Page 21] RFC 7033 WebFinger September 2013

 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 resource
 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 be wary of information received from untrusted
 sources.

10. IANA Considerations

10.1. Well-Known URI

 This specification registers the "webfinger" well-known URI in the
 "Well-Known URIs" registry as defined by RFC 5785 [3].
 URI suffix:  webfinger
 Change controller:  IETF
 Specification document(s):  RFC 7033
 Related information:  The query to the WebFinger resource will
 include one or more parameters in the query string; see Section 4.1
 of RFC 7033.  Resources at this location are able to return a JSON
 Resource Descriptor (JRD) as described in Section 4.4 of RFC 7033.

10.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 RFC 6838 [10].
 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.

Jones, et al. Standards Track [Page 22] RFC 7033 WebFinger September 2013

 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 7033
 Applications that use this media type:
   The JSON Resource Descriptor (JRD) is used by the WebFinger
   protocol (RFC 7033) 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

Jones, et al. Standards Track [Page 23] RFC 7033 WebFinger September 2013

 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.3. Registering Link Relation Types

 RFC 5988 established a "Link Relation Types" registry that is reused
 by WebFinger applications.
 Link relation types used by WebFinger applications are registered in
 the "Link Relation Types" registry as per the procedures of Section
 6.2.1 of RFC 5988.  The "Notes" entry for the registration SHOULD
 indicate if property values associated with the link relation type
 are registered in the "WebFinger Properties" registry with a link to
 the registry.

10.4. Establishment of the "WebFinger Properties" Registry

 WebFinger utilizes URIs to identify properties of a subject or link
 and the associated values (see Sections 8.3 and 8.6).  This
 specification establishes a new "WebFinger Properties" registry to
 record property identifiers.

10.4.1. The Registration Template

 The registration template for WebFinger properties is:
        o Property Identifier:
        o Link Type:
        o Description:
        o Reference:
        o Notes: [optional]
 The "Property Identifier" must be a URI that identifies the property
 being registered.

Jones, et al. Standards Track [Page 24] RFC 7033 WebFinger September 2013

 The "Link Type" contains the name of a link relation type with which
 this property identifier is used.  If the property is a subject-
 specific property, then this field is specified as "N/A".
 The "Description" is intended to explain the purpose of the property.
 The "Reference" field points to the specification that defines the
 registered property.
 The optional "Notes" field is for conveying any useful information
 about the property that might be of value to implementers.

10.4.2. The Registration Procedures

 The IETF has created a mailing list, webfinger@ietf.org, which can be
 used for public discussion of the WebFinger protocol and any
 applications that use it.  Prior to registration of a WebFinger
 property, discussion on the mailing list is strongly encouraged.  The
 IESG has appointed Designated Experts [13] who will monitor the
 webfinger@ietf.org mailing list and review registrations.
 A WebFinger property is registered with a Specification Required (see
 RFC 5226 [13]) after a review by the Designated Experts.  The review
 is normally expected to take on the order of two to four weeks.
 However, the Designated Experts may approve a registration prior to
 publication of a specification once the Designated Experts are
 satisfied that such a specification will be published.  In evaluating
 registration requests, the Designated Experts should make an effort
 to avoid registering two different properties that have the same
 meaning.  Where a proposed property is similar to an already-defined
 property, the Designated Experts should insist that enough text be
 included in the description or notes section of the template to
 sufficiently differentiate the new property from an existing one.
 The registration procedure begins with a completed registration
 template (as defined above) sent to webfinger@ietf.org.  Once
 consensus is reached on the mailing list, the registration template
 is sent to iana@iana.org.  IANA will then contact the Designated
 Experts and communicate the results to the registrant.  The WebFinger
 mailing list provides an opportunity for community discussion and
 input, and the Designated Experts may use that input to inform their
 review.  Denials should include an explanation and, if applicable,
 suggestions as to how to make the request successful if resubmitted.

Jones, et al. Standards Track [Page 25] RFC 7033 WebFinger September 2013

 The specification registering the WebFinger property MUST include the
 completed registration template shown above.  Once the registration
 procedure concludes successfully, IANA creates or modifies the
 corresponding record in the "WebFinger Properties" registry.

11. Acknowledgments

 This document has benefited from extensive discussion and review by
 many of the members of the APPSAWG working group.  The authors would
 like to especially acknowledge the invaluable input of Eran Hammer-
 Lahav, Blaine Cook, Brad Fitzpatrick, Laurent-Walter Goix, Joe
 Clarke, Peter Saint-Andre, Dick Hardt, Tim Bray, James Snell, Melvin
 Carvalho, Evan Prodromou, Mark Nottingham, Elf Pavlik, Bjoern
 Hoehrmann, Subramanian Moonesamy, Joe Gregorio, John Bradley, and
 others that we have undoubtedly, but inadvertently, missed.
 The authors would also like to express their gratitude to the chairs
 of the APPSAWG working group, especially Salvatore Loreto for his
 assistance in shepherding this document.  We also want to thank Barry
 Leiba and Pete Resnick, the Applications Area Directors, for their
 support and exhaustive reviews.

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. and E. Hammer-Lahav, "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 L. Masinter, "Uniform
       Resource Identifier (URI): Generic Syntax", STD 66, RFC 3986,
       January 2005.
 [7]   Van Kesteren, A., "Cross-Origin Resource Sharing", W3C CORS,
       July 2010, <http://www.w3.org/TR/cors/>.

Jones, et al. Standards Track [Page 26] RFC 7033 WebFinger September 2013

 [8]   IANA, "Link Relations",
       <http://www.iana.org/assignments/link-relations/>.
 [9]   IANA, "MIME Media Types",
       <http://www.iana.org/assignments/media-types>.
 [10]  Freed, N., Klensin, J., and T. Hansen, "Media Type
       Specifications and Registration Procedures", BCP 13, RFC 6838,
       January 2013.
 [11]  Phillips, A., Ed., and M. Davis, Ed., "Tags for Identifying
       Languages", BCP 47, RFC 5646, September 2009.
 [12]  Rescorla, E., "HTTP Over TLS", RFC 2818, May 2000.
 [13]  Narten, T. and H. Alvestrand, "Guidelines for Writing an IANA
       Considerations Section in RFCs", BCP 26, RFC 5226, May 2008.

12.2. Informative References

 [14]  Perreault, S., "vCard Format Specification", RFC 6350, August
       2011.
 [15]  Sakimura, N., Bradley, J., Jones, M., de Medeiros, B.,
       Mortimore, C., and E. Jay, "OpenID Connect Messages 1.0",
       July 2013,
       <http://openid.net/specs/openid-connect-messages-1_0.html>.
 [16]  Hammer-Lahav, E., Ed., and B. Cook, "Web Host Metadata", RFC
       6415, October 2011.
 [17]  Hammer-Lahav, E. and W. Norris, "Extensible Resource Descriptor
       (XRD) Version 1.0",
       <http://docs.oasis-open.org/xri/xrd/v1.0/xrd-1.0.html>.
 [18]  Saint-Andre, P., "The 'acct' URI Scheme", Work in Progress,
       July 2013.
 [19]  Duerst, M., Masinter, L., and J. Zawinski, "The 'mailto' URI
       Scheme", RFC 6068, October 2010.
 [20]  Balduzzi, M., Platzer, C., Thorsten, H., Kirda, E., Balzarotti,
       D., and C. Kruegel "Abusing Social Networks for Automated User
       Profiling", Recent Advances in Intrusion Detection, Springer
       Berlin Heidelberg, March 2010,
       <https://www.eurecom.fr/en/publication/3042/download/
       rs-publi-3042_1.pdf>.

Jones, et al. Standards Track [Page 27] RFC 7033 WebFinger September 2013

Authors' 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
 Michael B. Jones
 Microsoft
 EMail: mbj@microsoft.com
 URI: http://self-issued.info/
 Joseph Smarr
 Google
 EMail: jsmarr@google.com
 URI: http://josephsmarr.com/

Jones, et al. Standards Track [Page 28]

/data/webs/external/dokuwiki/data/pages/rfc/rfc7033.txt · Last modified: 2013/09/27 21:17 by 127.0.0.1

Donate Powered by PHP Valid HTML5 Valid CSS Driven by DokuWiki