Something I Learned Recently: WebFinger

Somewhat before my time in tech, back in the day of multi-user servers and very thin clients, there was a command called finger which would show you who else was logged in to the same computer. You could also get information about the user with finger user and even query users on other servers with finger user@server. As far as I know, this still works today, though I haven't heard anyone even mention it in about 15 years.

Recently I was looking into the structure of Mastodon and "Fediverse" federated communications, and came across a newer standard called WebFinger. This gets used by Mastodon when you search for a user - you have user@server all over again, though in the Mastodon UI this is usually @user@server, but the leading @ is for display only and gets dropped.

The way this works is described by a recent-ish standard - RFC 7033: WebFinger, which was published in 2013 (so only 10 years old). This can do more than just Mastodon user lookup, but that was how I found it.

Essentially, you hit a particular URL, and the server gives you information about the user - this time over HTTPS (just like everything else these days... who needs 65535 ports anymore when everything is HTTPS?).

To make a request, you query https://server/.well-known/webfinger?resource=<uri>, where <uri> is the URI of a thing that you want to find information about. This could be a http URI, a https URI, or a URI with some other scheme entirely.

In the case of Mastodon, it queries resource=acct:user@server which is a URI defined by yet another standard - RFC 7565: the 'acct' URI scheme, which describes user accounts.

There is also a rel query string parameter but Mastodon doesn't seem to use this. For more info, check the RFC as linked above.

So to put this all together, if you search for hello@yaakov.online on Mastodon, you'll end up querying https://yaakov.online/.well-known/webfinger?resource=acct:hello@yaakov.online.

In my case, I've set this up as HTTP 302 redirect to my actual Mastodon profile at cloudisland.nz. This is a cool hack you can do that is completely allowed by the standard:

A WebFinger resource MAY redirect the client

So if you go to your Mastodon instance and search for hello@yaakov.online, you'll end up with yaakov@cloudisland.nz in your search results instead.

If you want to try this yourself, this is the Nginx config I used:

location /.well-known/webfinger {
    if ( $arg_resource = "acct:hello@yaakov.online" ) {
        return 302 'https://cloudisland.nz/.well-known/webfinger/?resource=acct:yaakov@cloudisland.nz';
    }

    return 404;
}

The result that comes back looks like this:

{
  "subject": "acct:yaakov@cloudisland.nz",
  "aliases": [
    "https://cloudisland.nz/@yaakov",
    "https://cloudisland.nz/users/yaakov"
  ],
  "links": [
    {
      "rel": "http://webfinger.net/rel/profile-page",
      "type": "text/html",
      "href": "https://cloudisland.nz/@yaakov"
    },
    {
      "rel": "self",
      "type": "application/activity+json",
      "href": "https://cloudisland.nz/users/yaakov"
    },
    {
      "rel": "http://ostatus.org/schema/1.0/subscribe",
      "template": "https://cloudisland.nz/authorize_interaction?uri={uri}"
    }
  ]
}

This is just some JSON that describes my user.

The rel field describes each link and tells you what it is. In this case, the self link is the one that Mastodon uses, and application/activity+json describes it as an Activity Stream, part of the ActivityPub federation standard used by Mastodon.

And that's roughly all there is to it in this context.

There's now a HTTP-based version of the old finger command, and thanks to the recent Twitter acquisition and the many gTLDs available for funny Mastodon instance names, I suspect its now already more widely used than the original finger ever was.