Use HTTPS and distinguish responses from failures
02The 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.
Separate hosted sequence: origin returns 307 and Location: https://directory.example.net/tenant?resource=acct%3Acarol%40example.com. The client validates directory TLS and GETs that Location; the directory returns a 200 JRD. Lifelines show the same client receiving both responses. Do not blindly append the old query.
Source for this drawing: RFC 7033 · Read RFC section 4.2 ↗
New to this? Start hereA quick picture + helpful background
A message needs an address.
Think of a packet as a small addressed envelope. Devices pass it onward; transport protocols decide what delivery promises an application gets.
Helpful first, if these ideas are unfamiliar
These pictures are analogies to help you learn. The linked RFC explains the actual rules.
Terms in this drawing
Related RFCs and changes
“Updates” changes part of an earlier RFC. “Obsoletes” replaces it. This list shows selected related documents.
A failed secure query stays failed; a redirect needs a new HTTPS connection and certificate check.
- Clients MUST query using HTTPS. An invalid certificate, connection failure or 4xx/5xx response MUST be accepted as a failed query. The client MUST NOT retry with HTTP. HTTPS protects the connection; it does not prove that metadata is true.
- A missing or malformed resource MUST receive 400 Bad Request. If the service has no information about the requested resource, it MUST return 404 Not Found. A known subject with no matching links is a separate case.
- Unless another supported representation is explicitly requested through Accept, the service MUST return a JRD with media type application/jrd+json. Unsupported requested representations are silently ignored. A JRD may have empty or absent links.
- A server MAY redirect, but only to HTTPS; the client MUST validate the new certificate. For hosted service, the origin MUST return a redirect status and Location. The hosted path need not be /.well-known/webfinger. Location includes required parameters, which may differ from the original query. HTTP validators and expiry times MAY support caching (§4.2).
Arrows abbreviate TLS establishment except the explicit failure. Hosted delegation is an alternative deployment, not an extra actor in every lookup. The supplied /tenant path is illustrative. No live WebFinger queries are sent.
Read the RFC section ↗