My favorites | Sign in
Project Home Downloads Wiki Issues Source
Search
for
WebFingerProtocol  
the WebFinger protocol
Featured
Updated Jan 11, 2010 by joe.gregorio

WARNING: DRAFT

This is a draft, with updates based on various messages and blog posts along with various specs as they have matured over the past six months.

Protocol

The goal of the protocol is to get an XRD XML file describing how to find a user's public metadata from that user's email address or email address like identifier. The following describes the steps in the Webfinger protocol specifically, and ignores the options in the underlying protocols that don't apply (mostly the Link: header). The Requirements page gives some background on the requirements that went into the design of the WebFinger protocol.

Normalize and parse the email address

Given an email address, foo@example.com, turn it into a URI by prepending "acct:" if necessary. This lets machines digest it more easily. Grab the host of acct:foo@example.com -- in this case, example.com.

Get the domain's host-meta XRD file

First, you need to get the host's host-meta XRD file. In this case, example.com's. This is available at https://example.com/.well-known/host-meta. If there's no response to an SSL connection there, try http://example.com/.well-known/host-meta. Follow 3xx redirects; remember if anything wasn't retrieved via SSL connections with valid certificates.

Note that this needs to be done only the first time for each host-meta, after that you can cache the results using standard HTTP caching semantics.

Retrieving host-meta

GET /.well-known/host-meta HTTP/1.1
Host: example.com

The world has enough well-known URLs (/favicon.ico, /crossdomain.xml, /robots.txt), and we felt dirty adding another, so the /.well-known/ prefix (see draft-hammer-hostmeta-05) is the virtual directory where we hope future specs add their well-known URLs too.

Verify the host-meta XRD file's signature

If the host-meta file wasn't retrieved via SSL, check for an XRD signature.

If it's not signed and either it's ever been signed on prior retrievals, or it's a big company's site which you expect to use proper security, be afraid. Abort the process. Probably MITM. You can fall back to manual discovery (asking the user for info).

Also, once you verify the signature, double check that the XRD Host element matches your host name - e.g., example.com. This keeps example.com from stealing someone else's host-meta file and passing it off as their own.

Look for the XRD "lrdd" Link

Look for the Link element with rel="lrdd" and attribute template in the domain XRD file. Grab the value of the template attribute. This is a template to map from your acct: URI to the location of its metadata.

e.g.

<Link rel="lrdd" template="https://meta.example.org/?q={uri}"  type="application/xrd+xml" />

So given {uri} = acct:foo@example.com, this yields after swizzling:

https://meta.example.org/?q=acct%3Afoo%40example.com

(See draft-hammer-hostmeta-05)

Get user's XRD file

GET /?q=acct%3Afoo%40example.com HTTP/1.1
Host: meta.example.org

Follow 3xx etc. as normal. Again, if the SSL cert doesn't check out or if this isn't an https URL, remember secure=false. Also, verify that the XRD you get in the end has a Subject element that matches the acct: URI you started with:

<Subject>acct:foo@example.com</Subject>

Note: Need a big security section describing all the things that need checking.

You'll get back an XRD file containing the Link (s) that you're looking for. Look for the link(s) with the rel value you need. Those are the services you're trying to discover for acct:foo@example.com.

(See xrd-1.0-wd11.)

Appendix

See also Eran's implementing-webfinger blog post.

Respect and use DNS TTLs and HTTP caching/expiry headers. Also, XRD has an Expires element so honor that.

Comment by evan.pro...@gmail.com, May 6, 2009

Is it worth referencing the URI Template draft spec?

http://tools.ietf.org/html/draft-gregorio-uritemplate-03

It seems to have some traction.

Comment by bslatkin, Jun 1, 2009

How is this different than EAUT? http://eaut.org/

Comment by gerw...@gmail.com, Aug 14, 2009

I'd like to suggest the Link-Patterns include a provision for one-way address obfuscation, as some hosts may not be comfortable exposing "raw" email addresses. E.g. I might want to set up a domain to point to example.org, but don't want example.org to learn of valid addresses unless it's previously been informed.

My preference would be FOAF-style hashes of a mailto URI.

Comment by acran...@gmail.com, Aug 14, 2009

So the primary goal is an XRD recovery service?

What would the benefits of XRD be over vcards? A public vcard service would be more directly analogous to classic finger, so what are the design goals that XRD would deliver?

Comment by ptar...@gmail.com, Aug 15, 2009

Great idea.

As most of you guys are very familiar with openid, I'm sure you've already thought of this. But I'll bring it up anyways :

How about using YADIS for discovery on the root url for example.com? Big sites will understand the Accept header and small sites can just add the meta element.

Comment by csy...@gmail.com, Aug 15, 2009

I like this idea, but why not use JSON instead of XML for the XRD file?

Comment by egcros...@gmail.com, Aug 15, 2009

I feel that it would be a Right Thing if the Link-Pattern allowed substitution of the email's local part and domain part as separate elements. That would allow most common transformations to be done without the need to run any application on the server. For example:

Email: jsmith@example.com

Link-Pattern: http://{%local}.example.com/profile.xrd Result: http://jsmith.example.com/profile.xrd

Link-Pattern: http://profiles.example.com/{%local} Result: http://profiles.example.com/jsmith

Link-Pattern: http://www.{%domain}/~{%local}/ Result: http://www.example.com/~jsmith/

