Wiki · Concept · Last reviewed August 12, 2026

WebFinger

WebFinger is the IETF Proposed Standard for asking the domain associated with a URI for application-defined metadata. An HTTPS request returns a JSON Resource Descriptor containing claims and links; it does not prove control of the subject, authenticate a person or agent, grant consent, or authorize an action.

Category: Concept Published: June 25, 2026 Modified: August 12, 2026 Last reviewed: August 12, 2026 Tags: WebFinger, JRD, acct URI, discovery, social web, agents, privacy

Definition

WebFinger is an Internet Engineering Task Force Proposed Standard published as RFC 7033 in September 2013. It defines an HTTPS lookup for information about an entity identified by a URI. When the query target has a host, the client normally asks that host unless it has out-of-band instructions to use another one.

The response is a JSON Resource Descriptor, or JRD. Its optional subject, aliases, and properties members describe the resource; its links array points to application-defined related resources. WebFinger supplies the envelope and transport rules. The application using it defines which URI schemes, properties, and link relations mean anything.

The trust boundary is narrow. Valid TLS authenticates the server for the queried domain and protects the response in transit. It does not make the server's claims true, prove that a person controls the named account, bind an agent to a cryptographic key, or authorize a downstream operation. RFC 7033 expressly warns that a server or its administrator can provide false information.

How It Works

A client sends GET https://example.com/.well-known/webfinger with exactly one percent-encoded resource query parameter containing the target URI. It may repeat rel to ask for particular link relations. With no explicitly requested alternative format, the server returns JRD as application/jrd+json. A missing or malformed resource is a bad request; an unknown resource is not a blank identity claim.

For example, resolving acct:alice@social.example can begin with https://social.example/.well-known/webfinger?resource=acct%3Aalice%40social.example&rel=self. A matching JRD might name that account as its subject and provide a self link to an ActivityStreams actor URI. The client must still inspect every returned relation: RFC 7033 does not guarantee that a server supports the rel filter or returns only the requested links.

A JRD subject may differ from the requested URI when the server is expressing a canonical identifier or a move, while aliases assert other identifiers for the same entity. Those are server assertions, not independent verification. Syntactically valid members or relations the client does not understand should be ignored; their meaning must not be guessed.

The familiar acct: form comes from RFC 7565. It identifies an account at a service provider, including an account used by a bot or role, but it is not itself an email address, interaction protocol, or proof of account control. Removing acct: and seeing an email-shaped string does not establish that mail can be delivered there.

WebFinger requests are HTTPS-only. A failed TLS connection, invalid certificate, or error response must not be retried over HTTP. RFC 7033 permits redirects only to HTTPS and requires certificate validation again after redirect. Responses may use HTTP cache validators and expiration, so cache age is part of any identity-sensitive decision.

Current Deployment Context

Federated social handles. The W3C ActivityPub and WebFinger report documents the common conversion of user@domain into an acct: query and then a typed self link to an actor document. It is a 2024 Community Group Final Report, not a W3C Standard or Standards Track document. The ActivityPub Recommendation itself identifies objects and actors with HTTP(S) URIs and does not define WebFinger handle resolution.

Implementation requirements can be stronger than the base standards. As reviewed August 12, 2026, Mastodon's WebFinger documentation says WebFinger is required for full interoperability with Mastodon because it converts mention-style addresses into actor profile URIs. That is a Mastodon interoperability requirement, not a universal requirement imposed by ActivityPub.

OpenID provider discovery. OpenID Connect Discovery 1.0 incorporating errata set 2 defines an optional WebFinger flow for locating an end user's OpenID Provider, using the relation http://openid.net/specs/connect/1.0/issuer. A relying party that already knows the issuer out of band can skip this step. Provider metadata validation and token validation remain separate from the WebFinger lookup.

Agent Context

An automated client can use WebFinger before fetching an ActivityPub actor, locating an OpenID Connect issuer, or finding another application-defined endpoint. The safe interpretation is: this domain currently returned this pointer for this URI under this application profile. The response is untrusted discovery input, not a credential.

Following a returned href creates a second network and trust decision. For server-side agents, attacker-controlled hosts, redirects, and link targets can become server-side request-forgery paths. Enforce allowed schemes, block destinations that violate the deployment's public-versus-private network policy, re-check every redirect and resolved address, and bound response size, time, and redirect count. The ActivityPub Recommendation separately warns production software against localhost fetches and unsafe URI schemes; the OWASP SSRF prevention guidance explains the broader network-control problem.

An agent should preserve the input URI, normalization result, queried host, redirect chain, certificate result, response time, cache state, JRD subject and aliases, selected relation and target, application profile, and the later authorization decision. That evidence distinguishes what the remote domain asserted from what the local system chose to do.

Governance Risks

Publication and correlation. RFC 7033 requires a service exposing personal data to let people choose and remove what WebFinger publishes, and forbids publication without the person's explicit authorization. Public aliases and links can still make separate accounts easier to correlate, so “public” should not be treated as harmless or purpose-free.

Enumeration and contact abuse. Response differences can disclose whether an account exists, and returned actor or messaging endpoints can lower the cost of spam, phishing, harassment, and scraping. RFC 7033 recommends mitigations against overuse and harvesting, while acknowledging that rate limits cannot prevent all distributed collection.

Lookup privacy. The queried server sees a request and may infer the target, source address, timing, and client characteristics. RFC 7033 strongly advises clients not to make automatic lookups without user authorization. Batch resolution and background enrichment therefore need an explicit purpose, retention rule, and user-facing control.

Authority collapse. A correct JRD says what a domain asserts at a point in time. It does not establish consent to scrape, train, message, purchase, moderate, disclose, or impersonate. Handles may also be renamed or reassigned; the Social Web community report advises ActivityPub implementations to use actor IDs, not usernames, as stable references.

Governance Pattern

Source Discipline

RFC 7033 is the normative source for WebFinger transport, JRD processing, redirects, privacy requirements, and the protocol's security limits. RFC 7565 is authoritative only for the acct: URI scheme. Neither document defines ActivityPub actor-link semantics or proves an email-shaped account is mail-enabled.

The 2024 ActivityPub/WebFinger report documents a Social Web interoperability profile but explicitly is not a W3C Standard. Mastodon documentation describes one implementation's current compatibility requirements. OpenID Connect Discovery defines a different application profile and makes issuer discovery optional. Requirements from one profile should not be generalized to every WebFinger deployment.

Examples, observed conventions, and link-relation vocabularies should be labeled as such. A source that demonstrates successful discovery supports only the returned domain assertion; claims about identity, control, authorization, or safety require separate evidence from the relevant protocol and governance layer.

Spiralist Reading

Spiralism reads WebFinger as a small directory ritual: a name is spoken to a domain, and the domain replies with pointers.

That ritual is useful because it makes distributed identity less brittle. It is dangerous because discoverability becomes a substrate for profiling, automation, and social reach. The moral work is not the lookup itself. The moral work is deciding what power is allowed to follow from being found.

Sources

Return to Wiki