Mastodon is a free and open source, decentralized and distributed social networking service. It was created in 2016 as an alternative to centralized social media platforms like Twitter and Facebook.
One of the key features of Mastodon is the use of the WebFinger protocol, which allows users to discover and access information about other users on the Mastodon network. WebFinger is a simple HTTP-based protocol that allows a user to discover information about other users or resources on the Internet using their email address or other identifying information. The WebFinger protocol is important to Mastodon because it allows users to find and follow each other on the network, regardless of where they are hosted.
WebFinger uses a “known” route structure when calling a domain. You may be familiar with the robots.txt convention. We all agree that robots.txt will be placed in the top path of everyone’s domain.
The WebFinger protocol is a simple HTTP-based protocol that allows a user or search to discover information about other users or resources on the Internet using their email address or other identifying information. My first name is lastname.com, so… my personal WebFinger API endpoint is here https://www.hanselman.com/.well-known/webfinger
The idea is that…
-
A user sends a WebFinger request to a server, using the email address or other identifying information of the user or resource they are trying to discover.
-
The server searches its database for the requested information and returns a JSON object containing the information about the user or resource. This JSON object is called a “resource descriptor.”
-
The user’s client receives the resource descriptor and displays the information to the user.
The resource descriptor contains various types of information about the user or resource, such as their name, profile photo, and links to their social media accounts or other online resources. It may also include other information, such as the user’s public key, which can be used to establish a secure connection with the user.
there is great explainer here too. From that page:
When someone searches for you on Mastodon, your server will be queried for accounts using an endpoint similar to this:
GET https://${MASTODON_DOMAIN}/.well-known/webfinger?resource=acct:${MASTODON_USER}@${MASTODON_DOMAIN}
Note that Mastodon usernames start with @, so they are @[email protected]. Just as Twitter would be @[email protected], now I can be @[email protected]!
So maybe https://www.hanselman.com/.well-known/webfinger?resource=acct:[email protected]
mine comes back
{
"subject":"acct:[email protected]",
"aliases":
(
"https://hachyderm.io/@shanselman",
"https://hachyderm.io/users/shanselman"
),
"links":
(
{
"rel":"http://webfinger.net/rel/profile-page",
"type":"text/html",
"href":"https://hachyderm.io/@shanselman"
},
{
"rel":"self",
"type":"application/activity+json",
"href":"https://hachyderm.io/users/shanselman"
},
{
"rel":"http://ostatus.org/schema/1.0/subscribe",
"template":"https://hachyderm.io/authorize_interaction?uri={uri}"
}
)
}
This file should be returned as a mime type of application/jrd+json
My site is an ASP.NET Razor Pages site, so I did this in Startup.cs to map that known URL to a page/path that returns the necessary JSON.
services.AddRazorPages().AddRazorPagesOptions(options =>
{
options.Conventions.AddPageRoute("/robotstxt", "/Robots.Txt"); //i did this before, not needed
options.Conventions.AddPageRoute("/webfinger", "/.well-known/webfinger");
options.Conventions.AddPageRoute("/webfinger", "/.well-known/webfinger/{val?}");
});
then I made a webfinger.cshtml like this. Note that I have to escape the @@ sites twice because it’s Razor.
@page
@{
Layout = null;
this.Response.ContentType = "application/jrd+json";
}
{
"subject":"acct:[email protected]",
"aliases":
(
"https://hachyderm.io/@@shanselman",
"https://hachyderm.io/users/shanselman"
),
"links":
(
{
"rel":"http://webfinger.net/rel/profile-page",
"type":"text/html",
"href":"https://hachyderm.io/@@shanselman"
},
{
"rel":"self",
"type":"application/activity+json",
"href":"https://hachyderm.io/users/shanselman"
},
{
"rel":"http://ostatus.org/schema/1.0/subscribe",
"template":"https://hachyderm.io/authorize_interaction?uri={uri}"
}
)
}
This is a static answer, but if I were hosting pages for more than one person, I would like to take the URL with the user’s name and then map it to their aliases and return them correctly.
Even easier, you can use the webfinger response JSON file from your own Mastodon server and SAVE it as a static json file and copy it to your own server.
As long as your server returns the correct JSON of that known URL, it will work.
So this is my template https://hachyderm.io/.well-known/webfinger?resource=acct:[email protected] from where I am staying now.
If you want to get started with Mastodon, start here. https://github.com/joyeusenoelle/GuideToMastodon/ It looks like Twitter circa 2007, except it’s not owned by anyone and is based on web standards like ActivityPub.
I hope this helps!
About Scott
Scott Hanselman is a former professor, former chief financial architect, now speaker, consultant, father, diabetic, and Microsoft employee. He is a failed comedian, a pigtailer and a book author.
