July 9, 2010

Weekend Project: Set Up Webfinger on Your Server(s)

Webfinger is a new Internet "identity discovery" mechanism, with which you can make personal or professional information about you or your organization discoverable through email addresses. Several well-known web service providers have implemented Webfinger for their customers' profiles, but if you manage your own mail server, all it takes to join the game is a little time.

Let Your Fingers Do the Walking

The name Webfinger is a reference to the old finger protocol (RFC 1288) from the 1990s. Those of us who are old enough to have had email addresses then remember how it worked -- an acquaintance from a mailing list might know only your email address; running finger
This e-mail address is being protected from spambots. You need JavaScript enabled to view it
at the command line would return a block of text from the example.com mail server.

Its contents might be domain-wide standard information, such as your first and last name and login state, but it could be anything else, via a customized file that you edited. Phone number, office hours, ASCII artwork, page after page of obscure Klingon poetry -- it was entirely up to the email account owner and often reflected his or her tastes as much as it provided concrete data.

Fast forward to today and finger is long dead, but the same general problem remains: given someone's email address, how do we reliably look up any related information? Today, however, we are not simply after a protocol that swaps out Monty Python quotes for Arrested Development quotes -- we want to enable access to serious bits like Web applications and online services.  Is there an online profile for this user? Is this someone already in our address book? How do I send this user an invitation to the conference call?

Some of these needs are purely people-oriented, simply designed to help us learn about our contacts -- an avatar image, a public GPG key, etc. But others are there to de-centralize the ever-growing world of social networking. For example, Webfinger can return a link to a PortableContacts version of your address book; thus when you log in to a new site, if you so authorize it, the site can retrieve your address book contacts and spare you the hassle of re-entering duplicate names and addresses.

The Webfinger standard was created by developers with backgrounds as varied as Google, Yahoo, Twitter, and OAuth. Like finger before it, the key principle is that a user's identity is associated with an email address (rather than, say, a URL) -- this is how people think, and getting it wrong was one of the design decisions that hampered OpenID. Webfinger made its debut in Google Buzz, and though Yahoo and other big-name email providers have enabled it, it is still largely unexploited by individuals and private companies and organizations.

As long as you have access to the web server from the same domain as your email address, though, setting it up is a breeze. We'll tackle the simple case first -- configuring a Webfinger response for your personal address -- before tackling the more complicated options.

The Simple Case: Your Personal Domain and Address

Let's assume you own the example.org domain, which hosts your personal email address, blog, and periodic releases of the odd open source project you manage in your spare time. When someone knows your email address, say
This e-mail address is being protected from spambots. You need JavaScript enabled to view it
, they can use a Webfinger client to query example.org about it. The request starts by asking for the URI http://example.org/.well-known/host-meta. The .well-known directory is an effort to future-proof such discovery techniques by placing this sort of standard info in a well-defined place, much like the "robots.txt" file, but in a directory to reduce clutter.

The host-meta file is XML, in the eXtensible Resource Descriptor (XRD) format. It needs to contain a link to the XRD namespace, and template link that explains where to look for the authoritative Webfinger entry for any email address.  For example:

<?xml version="1.0" encoding='UTF-8'?>
<XRD xmlns="http://docs.oasis-open.org/ns/xri/xrd-1.0" xmlns:hm="http://host-meta.net/xrd/1.0">
   <hm:Host xmlns="http://host-meta.net/xrd/1.0">example.org</hm:Host>
   <Link rel="lrdd" template="http://example.org/profiles/{uri}">
      <Title>Resource Descriptor</Title>

The "Link" element is a "Link-based Resource Descriptor Discovery" (LRDD) reference that tells the Webfinger client to look for your account information in the http://example.org/profiles/ directory. Currently there is a debate in the Webfinger community about the exact syntax of the URI; some want to use a "acct:" prefix; others claim it is unnecessary. For safety, you'd might as well create a file for yourself at both http://example.org/profiles/
This e-mail address is being protected from spambots. You need JavaScript enabled to view it
and http://example.org/profiles/acct:
This e-mail address is being protected from spambots. You need JavaScript enabled to view it

