What Is WebFinger?

WebFinger (RFC 7033) is a simple, open protocol that allows a server to publish machine-readable information about a user or resource using just an email-like handle. It is the "phone book" of the federated web — the mechanism by which one server can look up another user's identity information using an address like user@example.com.

If you've ever searched for someone on Mastodon using their full handle like @alice@fosstodon.org, WebFinger is what made that lookup possible behind the scenes.

How WebFinger Works

When a client wants to discover information about alice@fosstodon.org, it sends an HTTPS GET request to a well-known URL on that domain:

GET /.well-known/webfinger?resource=acct:alice@fosstodon.org

The server responds with a JSON Resource Descriptor (JRD) document — a JSON object listing links and metadata about that account.

Example WebFinger Response

{
  "subject": "acct:alice@fosstodon.org",
  "links": [
    {
      "rel": "self",
      "type": "application/activity+json",
      "href": "https://fosstodon.org/users/alice"
    }
  ]
}

This tells the querying server: "Alice's full ActivityPub actor document lives at that URL." The querying server can then fetch that URL to get Alice's full profile, inbox, outbox, and public key.

Setting Up WebFinger on Your Own Server

If you are building a federated application or want your domain to participate in the Fediverse, you need to serve a WebFinger endpoint. Here's the basic approach:

  1. Create the route: Your web server must handle requests to /.well-known/webfinger.
  2. Parse the resource query parameter: Extract the username from acct:user@yourdomain.com.
  3. Return the JRD document: Respond with Content-Type: application/jrd+json.
  4. Serve over HTTPS: WebFinger requires HTTPS. No HTTP fallback is permitted.

Minimal Node.js / Express Example

app.get('/.well-known/webfinger', (req, res) => {
  const resource = req.query.resource;
  if (resource !== 'acct:alice@yourdomain.com') {
    return res.status(404).json({ error: 'Not found' });
  }
  res.json({
    subject: resource,
    links: [{
      rel: 'self',
      type: 'application/activity+json',
      href: 'https://yourdomain.com/users/alice'
    }]
  });
});

Common Use Cases

  • Mastodon-compatible profile discovery: Let others find your self-hosted ActivityPub actor using an @handle.
  • OpenID Connect discovery: Some identity providers use WebFinger to locate the OpenID configuration endpoint.
  • Custom domain aliasing: Use your own domain as your Fediverse identity even if your server is hosted elsewhere.

Testing Your WebFinger Endpoint

You can test any WebFinger endpoint manually using curl:

curl "https://yourdomain.com/.well-known/webfinger?resource=acct:alice@yourdomain.com"

Or use online WebFinger lookup tools to verify your response format is correct before connecting to federated networks.

WebFinger is a small but critical piece of the federated web's infrastructure. Implementing it correctly opens the door to interoperability with the entire Fediverse and ActivityPub ecosystem.