There are a wide range of social media logins provided by Auth0 - including the usual suspects like Facebook, Twitter, WordPress, Discord, etc. Sadly, there's no support for Mastodon⁰.

All is not lost though. The Auth0 documentation says:

However, you can use Auth0’s Connections API to add any OAuth2 Authorization Server as an identity provider.

You can manually add a single Mastodon instance, but that doesn't work with the decentralised nature of the Fediverse. Instead, I've come up with a manual solution which works with any Mastodon server!

Background

Every Mastodon¹ server is independent. I have an account on mastodon.social you have an account on whatever.chaos. They are separate servers, albeit running similar software. A generic authenticator needs to work with all these servers. There's no point only allowing log ins from a single server.

Fortuitously, Mastodon allows app developers to automatically create new apps. A few simple lines of code and you will have an API key suitable for read-only access to that server. You can read how to instantly create Mastodon API keys or you can steal my PHP code.

User Experience

The user clicks the sign-in button on OpenBenches. They're taken to the Auth0 social login screen:

The user clicks on Mastodon. This is where Auth0's involvement ends!

The user is asked to provide the URl of their instance:

In the background, my server contacts the Mastodon instance and creates a read-only API key.

The user is asked to sign in to Mastodon.

The user is asked to authorise read-only access.

The user is now signed in and OpenBenches can retrieve their name, avatar image, and other useful information. Hurrah!

Auth0

Once you have created a service to generate API keys, it will need to run on a publicly accessible web server. For example https://example.com/mastodon_login.

Here's what you need to do within your Auth0 tennant:

• Authentication → Social → Create Connection
• At the bottom, choose "Create Custom".
• Choose "Authentication" only.
• Give your connection a name. This will be visible to users.
• "Authorization URL" and "Token URL" have the same value - the URl of your service.
• "Client ID" is only visible to you.
• "Client Secret" any random password; it won't be used for anything.
• Leave everything else in the default state.

It should look something like this:

Click the "Create" button and you're (almost) done.

Auth0 Icon

You will need to add a custom icon to the social integration. Annoyingly, there's no way to do it through the web interface, so follow that guide to use the command line.

Done!

I'll admit, this isn't the most straightforward thing to implement. Auth0 could make this easier - but it would still rely on users knowing the URl of their home instance.

That said, the Mastodon API is a delight to work with and the read-only permissions reduce risk for all parties.

Instead, you need to create an "OpenID Connect" provider. Here's how.

OpenSteetMap

As per the OAuth documentation you will need to:

• Register a new app at https://www.openstreetmap.org/oauth2/applications/
• Give it a name that users will recognise
• Give it a redirect of https://Your Auth0 Tenant.eu.auth0.com/login/callback
• Tick the box for "Sign in using OpenStreetMap"

Once created, you will need to securely save your Client ID and Client Secret.

Auth0

These options change frequently, so use this guide with care.

• Once you have logged in to your Auth0 Tennant, go to Authentication → Enterprise → OpenID Connect → Create Connection
• Provide the new connection with the Client ID and Client Secret
• Set the "scope" to be openid
• Set the OpenID Connect Discovery URL to be https://www.openstreetmap.org/.well-known/openid-configuration
• In the "Login Experience" tick the box for "Display connection as a button"
• Set the favicon to be https://blog.openstreetmap.org/wp-content/uploads/2022/07/osm-favicon.png or other suitable graphic

Next Steps

We're not quite done, sadly.

The details which OSM sends back to Auth0 are limited, so Auth0 is missing a few bits:

{
    "created_at": "2026-02-29T12:34:56.772Z",
    "identities": [
        {
            "user_id": "openstreetmap-openid|123456",
            "provider": "oidc",
            "connection": "openstreetmap-openid",
            "isSocial": false
        }
    ],
    "name": "",
    "nickname": "",
    "picture": "https://cdn.auth0.com/avatars/default.png",
    "preferred_username": "Terence Eden",
    "updated_at": "2026-02-04T12:01:33.772Z",
    "user_id": "oidc|openstreetmap-openid|123456",
    "last_ip": "12.34.56.78",
    "last_login": "2026-02-29T12:34:56.772Z",
    "logins_count": 1,
    "blocked_for": [],
    "guardian_authenticators": [],
    "passkeys": []
}

