WebFinger

Dec 1, 2021 3 min read Bluesky

This blog contain just snips - a detailed explanation is available in the Reference links..

Background:

Twitter started the project called Bluesky with a goal to build a social web. As part of it, ActivityPub a decentralized social networking protocol was built - which uses WebFinger in the background.

What is WebFinger:

WebFinger is used to discover information about people or other entities on the Internet that are identified by a URI using standard Hypertext Transfer Protocol (HTTP) methods over a secure transport. A WebFinger resource returns a JavaScript Object Notation (JSON) object describing the entity that is queried.

Key Items to Note:

WebFinger protocol is used to request information about an entity identified by a query target (a URI).

A WebFinger request is an HTTPS request to a WebFinger resource.

A WebFinger resource is a well-known URI

A WebFinger resource is always given a query target, which is another URI that identifies the entity whose information is sought. GET requests to a WebFinger resource convey the query target in the “resource” parameter of the WebFinger URI’s query string

The path component of a WebFinger URI MUST be the well-known path "/.well-known/webfinger”.

The WebFinger resource returns a JSON Resource Descriptor (JRD) as the resource representation to convey information about an entity on the Internet

The use of HTTPS is REQUIRED to ensure that information is not modified during transit. Clients MUST verify that the certificate used on an HTTPS connection is valid and accept a response only if the certificate is valid.

The Registration Template:

Property Identifier:
Link Type:
Description:
Reference:
Notes: [optional] The “Property Identifier” must be a URI that identifies the property being registered.

Example:

Suppose Lia wishes to authenticate with a web site she visits using OpenID Connect. She would provide the web site with her OpenID Connect identifier, say lia@example.com. The visited web site would perform a WebFinger query looking for the OpenID Connect provider. Since the site is interested in only one particular link relation, the WebFinger resource might utilize the “rel” parameter

Request:

    GET /.well-known/webfinger?
    resource=acct%3Alia%40example.com&
    rel=http%3A%2F%2Fopenid.net%2Fspecs%2Fconnect%2F1.0%2Fissuer
    HTTP/1.1
    Host: example.com

Response:

      HTTP/1.1 200 OK
      Access-Control-Allow-Origin: *
      Content-Type: application/jrd+json
      {
        "subject" : "acct:lia@example.com",
        "links" :
        [
          {
            "rel" : "http://openid.net/specs/connect/1.0/issuer",
            "href" : "https://openid.example.com"
          }
        ]
      }

Since the “rel” parameter only serves to filter the link relations returned by the resource, other name/value pairs in the response, including any aliases or properties, would be reeturned. Also, since support for the “rel” parameter is not guaranteed, the client must not assume the “links” array will contain only the requested link relation.

Take ways:

The specification is rather simple as it uses JSON as the data model for all the communication. Almost, all languages provide support for handling JSON. Validation is still not part of the spec - So both validation and handling attack should be the responsiblity for the client.

References:

Tech Bluesky