WebFinger
Translate `user@domain` mentions to actor profile URIs.
What is WebFinger, and why is it used?
On Mastodon, user profiles can be hosted either locally on the same website as yours, or remotely on a completely different website. The same username may be used on a different domain. Therefore, a Mastodon user’s full mention consists of both the username and the domain, in the form @username@domain
. In practical terms, @user@example.com
is not the same as @user@example.org
. If the domain is not included, Mastodon will try to find a local user named @username
. However, in order to deliver to someone over ActivityPub, the @username@domain
mention is not enough – mentions must be translated to an HTTPS URI first, so that the remote actor’s inbox and outbox can be found.
Enter WebFinger. WebFinger as described in RFC 7033 is a spec that defines a method for resolving links to a resource, given only a URI on a particular server. This allows anyone to look up where a resource is located without having to know its exact location beforehand; for example, by email or phone number. This lookup is directed at the endpoint /.well-known/webfinger
, and a resource
query parameter is passed along with the lookup. The resource URI used with Mastodon is the acct:
URI as described in RFC 7565, with the username of a profile that is hosted on a particular domain.
username@domain
address, but Mastodon’s internal logic depends almost completely on acct
: URIs or username@domain
representations. Searching for any objects or profiles from an ActivityPub implementation without WebFinger will fail because the author cannot be converted to a user in the local database.Sample WebFinger flow
Suppose we want to lookup the user @Gargron
hosted on the mastodon.social
website.
Just make a request to that domain’s /.well-known/webfinger
endpoint, with the resource
query parameter set to an acct:
URI.
You can parse this JSON response to find a link with your desired type. For ActivityPub id
, we are interested in finding application/activity+json
specifically.
This way, we have translated @Gargron@mastodon.social
to https://mastodon.social/users/Gargron
and we can now interact over ActivityPub by referring to this URI as id
where appropriate.
Note in the above example that social.example
does not use the same URI structure as Mastodon. Thus, we cannot guess the actor id
given only the username and domain. However, if social.example
supports WebFinger, then we can get this id
by requesting https://social.example/.well-known/webfinger?resource=acct:username@social.example
and parsing the response for a link with the application/ld+json; profile="https://www.w3.org/ns/activitystreams"
or application/activity+json
type. This link should also have the link relation rel="self"
.
Mastodon’s requirements for WebFinger
When given an account in the form username@domain
or @username@domain
, Mastodon will do the following:
- Construct an
acct:
URI using that username and domain - Make a WebFinger request for that
resource
Using that WebFinger response, Mastodon will check the following:
- The
subject
is present - The
links
array contains a link withrel
ofself
andtype
of eitherapplication/ld+json; profile="https://www.w3.org/ns/activitystreams"
orapplication/activity+json
- The
href
for this link resolves to an ActivityPub actor
- The
Using that ActivityPub actor representation (which may be provided directly, without the initial WebFinger request), Mastodon will do the following:
- Take
preferredUsername
and the hostname of the actor’s server - Construct an
acct:
URI using that username and domain - Make a Webfinger request for that
resource
If the subject
matches the resource
, then the process stops here. Otherwise, if the subject
contains a different canonical account URI, then Mastodon will perform an additional Webfinger request for that canonical account URI in order to ensure that this new resource
links to the same ActivityPub actor with the same criteria being checked.
In other words, the following cases are valid:
- Asking
example.com
for the resourceacct:alice@example.com
yields a link to an actor on the domainexample.com
with apreferredUsername
ofalice
, and thesubject
matches the requested resourceacct:alice@example.com
- Asking
example.com
for the resourceacct:alice@example.com
yields a link to an actor on the domainap.example.com
with apreferredUsername
ofalice
- …then, asking
ap.example.com
for the resourceacct:alice@ap.example.com
yields asubject
ofacct:alice@example.com
and a link to the same actor
- …then, asking
See also
app/services/activitypub/fetch_remote_actor_service.rb app/services/resolve_account_service.rb app/lib/webfinger.rbLast updated February 6, 2023 路 Improve this page