Annoyingly, Auth0 doesn't set a name or nickname - so you'll need to manually get the preferred_username, or create a "User Map":

{
  "mapping_mode": "use_map",
  "attributes": {
    "nickname": "${context.tokenset.preferred_username}",
    "name":     "${context.tokenset.preferred_username}"
  }
}

There's also no avatar image - only the default one.

Getting the Avatar Image

The OSM API has a method for getting user data.

For example, here's all my public data: https://api.openstreetmap.org/api/0.6/user/98672.json - thankfully no authorisation required!

{
  "user": {
    "id": 98672,
    "display_name": "Terence Eden",
    "img": {
      "href": "https://www.gravatar.com/avatar/52cb49a66755f31abf4df9a6549f0f9c.jpg?s=100&d=https%3A%2F%2Fapi.openstreetmap.org%2Fassets%2Favatar_large-54d681ddaf47c4181b05dbfae378dc0201b393bbad3ff0e68143c3d5f3880ace.png"
    }
  }
}

Alternatively, you can use the Unavatar service to get the image indirectly.

I hope that's helpful to someone!

There is no way to update the logo of a custom social connection on Auth0 without using the command line. On literally every other service I've used, there's a little box to upload a logo. But Okta have a funny idea of what developers want.

And, to make matters worse, their documentation contains an error! They don't listen to community requests or take bug reports, so I'm blogging in the hope that this is useful to you.

The Command

curl --request PATCH \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-H 'Authorization: Bearer eyJhb...ZEQ' \
  --url 'https://whatever.eu.auth0.com/api/v2/connections/con_qwerty123456' \
  --data ' ... '

You will also need to supply some JSON in the data parameter. I've formatted it to be easier to read than the garbage documentation. All of these fields are mandatory.

{
  "options": {
    "client_id": "your-app-id",
    "client_secret": "Shhhhhh!",
    "icon_url": "https://example.com/image.svg",
    "scripts": {
      "fetchUserProfile": "???"
    },
    "authorizationURL": "https://example.com/oauth2/authorize",
    "tokenURL": "https://example.com/oauth2/token",
    "scope": "auth"
  },
  "display_name": "Whatever"
}

OK, but how do you get all those values?

• Bearer token:
  • Create a management token
  • The only scope it needs is update:connections
• URl
  • This is your normal Auth0 domain name.
  • The Connection ID at the end can be found in the dashboard of your social connection
    
• Client ID & Secret
  • You set these in the social connection's dashboard.
• icon_url
  • Public link to an image. It can be an SVG.
• fetchUserProfile
  • Whatever code you want to run. If you don't want any, you can't leave it blank. So type in a couple of characters.
• authorizationURL and tokenURL
  • Wherever you want to redirect users to
• display_name
  • What you want to show to the user

This is such a load of bollocks! Is it really that hard for the Okta team to put an input field with "type the URl of your logo"?

For a traditional social-media site like Twitter or Facebook, you would create an OAuth app on the service that you want. But there are hundreds of Mastodon servers. So you need to create a new app for each one. That sounds hard, but it isn't. Well… not too hard.

Here's some code adapted from Infosec.press. It's all written using cURL on the command line - so you should be able to adapt it to your preferred programming language.

Register an app on the user's Mastodon instance

Let's assume the user has given you the name of their Mastodon server - example.social

You then send a request for an app to be created on example.social with your website's details. All it requests is the ability to read a user's details, nothing else.

curl -X POST \
 -F "client_name=Login to your_website.tld" \
 -F "redirect_uris=https://your_website.tld/oauth/mastodon?server=example.social&" \
 -F "scopes=read:accounts" \
 -F "website=https://your_website.tld" \
 -A "user-agent/0.1"
 https://example.social/api/v1/apps

You can set the User Agent to be anything suitable. Some servers won't work if it is omitted.

If the request was successful, example.social will send you this JSON in response:

