RFC 7033
WebFinger
RFC 7033: WebFinger 🦋
okay bestie, so this is RFC 7033, and it's titled WebFinger 💖 It's a Standards Track doc from the IETF, ISSN 2070-1721, dated September 2013. The authors are P. Jones and G. Salgueiro (both Cisco Systems), M. Jones (Microsoft), and J. Smarr (Google) 🫶 There's no Obsoletes or Updates line in the header, so it doesn't list any documents it replaces or changes.
Abstract ✨
okay so this spec defines the WebFinger protocol 🔍 You can use it to discover info about people or other entities on the Internet with plain old standard HTTP methods 🌸 The main point is that WebFinger can look up a URI that isn't usable as a locator otherwise, like account URIs or email URIs. that's giving main character energy 👑
Status of This Memo 💅
this is an Internet Standards Track document, which means it's a product of the Internet Engineering Task Force (IETF) 🎀 It represents the consensus of the IETF community, got public review, and was approved for publication by the Internet Engineering Steering Group (IESG). if you want more on Internet Standards, check out Section 2 of RFC 5741 📚
for the current status, errata, and how to give feedback, go to 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 doc is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents (http://trustee.ietf.org/license-info) as in effect on the date of publication. please read these carefully, bestie, because they describe your rights and restrictions for 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 they're provided without warranty as described in the Simplified BSD License 💜
Table of Contents 🍓
here's the TOC exactly as it's written in the original 📋
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 ...................................271. Introduction ✨
okay so WebFinger is used to discover info about people or other entities on the Internet that are identified by a URI [6] 🔎 It does this with standard Hypertext Transfer Protocol (HTTP) [2] methods over a secure transport [12] 🔐 A WebFinger resource returns a JavaScript Object Notation (JSON) [5] object describing whatever entity was queried. That JSON object is called the JSON Resource Descriptor (JRD) 💅
for a person, the stuff WebFinger can find includes a personal profile address, an identity service, a telephone number, or a preferred avatar 🎀 For other entities, a WebFinger resource might return JRDs with link relations [8] 🖨️ this is how a client could learn things like a printer being able to print in color on A4 paper, the physical location of a server, or other static info 🌈
info from WebFinger might be for direct human consumption, like looking up someone's phone number 📱 or it might be used by systems to help with some operation, like facilitating a login to a web site by figuring out a user's identity service (with extra security mechanisms on top, obviously 🔒) The info is meant to be static in nature, so WebFinger is not intended to return dynamic stuff like the temperature of a CPU or the current toner level in a laser printer 🙈 not the vibe, bestie
WebFinger is designed to work across lots of applications 🦋 Applications that want to use WebFinger need to specify properties, titles, and link relation types that fit the application. they also need to define the right URI scheme to use for the query target ✨
you'll see how WebFinger is used in the examples in Section 3, and it's described more formally in Section 4 📚 Section 8 explains 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] 🌸 these are the official requirement words, so bestie, pay attention to them 👑
WebFinger makes heavy use of "link relations" 🔗 A link relation is an attribute-value pair where the attribute says what kind of relationship exists between the linked entity or resource and the info in the value 🦋 In Web Linking [4], the link relation is shown with an HTTP entity-header called "Link", where the "rel" attribute gives the type of relationship and the "href" attribute gives the info linked to the entity or resource 💖 In WebFinger, the same idea is shown with a JSON array of "links" objects instead. each member named "rel" gives the type of relationship, and each member named "href" gives the info linked to the entity or resource 🎀
now, WebFinger narrows the scope of link relations compared to Web Linking 🎯 the value of the "rel" member has to be either a single IANA-registered link relation type [8] or a URI [6] no other options, periodt 💅
all the URIs in this document follow the syntax from Section 3 of RFC 3986 [6] 🌐 Relative URIs, which follow the syntax 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 here should be simple enough to get without reading the formal specs of the applications 💕
3.1. Identity Provider Discovery for OpenID Connect 🔐
okay so imagine Carol wants to log in to a web site she visits using OpenID Connect [15] 🙋♀️ She gives the web site her OpenID Connect identifier, let's say carol@example.com 💌 The site then does a WebFinger query to look for the OpenID Connect provider. since the site only cares about one particular link relation, the WebFinger resource might use 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.comthe 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"
}
]
}so since the "rel" parameter only filters which link relations get returned, the other name/value pairs in the response, including any aliases or properties, would still be returned 🎀 Also, support for the "rel" parameter isn't guaranteed, so the client must not assume the "links" array will contain only the requested link relation 🙈 always double check, bestie 🫶
the "rel" parameter is just a filter, not a promise. if the server ignores it, you'll get every link relation back, so don't assume you only got the one you asked for 💀
✨ more parts coming, bestie, so stay tuned 🦋
3.2. Getting Author and Copyright Information for a Web Page 📚
Okay so picture an app that wants metadata about a web page, like who wrote it and what the copyright situation is 📝. The client can use WebFinger to send a query for that exact URL. Say the page of interest is http://blog.example.com/article/id/314. The client would send something like this:
GET /.well-known/webfinger?
resource=http%3A%2F%2Fblog.example.com%2Farticle%2Fid%2F314
HTTP/1.1
Host: blog.example.comAnd the server might reply like this 💌:
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"
}
}
]
}Look at that glow-up 🦋. The server sent back a list of aliases, properties, and links all tied to the subject URL. Each link is grouped by its link relation type. For the author link, you get a reference to the author's blog, plus a title for the blog in two languages (en-us and fr) 🌍. There's also a property saying the author is the editor of the blog. Iconic 👑.
Also, the server only returned two links in the "links" array here, but a server can return any number of links when it gets queried 💖.
4. WebFinger Protocol ✨
Okay bestie, here's the core of it 🧚. The WebFinger protocol is how you request info about an entity that's identified by a query target (a URI). The client can optionally name one or more link relation types it wants info about 💅.
A WebFinger request is an HTTPS request sent to a WebFinger resource. A WebFinger resource is a well-known URI [3] that uses the HTTPS scheme, built from the query target (required) and any link relation types (optional) 🎀. WebFinger resources MUST NOT be served with any other URI scheme (such as HTTP). Not even a little bit 🙅♀️.
Every WebFinger resource always comes with a query target, which is another URI that identifies the entity whose info you're after. GET requests to a WebFinger resource put the query target in the "resource" parameter of the query string. See Section 4.1 for the deets 🔍.
The host you send a WebFinger query to really matters 👀. If the query target has a "host" portion (Section 3.2.2 of RFC 3986), then the query SHOULD go to that same "host" portion, unless the client gets instructions through some out-of-band mechanism telling it to send the query somewhere else. If the query target doesn't have a "host" portion, then the client picks a host using whatever extra info it has 🧭.
The path component of a WebFinger URI MUST be the well-known path "/.well-known/webfinger". A WebFinger URI MUST also have a query component that encodes the query target and any optional link relation types, as described in Section 4.1 💜.
The WebFinger resource returns a JSON Resource Descriptor (JRD) as its representation, which conveys info about an entity on the Internet 🌐. And to make browser-based queries work, the Cross-Origin Resource Sharing (CORS) [7] specification gets used too 🫶.
4.1. Constructing the Query Component of the Request URI 🧩
Here's how you build the query part of your URI. A WebFinger URI MUST contain a query component (see Section 3.4 of RFC 3986). That query component MUST contain a "resource" parameter, and it MAY contain one or more "rel" parameters. The "resource" parameter MUST contain the query target (URI), and the "rel" parameters MUST contain encoded link relation types, following the encoding in this section 🍓.
The client does the following steps. First, each parameter value gets percent-encoded, as per Section 2.1 of RFC 3986. That encoding has to match the query production in Section 3.4 of that spec, with one extra rule: any "=" and "&" characters inside the parameter values also get percent-encoded 🙈. Next, the client builds the query string by joining the name of the first parameter, an equal sign ("="), and the percent-encoded value. For each parameter after that, the client adds an ampersand ("&"), then the next parameter's name, an equal sign, and its value. The client MUST NOT insert any spaces while building the string 🚫. And the order of the attribute-value pairs in the query component doesn't change how it's interpreted. Lowkey freeing 🌸.
4.2. Performing a WebFinger Query 🚀
A WebFinger client sends a query using the GET method to the well-known [3] resource identified by a URI whose path component is "/.well-known/webfinger" and whose query component MUST include the "resource" parameter exactly once, set to the value of the URI being looked up 🎯.
If the "resource" parameter is missing 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 the server has no info about, the server MUST indicate that it couldn't match the request, as per Section 10.4.5 of RFC 2616 🤷♀️.
Security check, bestie 🔐: a client MUST query the WebFinger resource using HTTPS only. If the client finds the resource has an invalid certificate, if the resource returns a 4xx or 5xx status code, or if the HTTPS connection can't be established for any reason, then the client MUST accept that the WebFinger query failed. It MUST NOT try to reissue the request over HTTP on a non-secure connection. Absolutely not 💀.
A WebFinger resource MUST return a JRD as its representation if the client doesn't explicitly ask for another supported format through the HTTP "Accept" header. The client MAY include the "Accept" header to say what representation it wants. Representations other than JRD might get defined in future specs ✨. And the WebFinger resource MUST silently ignore any requested representation it doesn't understand or support 🙃. The media type for the JSON Resource Descriptor (JRD) is "application/jrd+json" (see Section 10.2) 🎀.
The properties, titles, and link relation types a server returns in a JRD can be all over the place and super numerous 🌈. For example, the server might send back info about a person's blog, vCard [14], avatar, OpenID Connect provider, RSS or ATOM feed, and so on. And if the server has nothing to share, it might return a JRD with an empty "links" array, or with no "links" array at all 🫧.
A WebFinger resource MAY redirect the client. If it does, the redirect MUST only go to an "https" URI, and the client MUST do certificate validation again after being redirected 🔁. A WebFinger resource can also include cache validators in a response, so the client can make conditional requests, and/or expiration times, as per Section 13 of RFC 2616 ⏰.
4.3. The "rel" Parameter 🎀
When a client sends a request to a WebFinger resource, it MAY use the "rel" parameter to ask for just a subset of the info that would otherwise come back without it. When "rel" is used and accepted, only the link relation types matching the one in the "rel" parameter show up in the "links" array of the JRD. If the resource has no matching link relation types, the "links" array in the JRD will be either absent or empty. Everything else in the resource descriptor stays put, even when "rel" is used 💖.
The "rel" parameter MAY be included multiple times to request multiple link relation types 🌸.
The whole point of "rel" is to return a subset of "link relation objects" (see Section 4.4.4) that would otherwise be in the resource descriptor 🧁. Using it might cut processing on the client or server, and it might also save bandwidth when you're sending a partial resource descriptor, especially if there are tons of link relation values for one "resource" value 📉. Also, if a client asks for a link relation type the server has no info about, the server MAY return a JRD with an empty "links" array or no "links" array 🤍.
WebFinger resources SHOULD support the "rel" parameter 💅. If a resource doesn't support it, the resource MUST ignore the parameter and process the request as if no "rel" parameter values were there 🙌.
Here's an example that uses "rel" to ask for links of 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.comIn this example, the client asks for links of the types "http://webfinger.example/rel/profile-page" and "http://webfinger.example/rel/businesscard". The server then replies with something 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"
}
]
}See how the response only includes links of the types the client asked for, and only the ones the server had info on 🎯? The rest of the JRD is still there too, which is so clean ✨. Also notice that every link in the "links" array here uses HTTPS. That matters a lot if the data you get through WebFinger needs to stay secure 🔒🫶.
4.4. The JSON Resource Descriptor (JRD) 🧾✨
okay so the JSON Resource Descriptor (JRD) 💅 was first introduced in RFC 6415 [16] and it's based on the Extensible Resource Descriptor (XRD) format [17]. it's a JSON object with these four name/value pairs:
subjectaliasespropertieslinks
the subject member is a name/value pair whose value is a string. aliases is an array of strings. properties is an object full of name/value pairs whose values are strings, and links is an array of objects holding link relation info 🔗
when a client processes a JRD, it MUST ignore any unknown member and it must NOT treat an unknown member as an error 🙈 that's the vibe: unknown stuff just gets skipped, no drama.
we'll go through each of these members in more detail below 🦋
4.4.1. subject 🫶
the value of subject is a URI that identifies the entity the JRD describes.
the subject value returned by a WebFinger resource MAY differ from the resource parameter the client sent in its request 👀 this could happen when the subject's identity changes (like when a user moves their account to another service), or when the resource prefers to write URIs in canonical form.
the subject member SHOULD be present in the JRD 💖
4.4.2. aliases 🎀
the aliases array holds zero or more URI strings that identify the same entity as the subject URI.
the aliases array is OPTIONAL in the JRD ✨
4.4.3. properties 🌸
the properties object has zero or more name/value pairs. the names are URIs (called "property identifiers") and the values are strings or null. properties are how we pass extra info about the subject of the JRD 🧚 for example:
"properties" : { "http://webfinger.example/ns/name" : "Bob Smith" }the properties member is OPTIONAL in the JRD 💜
4.4.4. links 🔗💅
the links array can hold any number of member objects, and each one represents a link [4]. each link object can have these members:
reltypehreftitlesproperties
the rel and href members are strings. rel is the link's relation type and href is the target URI. the context of the link is the subject (see Section 4.4.1) 🫶
the type member is a string saying what the media type of the result should be once you dereference the link 🍓
the order of elements in the links array MAY be read as a preference order 👑 so if two or more link relations share the same rel value, the first one is the user's preferred link. ngl this is such a clean detail 😭
the links array is OPTIONAL in the JRD ✨
each member of the objects in the links array gets its own breakdown below. each object (a "link relation object") is totally independent from every other object in the array. any requirement to include a given member only applies to that one particular object 🦋
4.4.4.1. rel 💖
the rel value is a string that's either a URI or a registered relation type [8] (see RFC 5988 [4]). the rel value MUST contain exactly one URI or registered relation type. that URI or relation type tells you what kind of link relation it is 🔥
the other members in the object only make sense once you know the link relation type. sometimes the link relation has semantics that let the client query for other resources on the Internet 🌐 other times, the semantics let the client use the other members of the link relation object without fetching any extra 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 type value 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 href value is a string containing a URI that points to the target resource 🍓
the href member is OPTIONAL in the link relation object 🫶
4.4.4.4. titles 🌸
the titles object has zero or more name/value pairs. the names are a language tag [11] or the string "und". the string is human-readable and describes the link relation 📖 you can give more than one title for the link relation MAY for the benefit of users who use it. if you do, a language identifier SHOULD be used as the name. if the language is unknown or unspecified, the name is "und" 🌍
a JRD SHOULD NOT include more than one title with the same language tag (or "und") in the link relation object. the meaning is undefined if a link relation object has more than one title with the same language tag (or "und"), but this MUST NOT be treated as an error 🙃 a client MAY pick whichever title or titles it wants to use 💅
here's 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 💜
inside a link relation object, the properties object has zero or more name/value pairs. the names are URIs (called "property identifiers") and the values are strings or null. properties convey extra info about the link relation 🌟 for example:
"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) that names the query target (a URI) the client wants info about. WebFinger doesn't care what scheme that URI uses. 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 reachable from a web browser because of "Same-Origin" policies 🙈 the current best practice is to make resources available to browsers through Cross-Origin Resource Sharing (CORS) [7]. 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: *but defaulting to the least restrictive setting isn't always right 🚫 for example, a server on an intranet that serves sensitive company info SHOULD NOT allow CORS requests from any domain, because that could leak the sensitive info 😭 a server that wants to keep info away from external entities SHOULD use a more restrictive Access-Control-Allow-Origin header 🔒
6. Access Control 🔐
as with all web resources, accessing the WebFinger resource could require authentication. and if the client doesn't give the required credentials, the server might forbid access or give a different response than it would have if the client had authenticated 👀
a WebFinger resource MAY give different responses to different clients based on other factors, like whether the client is inside or outside a corporate network 🏢 for example, a query on the internal corporate network might return link relations to employee pictures, while those link relations might not be provided to external entities 📸
also, link relations in a WebFinger resource representation might point to web resources that have access restrictions. the corporate server example still applies: it might give both internal and external entities URIs to employee pictures, but if the request comes from outside the corporate network, the client might need more authentication to access the picture resources 🫣
what set of link relations a WebFinger resource gives each client, which resources need extra authentication, and which specific authentication mechanisms get used are all outside the scope of this document 🧠✨
7. Hosted WebFinger Services ☁️
as with most Internet services, a domain owner can use "hosted" WebFinger services 🌸 for example, a domain owner might control most of its domain but use a third-party hosting service for email. for email, mail exchange (MX) records identify the mail servers for a domain. an MX record points to the mail server that mail for the domain should be delivered to. to the sending server, it doesn't matter whether those MX records point to a server in the destination domain or in a different one 📬
a domain owner might also use a third party to provide WebFinger services on behalf of its users 🧚 just like a domain owner has to insert MX records into DNS to allow hosted email services, the domain owner has to redirect HTTP queries to its domain to allow 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 doesn't need to point to the well-known WebFinger location on the hosting provider's server 🎀
say example.com's WebFinger services are hosted by wf.example.net 💅 if a client sends a query for acct:alice@example.com like this:
GET /.well-known/webfinger?
resource=acct%3Aalice%40example.com HTTP/1.1
Host: example.comthe server might respond like this:
HTTP/1.1 307 Temporary Redirect
Access-Control-Allow-Origin: *
Location: https://wf.example.net/example.com/webfinger?
resource=acct%3Aalice%40example.comthen the client can follow the redirect and reissue the request to the URI in the Location header 🦋 and heads up: the server will put any required URI parameters in the Location header value, which could be different from the URI parameters the client originally used 👀💖
8. Definition of WebFinger Applications ✨
okay so this section is basically the "hey, if you're building an app on top of WebFinger, here's your homework" part 📝💅 this spec covers the query syntax, the JRD (JSON Resource Descriptor) you get back, security stuff, hosted services, and the HTTP status codes you might see. what it does NOT do is list every property or link relation type an app might use, or say what you should expect to get back for a specific URI or URI scheme 🙈 but all of that missing stuff still matters for interop, so it MUST be specified in the document for whatever app is using WebFinger, following the steps in this section 🔥
8.1. Specification of the URI Scheme and URI
any app that uses WebFinger MUST specify the URI scheme(s) it uses, plus what shapes the URIs can take where that makes sense 🦋 like if you're looking up a user's account on some domain, it makes sense to call out the "acct" URI scheme [18]. if you want the copyright info for a web page, you'd specify the web page URI (http or https) 🌸
the examples in Sections 3.1 and 3.2 show different URI schemes in action ✨ Section 3.1 uses WebFinger to grab info for OpenID Connect, and Section 3.2 uses it to find metadata about a web page, including author and copyright info 💖 each of these apps needs to be fully specified so everyone's on the same page (literally) 🫶
8.2. Host Resolution
okay so remember Section 4 said the host you send a WebFinger query to really matters 🎀 normally, WebFinger apps just follow the Section 4 procedures to send queries to the right place 🧚
BUT some URI schemes don't even have a host part, and sometimes an app shouldn't or can't use the host part of a URI at all 💀 in those cases, the application specification MUST clearly define how host resolution works, and that might include baking a "default" host into the client that queries get sent to 🔥
8.3. Specification of Properties
WebFinger has two kinds of properties 👑 there are subject-specific properties (the ones from Section 4.4.3 that describe the URI being queried) and link-specific properties (see Section 4.4.4.5) 💜 this part is about the subject-specific ones 🌈
apps that use subject-specific properties MUST define the URIs that identify those properties, along with the valid values 💅
check out this bit of JRD from the Section 3.2 example 👀
"properties" :
{
"http://blgx.example.net/ns/version" : "1.3",
"http://blgx.example.net/ns/ext" : null
}so two properties came back in that response 🍓 each one would be defined in some WebFinger app spec, and they could live in the same spec or in totally different ones 🦋 since the second option is totally possible, WebFinger clients should NOT assume that one property is related to another unless the app spec explicitly says so 🙈 no vibes-based assumptions, bestie 💀
8.4. Specification of Links
each link in a WebFinger response is made of a few pieces, and some are optional (check Section 4.4.4) 🌸 the WebFinger app spec MUST define each link and any values tied to it, like the link relation type ("rel"), the expected media type ("type"), properties, and titles 🎀
the target URI (the "href") usually doesn't get defined in the app spec if it's there at all 🧚 what you DO usually spell out is the URI scheme or any special quirks the URI has ✨ and if a link doesn't need an external reference, then ALL of the semantics for using that link MUST be defined in the app spec 🫶 those links might only rely on their properties or titles to get their meaning across 💖
8.5. One URI, Multiple Applications
this one's important, so be mindful 🍓 different WebFinger apps can use the same URI scheme, and effectively the same URI for totally different reasons 😭 that's fine tho, because every property identifier (see Sections 4.4.3 and 4.4.4.5) and link relation type gets uniquely defined for one specific app 🔥
also, when a client asks about a URI and gets back a bunch of property identifiers or link relation types, the response is just giving info about that URI without any particular meaning attached 🦋
how the client interprets that info SHOULD follow the app spec (or specs) the client actually implements 🌈
any syntactically valid properties or links the client gets that it doesn't fully understand SHOULD be ignored, and they SHOULD NOT make the client report an error 💅 no drama over stuff you don't recognize, periodt ✨
8.6. Registration of Link Relation Types and Properties
app specs MAY define a simple token as a link relation type for a link 🧚 if they do, that link relation type MUST be registered with IANA as described in Sections 10.3 📝
and any properties that get defined MUST be registered with IANA too, following Section 10.4 👑
9. Security Considerations 🔐
9.1. Transport-Related Issues
okay this part is serious, so let's get into it 🥺 this spec uses Cross-Origin Resource Sharing (CORS) [7], which means all of the security considerations for CORS also apply here 💀
using HTTPS is REQUIRED so info doesn't get changed in transit 🔥 it should be acknowledged that wherever a web server normally exists, there's a risk that a compromised network could swap out a WebFinger resource running on HTTPS for one that only runs over plain HTTP 😭 because of that, clients MUST NOT send queries over a non-secure connection 🚫
⚠️ clients MUST verify that the certificate on an HTTPS connection is valid (as defined in [12]), and they should only accept a response if that certificate checks out. no shortcuts, no excuses, bestie 💖
9.2. User Privacy Considerations
okay, so service providers and users need to know that once info is on the Internet, ANY user can get to it, and WebFinger makes it even easier to find 🦋 WebFinger is super useful for finding someone's avatar, blog, or other personal stuff 🌸 but users should also understand the risks 💜
systems or services that expose personal data through WebFinger MUST give users an interface to pick which data elements get exposed 🎀 for example, social networking sites might let users mark some data as "public" and then use that marking to decide what gets exposed through WebFinger ✨ so only what the user marked as public gets published 🫶 and users can take info back off WebFinger by removing that marking 🧚
WebFinger MUST NOT be used to provide any personal data unless the person whose info is being shared explicitly authorized the relevant service to publish it via WebFinger 🔥 putting your personal data inside an access-controlled or otherwise limited space on the Internet does NOT count as implicit permission to publish it via WebFinger 🙅♀️ not me thinking it does 😭
the privacy and security concerns here are worth repeating when it comes to personal data that could reveal a user's current context, like their location 📍 the whole power of WebFinger is that it gives you one place to find pointers to info about a person 🌈 but service providers and users should think about what kind of info they're sharing and remember it could be visible to the entire world 🌍 sharing location info could put someone in danger from anyone who wants to hurt them 💀 that's not a vibe 🥺
users should also be aware of how easily personal data they publish can get used in unintended ways 🍓 in one study about WebFinger-like services, Balduzzi et al. [20] took a big set of leaked email addresses and showed a bunch of privacy concerns, including the ability to cross-correlate the same user's accounts across multiple social networks 😳 the authors also describe possible mitigation strategies 🦋
easy access to user info through WebFinger was a design goal of the protocol, not a limitation 💅 if someone wants to limit access to info available through WebFinger (like WebFinger resources meant only for use inside a corporate network), the network administrator needs to take the necessary steps to limit access from outside the network 🔒 standard methods for securing web resources let administrators control access to resources that might return sensitive info ✨ and a server can be set up to require authentication and stop info from being disclosed to unauthorized entities 🫶
9.3. Abuse Potential 🚨
Okay bestie, service providers really need to be mindful of abuse with WebFinger 👀
As one example, someone could query a WebFinger server just to figure out whether a given URI is valid. With that query, the person may deduce that an email identifier is valid, for example. That could help spammers keep a current list of known email addresses and find new ones 💀
WebFinger could also be used to link a name or other personal data to an email address, which lets spammers write more convincing emails. This could be especially useful for 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 harvesting 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 read this as meaning that they don't 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 by people phishing for information about users 🪤 For example, imagine a mail client that is set up to automatically perform a WebFinger query on the sender of each received mail message. If a spammer sent an email with a unique identifier in the 'From' header, then when the WebFinger query ran, the spammer could link that request to a particular user's email address. That hands the spammer info like the user's IP address, the fact that the user just checked email, what kind of WebFinger client the user used, 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 way to make sure that the information a user provides is accurate. Likewise, neither the resource nor the client can be absolutely guaranteed that information hasn't been manipulated, either at the server or along the communication path between the client and server. Using HTTPS helps with some concerns about manipulation along the communication path, but it clearly can't fix situations where the resource provides incorrect information, whether because it was given false information or because of malicious behavior by the server administrator. As with any information service 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]. Here's the registration:
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, following the media type registration procedures defined in RFC 6838 [10]. The full registration is below, so take a good look at it 👀
Type name: application
Subtype name: jrd+json
Required parameters: N/A
Optional parameters: N/A
In particular, because RFC 4627 already defines the character
encoding for JSON, no "charset" parameter is used.
Encoding considerations: See RFC 6839, Section 3.1.
Security considerations:
The JSON Resource Descriptor (JRD) is a JavaScript Object Notation
(JSON) object. It is a text format that must be parsed by entities
that wish to utilize the format. Depending on the language and
mechanism used to parse a JSON object, it is possible for an
attacker to inject behavior into a running program. Therefore,
care must be taken to properly parse a received JRD to ensure that
only a valid JSON object is present and that no JavaScript or other
code is injected or executed unexpectedly.
Interoperability considerations:
This media type is a JavaScript Object Notation (JSON) object and
can be consumed by any software application that can consume JSON
objects.
Published specification: RFC 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
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/ABestie, the security considerations in that template are a must-read. A JRD is JSON, and JSON is text that has to be parsed, so parsing it carefully matters a lot 🔐
10.3. Registering Link Relation Types 🔗
RFC 5988 established a "Link Relation Types" registry, and WebFinger applications reuse it 🫶
Link relation types used by WebFinger applications are registered in the "Link Relation Types" registry under the procedures of Section 6.2.1 of RFC 5988. The "Notes" entry for the registration SHOULD indicate whether property values associated with the link relation type are registered in the "WebFinger Properties" registry, with a link to that registry ✨
10.4. Establishment of the "WebFinger Properties" Registry 🎀
WebFinger uses URIs to identify properties of a subject or link, along with 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 looks like this:
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. The "Link Type" contains the name of a link relation type that this property identifier is used with. If the property is a subject-specific property, this field is specified as "N/A". The "Description" is meant to explain what the property is for. The "Reference" field points to the specification that defines the registered property. The optional "Notes" field is for sharing any useful information about the property that might be valuable to implementers 🧚
10.4.2. The Registration Procedures 🗳️
The IETF has created a mailing list, webfinger@ietf.org, for public discussion of the WebFinger protocol and any applications that use it. Before registering a WebFinger property, discussion on the mailing list is strongly encouraged 💬 The IESG has appointed Designated Experts [13] who monitor the webfinger@ietf.org mailing list and review registrations.
A WebFinger property is registered with a Specification Required (see RFC 5226 [13]) after review by the Designated Experts. The review usually takes on the order of two to four weeks. However, the Designated Experts may approve a registration before a specification is published, once they are satisfied that such a specification will be published. When evaluating registration requests, the Designated Experts should make an effort to avoid registering two different properties that have the same meaning. If a proposed property is similar to one that's already defined, the Designated Experts should insist that enough text is included in the description or notes section of the template to clearly differentiate the new property from the 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 gives the community a chance to discuss and give input, and the Designated Experts may use that input to inform their review. Denials should include an explanation and, if applicable, suggestions for how to make the request successful if it's resubmitted 🫶
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. Ta-da! 💖
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 help 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
Okay bestie, these are the docs the RFC needs you to read first 📚💖 Skip them and the whole thing gets confusing fast 🙈
[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/>.
[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
These ones are the extra-credit reading 🧚✨ Not required, but they give you the full picture.
[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>.
Authors' Addresses 🎀
Meet the brilliant people behind the doc 👑 Slide into their inboxes if you have questions (respectfully, obviously 🫶)
Paul E. Jones 💅
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.comGonzalo Salgueiro 🦋
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.comMichael B. Jones 🌸
Michael B. Jones
Microsoft
EMail: mbj@microsoft.com
URI: http://self-issued.info/Joseph Smarr 🍓
Joseph Smarr
Google
EMail: jsmarr@google.com
URI: http://josephsmarr.com/That's the whole RFC, bestie! You made it 🌈💖✨
📦 where this page comes from
- ietf: rfc7033 2013-09
- 💖 girlified by claude-haiku-5-5 on : a language model's rewrite of the original, under its terms