The contents of this file also need to be in XRD, but you get to decide what they are. The skeleton syntax includes the following:

<?xml version="1.0"?>
<XRD xmlns="http://docs.oasis-open.org/ns/xri/xrd-1.0">
This e-mail address is being protected from spambots. You need JavaScript enabled to view it
   <Alias>Pat Realname</Alias>

   <!-- various "Link" elements go here! -->


You add personal content as you see fit with Link elements. The Webfinger project wiki has a list of examples, such as:

<Link rel="describedby"

for a public profile page, or:

<Link rel="http://microformats.org/profile/hcard"

for an hCard file. Other examples include an iCalendar feed, OpenID provider, and status update stream. In each case, the "rel" value inside the Link element provides a link to the proper syntax for contents of the href.  Links that are destined for human consumption, like a profile page, may return simple HTML content.  Information types that would be requested by an application, such as PortableContacts, ATOM, or FOAF, could be returned in other formats, such as JSON, or whatever else the application requests.

This is also where security comes into play. You probably do not want your personal information served up to just anyone; a real PortableContacts server will not return address book entries without first going through the authorization handshake -- the Link element just tells the application where to request it.  On the other hand, if you want to fill your Webfinger entry with a list of your credit card numbers, your private GPG and SSH keyring, and a detailed, high-resolution scan of your birth certificate -- hey, that's on you.

The More Complex Case: Your Organizational Server

For your own "vanity" domain, those two XRD files are all that you need to create in order to correctly answer Webfinger requests. The hard part is deciding what information you want to make public.

On the other hand, if you are the administrator for your company or organization's mail server, you may get tired of generating the XRD files for every account, particularly as the organization grows. The good news is that options are beginning to appear to serve up Webfinger responses. Since the basics are just XML, you could easily store the user information in MySQL and return it for the LRDD-configured template with PHP, Perl, or your favorite language.

If you're already using a CMS on the site in question, though, things are even easier. Matthias Pfefferle has written a Wordpress plugin that serves up responses to Webfinger queries based on Wordpress's user accounts. By default it returns Links for avatars and profile pages, but could easily be adapted to serve other data as well.

Jeremy Carbaugh has written a Webfinger server for Django, as well as a separate XRD parser in Python.  There are also nascent Webfinger servers written in Ruby and in Perl.

Finally, however you choose to assemble Webfinger responses, as a sever administrator you need to give consideration to DNS. Requests from clients may or may not come to the fully-qualified domain name that you expect, particularly if your email address scheme utilizes subdomains. Like a lot of the other fine details of Webfinger, this part of the system is still undergoing debate and development; there is no specification yet for how to discover the location of domain's host-meta file. The project is currently recommending TXT records for their flexibility, but you should check the mailing list to see where the active discussion leads.

Extra Credit: Clients!

Of course, to test your own Webfinger implementation, you will also need a Webfinger client -- the simplest option is to use DeWitt Clinton's Web application. There, you can check not only your own Webfinger server, but see what current third-party providers like Google and Yahoo are serving up about you. Remember, part of the value of Webfinger is that it puts control over how much information is publicly disclosed back into the user's hands.

Probably more important to the future success of Webfinger and related services than server implementation is a good selection of clients. So far, apart from a few command-line clients, the only major consumer of Webfinger resources you are likely to encounter is Mozilla Labs' Contacts In the Browser extension. This Firefox add-on automatically tries to retrieve information for known email addresses via Webfinger, although thus far it does not do much with the results. So if the concept of Webfinger strikes a chord that you'd like to follow up on with more than a weekend's work, how about adding support for it to your favorite PIM or email app?  Thunderbird, Android or Maemo phones, various open source Webmail clients -- the field is wide open.

There has been a lot of talk over the past year about freeing users from the walled gardens of proprietary services like Facebook, but unfortunately most of the solutions (such as Diaspora) seem to be bent on re-building a similar service structure with different licensing terms. Webfinger, on the other hand, takes a completely different approach -- it puts the user in charge of his or her own data, without regard to any particular network or service. Doesn't that sound like more fun?

Click Here!