{
  "id": "12345",
  "name": "Login to your_website.tld",
  "website": "https://your_website.tld",
  "scopes": [
    "read:accounts"
  ],
  "redirect_uris": [
    "https://your_website.tld/oauth/mastodon?server=example.social&"
  ],
  "vapid_key": "qwertyuiop-asdfghjkl-zxcvbnm",
  "redirect_uri": "https://your_website.tld/oauth/mastodon?server=example.social&",
  "client_id": "qw_asdfghjkl_zxcvbnm",
  "client_secret": "qwertyuiop1234567890"
}

Save the server's address, the client_id, and the client_secret. You will need all three later.

The user logs in to their Mastodon instance

You need to redirect the user to their server so they can log in. You need to construct a Mastodon URl using the data you received back. Don't forget to URl encode the redirect_uri.

For example, redirect the user to:

https://example.social/oauth/authorize
?client_id=qw_asdfghjkl_zxcvbnm
&scope=read:accounts
&redirect_uri=https://your_website.tld/oauth/mastodon%3Fserver=example.social%26
&response_type=code

When the user visits that URl they can then log in. If they're successful, they'll be redirected back to your server using your specified redirect URI:

https://your_website.tld/oauth/mastodon?server=example.social&code=qazwsxedcrfvtgbyhnujm

Get a Bearer token

Your website has received a GET request with the user's server name and an authorisation code. As per the Mastodon documentation, your app uses that code to request a Bearer token:

curl -X POST \
 -F "client_id=qw_asdfghjkl_zxcvbnm" \
 -F "client_secret=qwertyuiop1234567890" \
 -F "redirect_uri=https://your_website.tld/oauth/mastodon?server=example.social&" \
 -F "grant_type=authorization_code" \
 -F "code=qazwsxedcrfvtgbyhnujm" \
 -F "scope=read:accounts" \
 -A "user-agent/0.1"
 https://example.social/oauth/token

If that's worked, the user's server will return a Bearer token like this:

{
    "access_token": "abcdefg_123456",
    "token_type": "Bearer",
    "scope": "read:accounts",
    "created_at": 1732916685
}

Get the user's details

Finally(!) you can use that token to verify the user's credentials with the server:

curl \
 -H "Authorization: Bearer abcdefg_123456" \
 -A "user-agent/0.1"
 https://example.social/api/v1/accounts/verify_credentials

If that works, you'll get back all the user's details. Something like this:

{
    "id": "7112",
    "username": "Edent",
    "acct": "Edent",
    "display_name": "Terence Eden",
    "url": "https://mastodon.social/@Edent",
    "avatar": "https://files.mastodon.social/accounts/avatars/000/007/112/original/37df032a5951b96c.jpg",
...
}

Putting it all together

1. User providers their Mastodon instance's domain name
2. Your service looks up the domain name in its database
   • If there are no results, request to create a new app on the Mastodon instance and save the returned client_id and client_secret
3. Redirect the User to their Mastodon instance, using a URl which contains the client_id & callback URl
4. User logs in to their Mastodon instance
5. The User's Mastodon instance redirects the User to your service's callback URl which includes an the instance's domain name and User's authorisation code
6. Your service reads the User's domain name and authorisation code
7. Your service exchanges those details for a Bearer token
8. Your service uses the Bearer token to get the User's account details

Next steps?

This basic code works. For my next trick, can I integrate it into Auth0?

But there's a bug which is five years old. Auth0 doesn't show the screen name of Twitter users (e.g. @edent).

There was a workaround using their "rules" product. But rules are being removed next month and we all need to transition to "Actions". Why? Because fuck you, that's why. Auth0 have decoded that fixing bugs is less important than updating their logo yet again despite having updated it a couple of years ago.

Anyway, here's the new action you need:

exports.onExecutePostLogin = async (event, api) => {
  // Set the nickname to be the screen_name for Twitter connections
  if (event.connection.name === 'twitter' && event.user.screen_name) {
    api.idToken.setCustomClaim('nickname', event.user.screen_name);
  } 
};

Thanks to Gianfranco Parascandolo for helping me figure it out.

Using this firewall configuration, a user who visits /private is successfully taken through the login flow and I can then use $this->getUser() to see their details.

security:
    password_hashers:
        Symfony\Component\Security\Core\User\PasswordAuthenticatedUserInterface: 'auto'
    providers:
        users_in_memory: { memory: null }
        auth0_provider:
            id: Auth0\Symfony\Security\UserProvider
    firewalls:
        private:
            pattern: ^/private$
            context: user
            stateless: false
            provider: auth0_provider
            custom_authenticators:
                - auth0.authenticator
        main:
            lazy: true
            provider: users_in_memory

