Mastodon alias

※Note

I have since deleted my Mastodon account, so the endpoints and account URLs mentioned in this post are no longer live.

I’m not very active on social media, but I recently created a Mastodon account.

I’m still learning about the fediverse. So I was reading the docs a bit, and that’s when I stumbled upon WebFinger.

I had never heard of it before, but Mastodon uses WebFinger to figure out the location of an account. So it can, for example, resolve the account danillouz@mastodon.social to the location https://mastodon.social/@danillouz.

This location information is returned by a WebFinger endpoint, which made me wonder. Could my site, hosted on a custom domain, return this information as well, so that I could use my custom domain as an “alias” for my Mastodon handle? Turns out you can! But there are some caveats.

What’s WebFinger?

WebFinger is a protocol¹ that allows information about people or entities to be discovered over HTTP. It basically resolves some sort of URI identifier (like an email address, Mastodon account, or phone number) to a location (i.e. a URL), which can be retrieved by making a WebFinger request.

Making a WebFinger request

A WebFinger request is an HTTP GET request to a resource. The resource is a well-known URI with a query target. The query target identifies the entity to get the location for, which is specified via the ?resource= query parameter in the request. The endpoint then returns the location information as JSON.

For example, to get WebFinger information for the Mastodon account danillouz@mastodon.social², you need to make the following request:

GET /.well-known/webfinger?resource=acct:danillouz@mastodon.social
HOST: mastodon.social

200 OK
Content-Type: application/json

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

You can replace the Mastodon domain and username with your own, to get your information instead:

https://{MASTODON_DOMAIN}/.well-known/webfinger?resource=acct:{MASTODON_USERNAME}@{MASTODON_DOMAIN}

Why is WebFinger used?

On Mastodon, users have accounts on different servers, like mastodon.social or mas.to. So even though the handles danillouz@mastodon.social and danillouz@mas.to share the same “local” username danillouz, they are different accounts.

From what I understand, Mastodon’s internal implementation can’t just use the account handle. It requires the location (provided by WebFinger) to convert an account to a user on its server for things like mentions and search to work.

Adding a WebFinger endpoint

The RFC mentions that WebFinger information is static:

So if you can host some static JSON on your custom domain, you can add a WebFinger endpoint.

You can do this by:

1. Making a WebFinger request for your Mastodon account to get your WebFinger information.
2. Copy and paste the WebFinger JSON response from step 1 into a static file.
3. Returning the JSON³ from step 2 whenever an HTTP GET request is made to /.well-known/webfinger?resource=acct:{MASTODON_USERNAME}@{MASTODON_DOMAIN} on your custom domain.

With that in place, your custom domain can be used to find your Mastodon account.

Static file endpoint

I’m using Astro, so I just added a static file endpoint:

1
import type { APIRoute } from "astro"
2

3
const MASTODON_USERNAME = "danillouz"
4
const MASTODON_DOMAIN = "mastodon.social"
5

6
export const GET: APIRoute = async function ({ params, request }) {
7
  return new Response(
8
    JSON.stringify({
9
      subject: `acct:${MASTODON_USERNAME}@${MASTODON_DOMAIN}`,
10
      aliases: [
11
        `https://${MASTODON_DOMAIN}/@${MASTODON_USERNAME}`,
12
        `https://${MASTODON_DOMAIN}/users/${MASTODON_USERNAME}`,
13
      ],
14
      links: [
15
        {
16
          rel: "http://webfinger.net/rel/profile-page",
17
          type: "text/html",
18
          href: `https://${MASTODON_DOMAIN}/@${MASTODON_USERNAME}`,
19
        },
20
        {
21
          rel: "self",
22
          type: "application/activity+json",
23
          href: `https://${MASTODON_DOMAIN}/users/${MASTODON_USERNAME}`,
24
        },
25
        {
26
          rel: "http://ostatus.org/schema/1.0/subscribe",
27
          template: `https://${MASTODON_DOMAIN}/authorize_interaction?uri={uri}`,
28
        },
29
      ],
30
    }),
31
    { headers: { "Content-Type": "application/jrd+json" } },
32
  )
33
}

Redirecting WebFinger requests

Note that the Static file endpoint I added will only serve the WebFinger information when making the request:

GET /.well-known/webfinger.json
Host: www.danillouz.dev

But Mastodon will actually make the following request:

GET /.well-known/webfinger?resource=acct:danillouz@danillouz.dev
Host: www.danillouz.dev

Since I have just one Mastodon account, I chose to just ignore the ?resource= query parameter, and redirect all requests from /.well-known/webfinger to /.well-known/webfinger.json.

I’m using Vercel, which supports redirects. So I can achieve the desired redirect by adding the following rule:

1
{
2
  "redirects": [
3
    {
4
      "source": "/.well-known/webfinger",
5
      "destination": "/.well-known/webfinger.json"
6
    }
7
  ]
8
}

Using my custom domain as an alias

Now that my custom domain has a WebFinger endpoint, I can find my Mastodon account by using my custom domain!

For example, searching for hi@danillouz.dev will now give me a hit.

So how useful is this?

I’m not sure to be honest.

As mentioned before, Mastodon is a bit different: an account handle consists of two parts:

• The local username. For example danillouz.
• The server domain. For example mastodon.social.

The docs mention that you should include the server domain when sharing your handle with other people, because otherwise they won’t be able to find you easily:

So in theory, setting up an alias allows you to create a handle that does not change when migrating to a different Mastodon server. It might make your account easier to find if people know your custom domain.

It’s also pretty cool that with the alias you can have a Mastodon handle that includes your custom domain without needing to host your own Mastodon server. But practically speaking, searching for just the local username on different servers also works as far as I can tell.

When the docs mentioned that you should include the server domain when sharing your handle, I thought this meant that someone would always have to search for danillouz@mastodon.social on servers other than mastodon.social to find me. But this doesn’t appear to be the case. For example, I can search for danillouz on mast.to and it will find me.

So maybe aliasing your handle isn’t really a good idea?

I’m not sure if having an “extra” WebFinger endpoint can actually break stuff (can information become stale?). But there are some caveats when using your custom domain as an alias to be aware of.

Caveats

There might be more, but these are the ones I encountered.

Users need to be signed in to find you via the alias

I created my account on mastodon.social, and there I can find my account when searching for the alias without problems. But when I tried finding my account using the alias on a different server, I was surprised there was no result.

Turns out that when you’re not signed in to a server, the search API will not use WebFinger to resolve the handle!

This is what the search request looks like when I’m signed in:

GET /api/v2/search?q=hi@danillouz.dev&resolve=true
Host: mastodon.social

And this is what the same search request looks like when I’m signed out:

GET /api/v2/search?q=hi@danillouz.dev&resolve=false
Host: mastodon.social

The difference is that the query parameter resolve is set to true when signed in. But it is set to false when signed out.

Checking the v2 search API docs, we can see that resolve controls if a WebFinger lookup should happen:

The alias behaves like a “catch-all”

Since I’m Redirecting WebFinger requests, I’m returning the same response for all acct: queries. In my original testing, any⁴ local username could be provided together with my custom domain.

Mastodon validates an alias by resolving it to an ActivityPub actor and checking the actor’s canonical WebFinger address. Both addresses must resolve to the same actor. So a catch-all can make many usernames resolve to one account, but it does not create separate accounts for them.

For example, these all worked:

• hey@danillouz.dev
• 737@danillouz.dev
• lol@danillouz.dev

Resources

• Mastodon on your own domain without hosting a server
• Integrating Mastodon with Astro