Top Qs
Timeline
Chat
Perspective

WebFinger

Protocol for the discovery of information about people and things identified by a URI From Wikipedia, the free encyclopedia

WebFinger
Remove ads

WebFinger is a protocol specified by the Internet Engineering Task Force IETF in RFC 7033 that allows for discovery of information about people and things identified by a URI.[1] Information about a person might be discovered via an acct: URI, for example, which is a URI that looks like an email address.

Thumb
Logo of WebFinger

WebFinger is specified as the discovery protocol for OpenID Connect,[2] which is a protocol that allows one to more easily log in to various sites on the Internet.[3]

The WebFinger protocol is used by federated software, such as GNU social (via its use in OStatus), Diaspora,[4] or Mastodon,[5] to discover users on federated nodes and pods, as well as the remoteStorage protocol.[6] The WebFinger protocol does not specify the usage of "template" within the "links" section. That is an extension made by the former oStatus protocol that the Fediverse inherited from. The reasoning for expanding upon this later was justified by wanting to use a different key for a value that isn't an URL but a pattern to create one.[7]

As a historical note, the name "WebFinger" is derived from the old ARPANET Finger protocol, but it is a very different protocol designed for HTTP.[8]

The protocol payload is represented in JSON format with a MIME-Type of application/jrd+json.[9]

Remove ads

Technical overview

Summarize
Perspective

Basically the WebFinger is just a structured data format. The content of this structure depends entirely on the applications using it. While ensuring compatibility and extensibility.

Thumb

Basic example with profile page and business card

For this example we've two users Alice and Bob. Alice only knows the E-Mail address of bob bob@example.com. Bob previously setup WebFinger over at example.com.

  1. Alice opens the "Add contact" page of their E-Mail client and only enters Bobs E-Mail Address.
  2. The application then derives the WebFinger URL:
    • test
    • https://
    • + the domain part of the email address example.com
    • + /.well-known/webfinger?resource=
    • + the kind of schema the application is looking for, in this case we want to have account information, so it's acct
    • + followed by an URL-Encoded :-character, aka. %3A
    • + followed by the URL-Encoded value (the email address) we'd like to know more of bob%40example.com.
    • Resulting in the URL: https://example.com/.well-known/webfinger?resource=acct%3Abob%40example.com
  3. The application then makes a HTTP-Request towards it and follows all potential HTTP redirects according to the HTTP specification.
  4. When the application got a successful result it parses the obtained JSON looking at all of the obtained "properties" and "links" to find ones it understands ignoring all others. Like e.g. http://webfinger.net/rel/profile-page for populating the users homepage field or http://webfinger.net/rel/avatar for adding a picture to the contact details.

For this the client sends the following request:

GET /.well-known/webfinger?resource=acct%3Abob%40example.com HTTP/1.1
Host: example.com

Server response body:

{
	"subject": "acct:bob@example.com",
	"aliases": [
		"https://www.example.com/~bob/"
	],
	"properties": {
		"http://example.com/ns/role": "employee"
	},
	"links": [
		{
			"rel": "http://webfinger.net/rel/profile-page",
			"href": "https://www.example.com/~bob/"
		},
		{
			"rel": "http://webfinger.net/rel/avatar",
			"type": "image/png",
			"href": "https://www.example.com/~bob/avatar.png"
		}
	]
}


Remove ads

Usage within the Fediverse

Summarize
Perspective