I want some unauthenticated pages to show user information. For example, if the user is logged in then /home should say "Hello $username". If not, it should say "Log in here".

The answer was annoyingly simple - but not documented by Symfony or Auth0.

Change the main firewall to not be lazy:

        main:
            lazy: false
            provider: users_in_memory

That then places all the Auth0 information into the $_SESSION global variable. You can retrieve the user's details with:

if ( isset( $_SESSION["_sf2_attributes"]["auth0_session"]["user"] ) ) {
    $user = $_SESSION["_sf2_attributes"]["auth0_session"]["user"];
    $username   = $user["nickname"];
    $avatar     = $user["picture"];
}

I'm sure there's a more official way to do this, but this quick and dirty hack seems to work pretty well.

It is all good advice. But I gently disagree with the slide which says:

Avoid side projects with user accounts If it has user accounts it’s not a side-project, it’s an unpaid job

I get the sentiment. Storing passwords securely is hard. Dealing with users changing their names is hard. Updating avatars is hard. GDPR is hard. It's just a lot of pain and suffering.

But I still have user accounts on one of my side projects while avoiding all those issues. Here's how it works on OpenBenches.

Use Auth0

The Auth0 service is a multi-vendor OAuth provider. That means I can offer a button which "login" which leads to this screen:

Auth0 has around 60 different social login providers. I picked the ones which best suited my users' demographic.

So the user hits "Sign In With Twitter⁰", gives Twitter their username, password, blood sample, and 2FA token. Twitter gives OpenBenches an authentication token with read only access.

This is important. Even if I were hacked and the tokens stolen, an attacker wouldn't be able to alter the user's account on a different platform.

But, as it is, I don't store the token. So it can't be stolen.

Only store the essentials

Here's the database which contains my user "accounts":

CREATE TABLE `users` (
  `userID` bigint(20) NOT NULL,
  `provider` varchar(64) COLLATE utf8mb4_unicode_ci NOT NULL,
  `providerID` varchar(64) COLLATE utf8mb4_unicode_ci NOT NULL,
  `name` varchar(128) COLLATE utf8mb4_unicode_ci NOT NULL
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci;

The userID is just an internally-used key which is incremented. I guess it could be a GUID or something.

The provider is a string like twitter or facebook or linkedin etc.

The providerID is the publicly available ID assigned by the social login service. Twitter gives everyone a number, LinkedIn gives everyone a random string, etc.

The name is the string that the provider calls you. My Twitter name is @edent and my LinkedIn name is Thought Leader Terence Eden.

That's it! I don't store any access tokens. I don't store a date of birth. I don't store any data unnecessary to running my project.

What about updates?

I don't store URls to avatar images. Instead, I use Cloudinary's Social Avatar service. That's usually as simple as calling res.cloudinary.com/demo/image/twitter/1330457336.jpg - I have to fuss around a little for GitHub and Facebook. So as soon as the user changes their avatar with their provider, it changes on my site.

Sometimes people change their names. Every time they log in to OpenBenches, I check to see if their name has changed - and update it if it has.

Most services don't let you change your internal ID. So that's fixed.

Where it goes wrong

It isn't all sunshine and roses though. Here are two things which might give you cause for concern.

What if a user wants to merge their accounts? On OpenBenches we sometimes get users who set up two accounts - and then want data from each of them merged. So far, my answer has just been "no".

What if a user wants to delete their account? Well, they can delete it with Twitter or whoever. If someone asked, I'd probably delete their username from the table. But it hasn't happened yet.

Should you do this?

I'm not your real dad. It isn't my job to tell you how to live your life or set up your side projects.

Generally speaking, user accounts are bad news. We resisted having them on OpenBenches for the longest time - people were anonymous. But we had lots of users who wanted a leader board so they could show off how many benches they had uploaded. The only way we could build that is with user accounts. So we added it. You can see the Leader Board in action.

Building side projects can be a bit lonely. So it is sometimes nice to develop a community of people who want to use your stuff.