Federated Identity Resolution: A WebFinger and HTTPS Glossary
Connecting independent community platforms requires standard protocols so servers can locate accounts, profile metadata, and verification endpoints across domain boundaries. The primary standard governing this lookup pattern is WebFinger, which defines how an HTTPS endpoint discovers static metadata about accounts or web entities without requiring prior direct database access. For administrators deploying software with decentralized connections, such as setups reviewed in our Lemmy platform profile, understanding the core components of identity resolution is essential for configuring servers and troubleshooting request failures. Below is a reference glossary covering the core protocol specifications defined in RFC 7033.
Endpoint Architecture and Well-Known Paths
Resolving an identity begins by querying a standardized path on the target server. Because different community tools structure internal routing in distinct ways, network clients rely on an agreed uniform endpoint rather than guessing application-specific routes.
- /.well-known/webfinger: The mandatory HTTP path component where WebFinger requests must be directed. Every compliant WebFinger URI must route through this path on the destination host.
- Query Target: The identifier whose information is sought by the client. It is encoded as a Uniform Resource Identifier (URI), such as an account scheme URI (like
acct:carol@example.com) or a standard web page URL. Relative URIs are explicitly not permitted. - Target Host: The destination server receiving the resolution request. If the query target URI includes a host component, the client should send the request directly to that host, unless configured with out-of-band routing directions.
WebFinger Query Parameters and Filtering
Clients construct a resolution request using standard HTTPS GET queries. Two query parameters dictate how the server resolves the entity and how much link metadata it returns in response:
- resource: The required query parameter conveying the query target URI. A WebFinger request URI must contain a query component with this parameter included.
- rel: An optional parameter used to filter the returned link relations. A client can provide one or more
relparameters to specify the exact relationship types it desires, such as discovering an OpenID Connect issuer. Because server filtering support is not guaranteed, clients must be prepared to handle responses that still include unfiltered links.
JSON Resource Descriptor (JRD) Top-Level Objects
When an endpoint successfully processes a resolution request, it returns a JavaScript Object Notation payload known as a JSON Resource Descriptor (JRD). Served under the media type application/jrd+json, this descriptor contains structured metadata about the queried entity:
- subject: A top-level string indicating the target entity for which the descriptor provides information. This value corresponds to the queried URI.
- aliases: An optional array of alternative URI strings that identify the same entity as the subject.
- properties: A top-level JSON object containing static name-value pairs that describe attributes of the subject, such as version identifiers or role classifications. WebFinger is designed strictly for static information and is not intended to report dynamic server states.
Links Arrays and Link Relation Attributes
The core utility of resolving identities is discovering external service endpoints, public profiles, and cryptographic handles. WebFinger represents these connections inside a structured links collection:
- links: A top-level array of link objects. Each entry describes a relationship between the subject and an external resource or service.
- rel (inside a link object): A member specifying the relationship type. Under RFC 7033, this value must be either a URI or a single link relation type registered with the Internet Assigned Numbers Authority (IANA).
- href: The target URI providing the linked service or information specified by the relationship.
- titles: An optional member inside a link object that provides human-readable labels for the link, formatted as language maps with language codes pointing to descriptive titles.
Transport Enforcement and Cross-Origin Rules
Because identity queries often expose identity mappings or handle sensitive authentication paths, strict transport rules apply to protect community members from manipulation:
- HTTPS Mandatory Scheme: WebFinger resources must be requested and served exclusively over secure HTTPS transport. Serving WebFinger over plain HTTP is forbidden by the specification. Implementing appropriate transport encryption is also covered in our forum admin security steps.
- Access-Control-Allow-Origin: *: A required Cross-Origin Resource Sharing (CORS) header returned by WebFinger endpoints. This configuration permits browser-based web applications running on different domains to issue direct queries and read the resulting JRD payload.
Sources
Published October 31, 2026. No affiliate links on this page. Facts come from the sources linked above; check them for updates.