Switching costs for an IndieAuth server

One of the things I love about building with IndieWeb building blocks is that (sometimes through more work than anticipated) you can swap out pieces of your site without (much) disruption because the seams between building blocks are well specified.

So, this is me documenting how I replaced my IndieAuth setup to stop leaning on Aaron’s IndieAuth.com (which has been on the verge of retiring any day now for some years).

Please excuse this long and rambling post. Feel free to skip around!

What is IndieAuth?

At a high-level, IndieAuth is a way to sign in using your website as an identity.

Without digging too deeply into the plumbing, you start by updating your website’s homepage with some extra header info that says “my IndieAuth service is over there”. From there, you can sign into services that support IndieAuth (like the IndieWeb wiki, the social feed reader service Aperture, and more. And you can use your IndieAuth server to protect your own services, such as a Micropub server that can create new posts on your site.

Why switch?

I’ve been using indieauth.com as my IndieAuth setup since late 2016 because it was easy to set up, because it uses something called RelMeAuth to let me sign in using services I already trust (like GitHub).

However, indieauth.com has been growing stale as the IndieAuth spec has evolved. indieauth.com’s maintainer has been discussing replacing it since at least 2017.

The inciting incident for my switch was looking at OwnCast - a self-hostable video streaming service with attached chatroom. OwnCast’s chat allows using IndieAuth to sign in, which sounded great to me, but OwnCast’s implementation wasn’t expecting indieauth.com’s old-style response format.

Why set up my own?

There are a bunch of IndieAuth server implementations listed on the IndieWeb wiki. However: simplest of them (selfauth + mintoken) are now out of date with the spec and haven’t been replaced, yet. Others tend to be built into other CMSes like WordPress. A couple of standalone servers exist but are in languages I am not comfortable working in (hello Rust and Go) or have deployment requirements I wasn’t thrilled about supporting (hello Rails).

I found Taproot/IndieAuth on this page and that looked promising - a PHP library intended to be deployed within a fairly standard PHP web app style (“any PSR-7 compatible app”).

I knew this would be some work but it sounded promising and so I began the week-ish long process of actually writing and deploying that “PSR-7 compatible app” built on taproot/indieauth.

tl;dr say hello to Belding

Belding is an “PSR-7 compatible” PHP web app that provides a standalone IndieAuth endpoint for a single user with a simple password form for authentication.

I would love to go into the process and pitfalls of putting it together, but instead I’ll link to the README where you can learn more about how it works, how to use it, its limitations, etc.

Switching costs for an IndieAuth server

1. Tell the World

First up, you’ll need to update the headers on your site. I switched my authorization_endpoint and token_endpoint to my new server from indieauth.com. Since I’m updating to support the latest spec, I also added the indieauth-metadata header (which should eventually replace the other two).

Now that your site is advertising the new IndieAuth server, you will likely experience logouts or weird access denied reponses everywhere that your site has been used with IndieAuth.

2. Tell your own services

I needed to configure my own “relying apps” so they know to talk to the new server when checking that a request is allowed. This list thankfully wasn’t too long.

Beyond the effort of getting my server working as an indieauth.com replacement, I also took steps to try and support the latest in the IndieAuth spec. That meant updating these micropub servers to use the new “token introspection” feature which has some tighter security requirements.

(Note: I initially made the same change for my self-hosted copy of Aperture, but found it would be too many changes for me to take on at the moment. Instead, I updated by IndieAuth server to allow the older and less secure token verification method used by Aperture.)

3. Sign-in to all the things again \o|

Once all my relying apps were all talking to the new IndieAuth server, it was time to re-sign-in to all the things:


There are a lot of improvements I’d like to make to Belding, but in general I am happy that it seems to work and, outside of the time to develop the server itself, my website and the tools I use to manage it were only broken for about a day.

I think it’d also be really nice to wrap up Belding a bit so it’s easy to configure and deploy on free-and-cheap platforms like fly.io. I believe it should be easier for folks to spin up and control their own IndieWeb building blocks where possible!

It’s also become clear to me that there are some user- and developer-experience holes around setting up relying apps. The auth requirements for token introspection, for example, means you need a way to manage access for each “backend” that you have that relies on IndieAuth to protect itself!

Long story short (too late) I am finally able to sign into OwnCast server chat using my domain. 😂😅


Aaron Parecki
Jamie Tanna


Tom Tom at https://herestomwiththeweather.com/2022/10/09/minimum-viable-indieauth-server/ said:

One of the building blocks of the Indieweb is IndieAuth. Like many others, I bootstrapped my experience with indieauth.com but as Marty McGuire explains, there are good reasons to switch and even consider building your own. Because I wanted a server as simple to understand as possible but also wanted to be able to add features that are usually not available, I created a rails project called Irwin and recently configured my blog to use it. This is not production ready code. While I know that the …