Adding Mastodon discoverability by e-mail address

Through the “interesting” days when people started migrating to Mastodon, I found a quite interesting toot from one of its users, where he mentioned adding Mastodon discoverability for any domain using the WebFinger protocol.

I have been quite interested in how to implement this on my end, as I prefer people to discover me through my long-standing email address rather than a newly created username on a selected Mastodon server.

As my website is hosted on Netlify, I decided to check if I could implement this. Here’s how it goes.

For a better understanding of how Scott achieved this on his end, I referred to his original post¹. I read some more information about the WebFinger protocol on Wikipedia and then recalled John Mueller’s post from not so far back, where I found a conclusive solution for myself.

Before starting, I need to explain a couple of things.

As mentioned at the beginning, I would like people in the Mastodon network to be able to discover me by my email address rather than a specific username in the Mastodon network (currently @dariusz_wieckiewicz@mastodon.social).

I am not using my main domain for my website. My site is served on the subdomain dariusz of the domain wieckiewicz.org, which is also used to resolve my email address.

Mastodon uses the WebFinger protocol to discover users.

When using tools like Lookup WebFinger, located in the top-right part of the WebFinger website, you can type an email address to see how it resolves.

As you will see at the start, Lookup WebFinger will look into the domain that is part of your email, as follows:

GET https://wieckiewicz.org/.well-known/webfinger?resource=acct%3Adariusz%40wieckiewicz.org
Copy

As my website is static, using Hugo, I don’t have real server functionality to add dynamic responses. To handle this dynamic request for WebFinger, I decided to utilise what John mentioned in his Apache & co section – redirects.

Redirect method

I already have some redirects in place for my main domain. If you type wieckiewicz.org in your browser’s address bar, you will be 301 redirected to dariusz.wieckiewicz.org. I am doing this with a _redirects file located in the /static folder of my Hugo-based website.

https://wieckiewicz.org https://dariusz.wieckiewicz.org 301!
https://wieckiewicz.org/* https://dariusz.wieckiewicz.org/:splat                      301!
Copy

These two rules will not only redirect the main domain but also all links where the subdomain dariusz. is missing in the URL.

The original request sent by WebFinger looks as follows:

https://wieckiewicz.org/.well-known/webfinger?resource=acct:dariusz@wieckiewicz.org
Copy

As you may have noticed, symbols such as : and @ are replaced by their Unicode equivalents for compatibility reasons.

We need to keep this in mind when composing a redirect rule in our _redirects file to ensure that nothing unintentionally breaks.

Theoretically, a reference to .well-known/webfinger should be sufficient, but some sources, including John, also refer to Web Host Metadata (.well-known/host-meta) and Node Info (.well-known/nodeinfo), so I will include them as well.

Between the two rules mentioned above, I inserted the following:

https://wieckiewicz.org/.well-known/webfinger?resource=acct%3Adariusz%40wieckiewicz.org         https://mastodon.social/.well-known/webfinger?resource=acct%3Adariusz_wieckiewicz%40mastodon.social     301!

https://wieckiewicz.org/.well-known/host-meta?resource=acct%3Adariusz%40wieckiewicz.org         https://mastodon.social/.well-known/host-meta?resource=acct%3Adariusz_wieckiewicz%40mastodon.social     301!

https://wieckiewicz.org/.well-known/nodeinfo?resource=acct%3Adariusz%40wieckiewicz.org          https://mastodon.social/.well-known/nodeinfo?resource=acct%3Adariusz_wieckiewicz%40mastodon.social     301!
Copy

This may look a bit complicated, but if you have more users on your domain and these users use different servers in the fediverse, it will be easier to add them without restricting them to one instance (server).

Here you can see that when WebFinger requests a response from .well-known/webfinger?resource=acct:dariusz@wieckiewicz.org on my domain, it will be redirected to mastodon.social and my username there, dariusz_wieckiewicz@mastodon.social.

Once the redirect is active, the WebFinger Lookup service should return the response for the correct user on the mastodon.social server.

Remember, before applying any _redirects in production, check them using Netlify’s Playground!

Single file method

Using the redirect method is a bit ambitious. If you are looking for a quick and simple solution, Alex Guyot on Mastodon came up with a dirt simple solution by faking a WebFinger protocol response served from our domain.

The solution involves creating a webfinger file inside the .well-known folder (with a dot at the beginning).

By obtaining a response from the same file on the selected Mastodon server, we just need to copy, paste, and save it into our dummy file.

Using the following part of the path, we can get a JSON response from the Mastodon server:

/.well-known/webfinger?resource=acct:yourusername@mastodon.host
Copy

For example:

https://mastodon.social/.well-known/webfinger?resource=acct:dariusz_wieckiewicz@mastodon.social
Copy

This will give you a simple response:

{"subject":"acct:dariusz_wieckiewicz@mastodon.social","aliases":["https://mastodon.social/@dariusz_wieckiewicz","https://mastodon.social/users/dariusz_wieckiewicz"],"links":[{"rel":"http://webfinger.net/rel/profile-page","type":"text/html","href":"https://mastodon.social/@dariusz_wieckiewicz"},{"rel":"self","type":"application/activity+json","href":"https://mastodon.social/users/dariusz_wieckiewicz"},{"rel":"http://ostatus.org/schema/1.0/subscribe","template":"https://mastodon.social/authorize_interaction?uri={uri}"}]}

Copying, saving, and serving the file in /.well-known/webfinger will do the trick.

Dirty simple, yet it works well, so why not give it a try.

It’s time to check if other users can search for us (find us) in the Mastodon network using our original email address without knowing exactly on which server we created our account.

Try searching for me by typing my website address, but insert an @ symbol between my name (dariusz) and my surname-domain (wieckiewicz.org).

This gives us the flexibility to move between instances, and people who do not follow us can still find us using our original email address. Of course, this works as long as we keep our WebFinger file redirect up to date.

Why not try, find me, and say hello!