Also: encoding rules for the local part of the address need to be defined, as the local part is allowed to contain characters that are treated as special in the URLs.

Eugene

Comment by PaulHamm...@gmail.com, Aug 15, 2009

fred@example.com being webfingerable to http://example.com/@fred would have been much easier for machines and humans.

The 'pattern matching' could have been implemented with HTTP-301 (Moved Permanently)

Comment by hasse...@gmail.com, Aug 15, 2009

So you're basically trying to complicate things by doing id (email address) -> dns -> xrd -> contact data instead of doing .tel domain dns -> contact data ?

Also the id will change when the user's email changes, so the user will have to find an email provider that also provides the whole webfinger protocol.

Comment by hasse...@gmail.com, Aug 15, 2009

Following up on my earlier comment, whatever TLD you choose, just use NAPTRs! In a .tel domain, you could write something like: "E2U+x-xrd:http+x-lbl:my-personal-zrd" "!^.$!http://somedomain.com/myxrdfile.xml!"

Comment by mogsie.com, Aug 15, 2009

WRT Getting host-meta, couldn't it be linked from the root resource?

HEAD / HTTP/1.1
Host: example.org

200 OK
Link: <lesser-known/host-meta>; rel=host-meta
Comment by zeckal...@gmail.com, Aug 15, 2009

Vcard.

Comment by reed.und...@gmail.com, Aug 16, 2009

vCard + necessary extensions and /@local-name uri:

http://whereismybon.net/@reed

Comment by vin...@gmail.com, Aug 16, 2009

There is a lot of stuff in enterprise around web service descovery, UDDI etc..

was just thinking there may be some methods ofd doing stuff that could be usefull in there

Comment by ha...@interia.pl, Aug 17, 2009

I feel that the "well known location" of the XRD file should be just hard-wired to <http://example.com/~joe>. This is the default location of a user directory, which would allow most users to join the WebFinger? without the special configuration from web-services providers.

If we should use some sort of </.well-known/host-meta> or even <http://example.com/@joe>, we would have to wait for all the website administrators to reconfigure their servers.

Of course, lazy users will not publish proper finger data on their websites. The administrator could then perform XSLT transformation on the root index file of an user, adding neccessary <link rel='webfinger-query'/> tag.

Comment by earle%downlode.org@gtempaccount.com, Aug 19, 2009

Making sweeping statements about "the default location of a user directory" in this day and age seems unwise. Just a thought.

Comment by ajb...@gmail.com, Nov 30, 2009

Have you looked at Fingerpoint?

http://buzzword.org.uk/2009/fingerpoint/spec

It seems like this is much more in-line with current web architecture than the web finger protocol proposed here.

More commentary here:

http://blogs.sun.com/bblfish/entry/web_finger_proposals_overview

Comment by bobaman.goog@gmail.com, Dec 16, 2009

re: URI Templates, the draft is being heavily rewritten and is in flux.

Comment by mh.in.en...@gmail.com, Feb 12, 2010

That's really amazingly complicated.

I agree with the earlier post that just reading http://domain/@user seems equivalent but about a million times easier.

Comment by netler...@gmail.com, Feb 15, 2010

finger I can only in C on a UNIX-MASCHIN

Comment by reversep...@gmail.com, Feb 15, 2010

I've been working on a similar concept, albeit I think I am approaching it from a different direction http://wiki.github.com/brennannovak/WINK/ this is HOT idea right now, whoever, however we can dial it in, make it most extensible, and compatible...

Comment by butrus.b...@gmail.com, Apr 5, 2010

Another - simpliest - proposal: use a new HTTP method "FINGER" instead:

FINGER user HTTP /1.1
Host : example.com
Accept : text/plain

Or:

FINGER user HTTP /1.1
Host : example.com
Accept : application/xrd+xml

Or whatever content-type you want... The webserver could then return a document describing the user@example.com OR redirect to a webpage ("303 See Other" + Location: header) OR give an error (e.g. "406 Not Acceptable" for incompactible content-type)...

Comment by michele....@gmail.com, May 7, 2010

This is already similar to EAUT (e-mail address to URL translation, http://eaut.org), which was designed for OpenID but is not limited to it. I would not suggest a new HTTP method because HTTP GET should already have the necessary features.

It seems that WebFinger? could be a variant/extension to EAUT. One difference is that EAUT is http based, not https.

Comment by cat.on.j...@gmail.com, Jun 1, 2010

It seems there is billions of different way to do the same thing, and nobody agree with nobody, we should think about it...

Comment by macgir...@gmail.com, Jul 23, 2010

Seems I independently came up with a similar concept, and shaking my head in disbelief because - gosh darn, this is totally over-engineered.

Split off the LHS of the @, scrape the RHS. Find a <link rel="something" ...> relation for a template with a known name, containing the magical %s. Sprintf and you're done. Why are you making it so bloody difficult? Magic pathnames, XRD files - what have you guys been smoking?

Comment by jdrinkwater, Aug 11, 2010

For a single-user website with WebFinger? support, one would probably consider href="" instead of template="", as XRD supports that.

<Link rel="lrdd" href="https://example.org/me" type="application/xrd+xml" />

Does the protocol need to include this to encourage support? Is it enough to use template="" without uri templates?


Sign in to add a comment
Powered by Google Project Hosting