WebFinger Profile: Resolving Handles to ActivityPub Actor URIs

By 4FreeForums Editors · Published October 31, 2026 · Sources linked below

In decentralized community networks, user accounts do not reside in a single shared database. A handle like @username@domain must be discovered, translated, and verified before one server can deliver messages or fetch profile resources from another. The technical profile below breaks down how platforms implement WebFinger to turn plain handles into actionable actor identifiers across the fediverse.

The Identity Resolution Challenge in Federated Spaces

On standalone discussion boards, identifying a user requires only a simple username check against a local table. Across federated boards, accounts can be hosted locally or on entirely disparate remote installations. As documented in the WebFinger - Mastodon documentation, a mention consisting of a username and a host name ensures that @user@example.com is never confused with @user@example.org. When no host name is appended to a mention, server software assumes the search targets a local account.

ActivityPub cannot transmit messages using plain text mentions alone. Inter-server communication demands an HTTPS URI so platforms can identify the actor's specific inbox and outbox. If an ActivityPub implementation attempts to interact without resolving handles via WebFinger, lookups fail because remote authors cannot be translated into local user records. Communities tracking federated setups, such as those covered in our Lemmy: At-a-Glance Profile of the Federated Discussion Platform, rely heavily on this resolution layer to keep distributed conversations connected.

Discovery Mechanics at the Well-Known Endpoint

The standard lookup mechanism relies on RFC 7033, which establishes a clear path for resolving links to a resource using a URI tied to a given host. Rather than requiring prior knowledge of a profile's direct web address, requesting servers query the standard path:

/.well-known/webfinger

The query transmits a resource parameter structured as an acct: URI in accordance with RFC 7565. For example, querying an account hosted on a remote server sends an HTTP request targeting that instance's well-known directory with the account identifier attached. In Mastodon's Ruby codebase, services such as app/services/activitypub/fetch_remote_actor_service.rb, app/services/resolve_account_service.rb, and app/lib/webfinger.rb handle these background lookups.

Payload Inspection: Discovering Actor Links and JSON Types

When an instance responds to a WebFinger query, it delivers a JSON document outlining the resource identity, associated aliases, and a collection of links. Discovering systems parse this payload to extract the canonical ActivityPub profile reference.

• Subject: Confirms the entity being queried, represented as an acct: URI matching the target profile.
• Aliases: Provides alternative direct web addresses, such as public profile pages or system paths for the account.
• Link Relations: Contains link objects where the relation (rel) is marked as self.
• Accepted Media Types: The discovery client checks for either application/activity+json or application/ld+json; profile="https://www.w3.org/ns/activitystreams".

The target address in the href field of that matching link delivers the precise actor URI. That URI becomes the formal id used when creating and addressing subsequent activities, such as sending a Note to a user on another instance.

Verification Workflows and Canonical Subject Checks

Resolving an address is not purely a matter of accepting the first link returned. Platform security depends on verifying that the remote actor actually maps back to the queried identity. The specification detailed in the WebFinger - Mastodon documentation outlines specific verification criteria:

1. The client checks that a subject field exists within the response payload.
2. The client confirms the links array supplies a relation marked self pointing to an acceptable ActivityStreams media type.
3. The system loads the target URI to confirm it resolves to a valid actor object.
4. The client checks the actor's preferredUsername alongside the host domain, generating a fresh acct: URI to run a reverse WebFinger check.

If the response subject matches the constructed resource, discovery succeeds. If the remote subject returns a different canonical account URI, the system initiates an extra WebFinger check against that canonical URI to guarantee both paths reference the exact same actor before committing the user to the local database. Similar verification baselines protect administrators running safety controls, such as those outlined in our Mastodon Moderation Tools: An At-a-Glance Profile.

FEP-2c59 Support and Explicit Handle Matching

Platform updates have introduced more precise methods for declaring identities across domain boundaries. As of version 4.6.0, Mastodon incorporates support for FEP-2c59. Under this mechanism, an ActivityPub actor can explicitly declare its own webfinger handle within its actor payload.

This explicit attribute takes priority over legacy fallbacks. Resolving systems verify the explicitly stated handle first, falling back to constructing an account string from preferredUsername only when the specialized attribute is malformed or omitted entirely.

Sources

WebFinger - Mastodon documentation

Published October 31, 2026. No affiliate links on this page. Facts come from the sources linked above; check them for updates.