Fediverse instances like e.g. Mastodon[5], Peertube, Misskey, ... can look up the server name of a specific usernames by sending a request to the WebFinger endpoint of the domain within their username (the part after the 2nd @-symbol). This also allows companies, influencers (anyone with their own DNS domain name) to point towards their official accounts within the Fediverse (aka. with ActivityPub) without needing to have their own instance running on their own domain and without all of the accounts having to be on the same instance (e.g. automatic accounts populated by the websites CRM, one for some primarily video content on a Peertube instance, and some personalised "employee" accounts on either one or multiple different Mastodon/Fediverse instances WITHOUT having to separate all of these to different (sub) domain names. Allowing to have a single easily readable and recognisable association with ones website within multiple usernames like e.g.: @authorname@bigcompany.tld, @news@bigcompany.tld, and @videotutorialsXYZ@bigcompany.tld instead of a confusing mix of e.g. @authorname@social.bigcompany.tld, @feed@feed.bigcompany.tld, @videotutorialsXYZ@videos.bigcompany.tld, and especially instead of @authorname@othercompany.tld. Without WebFinger when a company either chooses to outsource or team up with another company for operating these platforms on their behalf they normally not only make it trivial for others to impersonate them (because of having usernames that do not depend on their websites like e.g. @something@anothercompany.tld) but they also have to give up control over that account and its social capital to that specific company. The owner of anothercompany.tld is now in control of a companies entire social capital. Even worse should that company decide to shut down their servers for one reason or another the entire social capital could have to be rebuilt from scratch as nobody will be able to find the new company they moved to.

With WebFinger all of these problems can be avoided easily as e.g. @authorname@bigcompany.tld does not have to be served by https://bigcompany.tld/, nor does @otherauthorname@bigcompany.tld have to be on the same server anymore. If WebFinger is used a company gets enabled to use Mastodon.social today but once it either is no longer ideal or becomes inaccessible they can on their own accord - without any approval, vetoing, or even cooperation of the Mastodon gGmbH that owns and operates Mastodon.social, moved towards any other instance without loosing their social capital. Be it a self-hosted one, one spun-up and operated by a smal regional IT contractor, or similar. And all of this completely transparently and without any for their community members having to "refollow" or do anything. Basically making migrating ones social media platform operator as easy as the one for ones website. Thereby eliminating vendor lock-in (e.g. as seen on centralised "big-tech" platforms like Twitter, Facebook, TikTok, or Instagram) and allowing one to staying in control of their network relationships and social capital.

All at the little cost of having to purchase single DNS domain. And to stay in control of it (e.g. by being registered and listed as the rightful owner of that DNS domain name within the DNS registry). Note: In most cases this is neither anything new or unique to WebFinger and for most companies associated risks are also already being managed as loosing control over ones domain usually includes also loosing ones Website, E-Mail reachability, and thereby not "just" their social capital but their entire web presence including loosing out on income from e.g. ads, affiliate links, and/or sales. For WebFinger specifically one most ideally should also ensures to stay in control over their webspace as well. However compared to loosing ones entire DNS domain that's basically just an annoying inconvenience.

When WebFinger is solely being used for the Fediverse alone it can be seen as a more universal, versatile, and simpler alternative to the more walled off AT_Protocol controlled and solely used by Bluesky. As all that is needed for WebFinger to function for this is host a single static file per username with a fixed file name of webfinger?resource=acct%3A<<USERNAME>>%40example.com within the .well-known folder on ones website. This means when someone visits https://example.com/.well-known/webfinger?resource=acct%3A<<USERNAME>>%40example.com they need to get a small JSON-file (aka. a text file) with content similar to the example below).

Example for user @Mastodon@mastodon.social

WebFinger aware platforms and clients first tries to access the URL https://mastodon.social/.well-known/webfinger?resource=acct%3AMastodon%40mastodon.social by sending the HTTP-Request:

GET /.well-known/webfinger?resource=acct%3AMastodon%40mastodon.social HTTP/1.1
Host: mastodon.social

Then the server responds with:

More human readable and formatted:

{
   "subject":"acct:Mastodon@mastodon.social",
   "aliases":[
      "https://mastodon.social/@Mastodon",
      "https://mastodon.social/users/Mastodon"
   ],
   "links":[
      {
         "rel":"http://webfinger.net/rel/profile-page",
         "type":"text/html",
         "href":"https://mastodon.social/@Mastodon"
      },
      {
         "rel":"self",
         "type":"application/activity+json",
         "href":"https://mastodon.social/users/Mastodon"
      },
      {
         "rel":"http://ostatus.org/schema/1.0/subscribe",
         "template":"https://mastodon.social/authorize_interaction?uri={uri}"
      },
      {
         "rel":"http://webfinger.net/rel/avatar",
         "type":"image/png",
         "href":"https://files.mastodon.social/accounts/avatars/000/013/179/original/b4ceb19c9c54ec7e.png"
      }
   ]
}

Response in raw unformatted and unmodified including all headers for reference:

HTTP/1.1 200 OK
Connection: keep-alive
Content-Length: 628
referrer-policy: same-origin
x-runtime: 0.016346
x-frame-options: DENY
x-xss-protection: 0
content-type: application/jrd+json; charset=utf-8
etag: W/"1b12765828befeb0088ccfaa101276d5"
x-request-id: 6b75d72dfe8e62d97f15f6fce1095d7b
x-content-type-options: nosniff
via: 1.1 varnish, 1.1 varnish
content-security-policy: base-uri 'none'; default-src 'none'; frame-ancestors 'none'; font-src 'self' https://mastodon.social; img-src 'self' data: blob: https://mastodon.social https://files.mastodon.social; style-src 'self' https://mastodon.social 'nonce-VcuwDlT8Sp/BslgCzk90Aw=='; media-src 'self' data: https://mastodon.social https://files.mastodon.social; manifest-src 'self' https://mastodon.social; form-action 'self'; child-src 'self' blob: https://mastodon.social; worker-src 'self' blob: https://mastodon.social; connect-src 'self' data: blob: https://mastodon.social https://files.mastodon.social wss://streaming.mastodon.social; script-src 'self' https://mastodon.social 'wasm-unsafe-eval'; frame-src 'self' https:
cache-control: max-age=259200, public
Accept-Ranges: bytes
Age: 102821
Date: Sun, 12 Oct 2025 13:27:46 GMT
X-Served-By: cache-fra-eddf8230117-FRA, cache-fra-eddf8230158-FRA
X-Cache: MISS, HIT
X-Cache-Hits: 0, 0
X-Timer: S1760275667.945082,VS0,VE1
Vary: Origin
Strict-Transport-Security: max-age=31557600
alt-svc: h3=":443";ma=86400,h3-29=":443";ma=86400,h3-27=":443";ma=86400

{"subject":"acct:Mastodon@mastodon.social","aliases":["https://mastodon.social/@Mastodon","https://mastodon.social/users/Mastodon"],"links":[{"rel":"http://webfinger.net/rel/profile-page","type":"text/html","href":"https://mastodon.social/@Mastodon"},{"rel":"self","type":"application/activity+json","href":"https://mastodon.social/users/Mastodon"},{"rel":"http://ostatus.org/schema/1.0/subscribe","template":"https://mastodon.social/authorize_interaction?uri={uri}"},{"rel":"http://webfinger.net/rel/avatar","type":"image/png","href":"https://files.mastodon.social/accounts/avatars/000/013/179/original/b4ceb19c9c54ec7e.png"}]}
Remove ads

See also

References

External links

Loading related searches...

Wikiwand - on

Seamless Wikipedia browsing. On steroids.

Remove ads
Remove ads