Setting up OIDC for Mastodon with Pocket ID

Today I wanted to experiment with setting up OIDC (specifically Pocket ID) for my Mastodon instance. Annoyingly, there is very little documentation about this, but here is what I gathered.

OIDC provider setup

Now, this setup will vary slightly depending on the OIDC provider you are using. I’m writing up the Pocket ID steps here, but they should transfer to other providers.

The main thing you need to provide is the callback URL, which is https://example.com/auth/auth/openid_connect/callback, where example.com is your Mastodon domain. (Yes, double auth. No, I don’t know why 🤷‍♂️)

You should also enable PKCE.

You’ll then be given a Client ID and Client Secret. Keep a note of these.

Mastodon setup

The minimal setup requires adding the following to your .env.production file. The comments explain each option.

OIDC_ENABLED=true # The main switch to turn it on
OIDC_DISCOVERY=true # Required if you don't want to manually provide all the OIDC endpoints. Depends on your provider exposing these through the `/.well-known/openid-configuration` endpoint (which Pocket ID does)
OIDC_USE_PKCE=true # If you turned on PKCE when registering Mastodon with your OIDC provider. Turn on both or neither, but never one or the other
OIDC_DISPLAY_NAME="<Your Provider Name>" # Used on the "Log in with <Provider Name>" button
OIDC_ISSUER="https://id.example.com" # The root URL of your provider
OIDC_SCOPE="openid,profile,email" # The scopes you need
OIDC_UID_FIELD="preferred_username" # The field to match on
OIDC_REDIRECT_URI="https://example.com/auth/auth/openid_connect/callback" # The same callback URL you provided above

Now, there is one thing worth dwelling on: the OIDC_UID_FIELD setting. This determines how accounts are matched between Mastodon and your OIDC provider. For example, if your OIDC username is michael, this will create a Mastodon account @[email protected].

If you later change your OIDC username (say, to michael-thomas) and log in to Mastodon again, Mastodon will see a new user and create @[email protected]. So, yeah, you don’t want to change your OIDC username if you do this…

A couple of other settings worth considering:

If you want to disable password login altogether, add OMNIAUTH_ONLY=true to your .env.production. Users will then only be able to log in using your OIDC provider.

If you do that, you may as well also add ONE_CLICK_SSO_LOGIN=true, which skips Mastodon’s login form entirely and goes straight to the OIDC provider.

Switching to OIDC

There is an interesting wrinkle here: I already had my instance up and running, and so already had an account. When I tried to log in using my OIDC provider I got the message “Error creating an account for this identity.”

This is a sensible security feature by Mastodon, which prevents account takeovers from OIDC providers. To let me log in and link my existing @[email protected] account to Pocket ID’s michael account, I needed to add ALLOW_UNSAFE_AUTH_PROVIDER_REATTACH=true to my .env.production too.

This matches on email address rather than username, though. So it requires that the OIDC user has the same email address as the Mastodon user you want to link. Keep that in mind.

Make sure you remove it again afterwards, as it isn’t called ‘unsafe’ for nothing. On a single user instance it matters less, since each account can only be attached to an OIDC provider once, but it’s still good practice.

With that done, logging in goes straight through Pocket ID and my instance is one fewer set of credentials to look after. It took far more digging than it should have, so hopefully this saves you some of it.