WebFinger Explained: How the Open Web Discovers Identities Across Servers

The Problem WebFinger Solves

Imagine you're on a Mastodon instance and want to follow someone on a different server. You type in their handle — @alice@social.example.com — but how does your server actually find Alice's profile, inbox, and public key? It can't rely on a central directory. This is where WebFinger comes in.

WebFinger is a simple, standardized lookup protocol defined in RFC 7033. It gives any server a way to query a remote host and ask: "What do you know about this resource?" The response is a JSON document that points to further endpoints and metadata.

How a WebFinger Request Works

A WebFinger query is just an HTTPS GET request to a well-known URL:

GET /.well-known/webfinger?resource=acct:alice@social.example.com
Host: social.example.com

The server at social.example.com responds with a JRD (JSON Resource Descriptor) document:

{
  "subject": "acct:alice@social.example.com",
  "aliases": [
    "https://social.example.com/users/alice"
  ],
  "links": [
    {
      "rel": "self",
      "type": "application/activity+json",
      "href": "https://social.example.com/users/alice"
    },
    {
      "rel": "http://webfinger.net/rel/profile-page",
      "type": "text/html",
      "href": "https://social.example.com/@alice"
    }
  ]
}

The links array is the key part. Each entry uses a rel (relation type) to describe what kind of resource is being linked. The consuming server reads these links and knows which URL to fetch for the ActivityPub actor document, which for the HTML profile page, and so on.

The acct: URI Scheme

WebFinger commonly uses the acct: URI scheme (defined in RFC 7565) to represent user accounts. This is why Mastodon handles look like email addresses — user@host — they're designed to be resolvable via WebFinger using this scheme.

WebFinger isn't limited to user accounts, though. It can look up any resource by URI, including https:// URLs, which some implementations use to resolve information about web pages or services.

Where WebFinger Is Used Today

Platform / Protocol	How WebFinger Is Used
Mastodon / ActivityPub	Discovering actor endpoints and public keys for federation
OpenID Connect	Issuer discovery — finding the OpenID provider for a given user
Diaspora	User discovery across Diaspora pods
Matrix (partial)	Server capability discovery

Implementing WebFinger on Your Server

Adding WebFinger support to your application is straightforward:

1. Expose a route at /.well-known/webfinger that accepts a resource query parameter.
2. Parse the resource URI to identify the subject (e.g., extract the username from an acct: URI).
3. Look up the subject in your data store.
4. Return a valid JRD JSON response with a Content-Type: application/jrd+json header.
5. Respond with HTTP 404 if the resource is not found.

Most web frameworks can implement this in under 50 lines of code. The simplicity is intentional — WebFinger is designed to be a lightweight glue layer, not a comprehensive identity system.

WebFinger and Privacy Considerations

Because WebFinger makes user information publicly queryable, implementors should think carefully about what they expose. Some considerations:

• Only return information the user has consented to make public.
• Avoid leaking internal IDs or metadata in the JRD response.
• Consider rate-limiting the endpoint to prevent enumeration attacks.

WebFinger is one of the unsung heroes of the open web — a small protocol doing enormous work behind the scenes every time a federated social network makes a cross-server connection.