RFC 7033 / START HERE
WebFinger discovery, before the details
WebFinger: metadata discovery for a URI
WebFinger is a protocol name, not an acronym. It asks an HTTPS service for metadata about an identifier, such as an account URI. The response is a JSON Resource Descriptor (JRD), which can describe a subject and useful links.
The idea in one picture
Choose and encode a resource URI
Query the HTTPS discovery service
Interpret metadata and links carefully
A simplified picture of the idea; the chapters explain the actual mechanisms.
Why it exists
An application needs a predictable way to find metadata without guessing a profile URL or treating an account identifier as an email address. Discovery still needs privacy and trust decisions.
A familiar example
With fictional Carol’s permission, an app asks example.com about acct:carol@example.com and finds an author link. This lookup does not log the app in or prove Carol’s identity.
Helpful background
You can start here without reading another RFC. If these ideas are unfamiliar, these short introductions may help.
What you’ll learn next
Begin with chapter one, or choose a topic.
- Choose the target and encode each query valueWebFinger discovers relatively static metadata about a Uniform Resource Identifier (URI). A URI identifies something; it need not be a location you can fetch. The resource parameter identifies the subject of the question. The HTTPS endpoint is the service receiving it. An application can use an acct URI for an account without assuming it is an email address or a login.→
- Use HTTPS and distinguish responses from failuresThe client sends an HTTP GET request over HTTPS, which protects HTTP with Transport Layer Security (TLS). A successful response normally carries a JSON Resource Descriptor (JRD): a structured metadata document. Failure, empty links and redirection mean different things.→
- Read the descriptor’s fields and scopesJavaScript Object Notation (JSON) represents named values, arrays and objects. A JRD describes a subject and may contain aliases, subject properties and typed links. Applications interpret their vocabulary; finding a link does not automatically fetch or trust it.→
- Filter links without dropping subject metadataThe rel query asks for links of selected relation types. It is an optimization that the server might not implement, so a client must inspect the response instead of assuming it contains only requested links.→
- Separate publication, access and trustDiscovery can expose personal information and reader activity. Permission to publish data, browser access to a response and access to a linked resource are separate decisions. A successful query does not authenticate a person or make assertions accurate.→
This introduction explains RFC 7033 (2013). Read the original RFC ↗