Implementing WebFinger

Hueniverse by Eran Hammer-Lahav

Webfinger2 The very nature of WebFinger is experimentation.

This means we are likely to see implementation before a fully baked specification. Since at the moment the various bits and pieces of the protocol are somewhat scattered across multiple drafts, this post will attempt to provide a quick implementer guide for those looking to jump right in and get something working.
Important Disclaimer: WebFinger and its dependencies are very much a work in progress. Not all the pieces have stable (or any) written specification with well defined behavior. This information is provided to early adopters who wish to play around with the protocol and provide feedback. Please check this post occasionally as it will change to reflect the most current information. Updates will be listed at the bottom of the page.

Server Side

Providers looking to support the WebFinger protocol need to create two resources, a host-meta file for the domain they wish to enable WebFinger on, and an endpoint (or endpoints) for the XRD documents describing their accounts. A third (and optional for providers) part of the protocol is going to provide DNS support for obtaining host-meta, which right now is proposed as an SRV record, but since it is still not fully baked will be skipped for now.

The first decision providers need to make is how they want to structure their accounts’ XRD endpoint (or endpoints). The main two styles are:

WebFinger defines three variables based on the input account identifier, the acct: URI:

  • id – the entire acct: URI without the ‘acct:’ prefix.
  • userinfo – the local part to the left of the ‘@’ character.
  • host – the domain name part to the right of the ‘@’ character.

For example, the identifier acct:joe@example.com breaks into:

  • id: joe@example.com
  • userinfo: joe
  • host: example.com

These three variables are used in a URI template to inform clients where they could find the account XRD for a given acct: URI. For example, the three templates that match the examples above are:

Once the provider decided on the location and style of its account XRD endpoints, it should publish that information to clients using its host-meta file. Host-meta is a general purpose, well-known location document that provides metadata information about the host. In this case, it provides information on how to find descriptors for accounts on the host.

The host-meta file is located at /.well-known/host-meta at the root of the domain it is about. For example:

http://example.com/.well-known/host-meta

It must contain the following (it may contain additional child elements, but at this point none are defined):

<?xml version=’1.0′ encoding=’UTF-8′?>
<XRD xmlns=’http://docs.oasis-open.org/ns/xri/xrd-1.0′&gt;
<Host>example.com</Host>
<Link>
<Rel>http://webfinger.info/rel/service</Rel&gt;
<URITemplate>http://example.com/webfinger?id={%id}</URITemplate>
</Link>
</XRD>

Providers must set the <Host> element to match their domain name and <URITemplate> to match their WebFinger endpoints structure. The template syntax is very simple. Variable names are placed in ‘{}’ and if the variable name is prefixed with a ‘%’, its value must be percent-encoded when expended. Template authors should make sure that their template results in a compliant URI that is properly encoded.

At this point the only thing left on the server side is to implement the WebFinger user XRD endpoints to return an XRD for each account at the chosen location. The account XRD must include at a minimum:

<?xml version=’1.0′ encoding=’UTF-8′?>
<XRD xmlns=’http://docs.oasis-open.org/ns/xri/xrd-1.0′&gt;
<Subject>acct:joe@example.com</Subject>
</XRD>

Which only says that this XRD describes the user account ‘joe@example.com’ and nothing else.The rest of the XRD content for accounts is still very much an open question, but a few ideas being experimented with are demonstrated in Brad Fitzpatrick’s XRD:

<?xml version=’1.0′ encoding=’UTF-8′?>
<XRD xmlns=’http://docs.oasis-open.org/ns/xri/xrd-1.0′&gt;
<Subject>acct:bradfitz@gmail.com</Subject>
<Alias>http://www.google.com/profiles/bradfitz</Alias&gt;
<Link>
<Rel>http://portablecontacts.net/spec/1.0</Rel&gt;
<URI>http://www-opensocial.googleusercontent.com/api/people/</URI&gt;
</Link>
<Link>
<Rel>http://webfinger.info/rel/profile-page</Rel&gt;
<Rel>http://microformats.org/profile/hcard</Rel&gt;
<Rel>http://gmpg.org/xfn/11</Rel&gt;
<Rel>describedby</Rel>
<MediaType>text/html</MediaType>
<URI>http://www.google.com/profiles/bradfitz</URI&gt;
</Link>
<Link>
<Rel>describedby</Rel>
<MediaType>text/x-foo</MediaType>
<URI>http://s2.googleusercontent.com/webfinger/?q=bradfitz%40gmail.com&fmt=foo</URI&gt;
</Link>
<Link>
<Rel>describedby</Rel>
<MediaType>application/rdf+xml</MediaType>
<URI>http://s2.googleusercontent.com/webfinger/?q=bradfitz%40gmail.com&fmt=foaf</URI&gt;
</Link>
</XRD>

The <Alias> element indicates an alternative URI the account might be known as. This would typically be an HTTP profile page or email address (prefixed with a mailto: URI scheme). The first link provides the location of the user’s Portable Contacts service. The second is a link to a profile page which has multiple relations to the account (it is its profile, hcard document, etc.). The third is a placeholder for another document describing the account using a made up format (with text records imitating the original finger protocol). The fourth is a link to FOAF information about the account.

This is all very experimental so please feel free to, well, experiment.

Client Side

The client’s first task is to obtain a normalized account identifier. This can be done by asking the end user to manually type in their identifier (usually their email address), or by providing them with a list of providers and a place to enter their username at that provider. The client can also encounter an account URI as a link or where URIs are usually found.

Either way, the client must end up with an account identifier structured as an ‘acct:userinfo@host‘ URI. Note that the acct: URI scheme should not be exposed or expected from end users. It should only be used internally to represent account identifiers. It can be used in documents as links to indicate ownership or a relationship to someone. Once that is obtained, the client performs the following steps:

  1. Parse the account URI and identify the host name.
  2. Obtain the host-meta file for the host at http://host/.well-known/host-meta using an HTTP GET request. The client must obey HTTP redirection (3xx) and should only use a document received with a success result code (2xx). This is where a DNS query will be added once it is figured out.
  3. Ensure that the host-meta has a matching <Host> element for the requested host. This will become more important when we add trust and signatures to the protocol.
  4. Find the first <Link> element that has a child <Rel> element with a value of http://webfinger.info/rel/service&rsquo;. Get the <URITemplate> element from that <Link>.
  5. Substitute the template variable names in ‘{}’ with their corresponding values. The three variable names defined are ‘id’, ‘userinfo’, and ‘host’. If a variable name is prefixed with a ‘%’, its value must be percent-encoded.
  6. Fetch the account XRD by making an HTTP GET request to the URI generated by the template.

At this point the client looks for whatever data it understands and can use in the XRD. See above for ideas on what can be found in account XRD documents.

Cet article a été publié dans Uncategorized. Ajoutez ce permalien à vos favoris.

Laisser un commentaire

Entrez vos coordonnées ci-dessous ou cliquez sur une icône pour vous connecter:

Logo WordPress.com

Vous commentez à l'aide de votre compte WordPress.com. Déconnexion / Changer )

Image Twitter

Vous commentez à l'aide de votre compte Twitter. Déconnexion / Changer )

Photo Facebook

Vous commentez à l'aide de votre compte Facebook. Déconnexion / Changer )

Photo Google+

Vous commentez à l'aide de votre compte Google+. Déconnexion / Changer )

Connexion à %s