Home » How IndieAuth works

Beto Dealmeida's avatar

How IndieAuth works

A simple explanation of IndieAuth

Approximate reading time: 3 minutes

Imagine someone emails you saying "hey, I'm your cousin Alice Doe, nice to meet you!" How do you know it's true?

You could ask your uncle Bob Doe, "do you have a daughter called Alice?" That would confirm that Alice exists, but not that the person emailing you is Alice.

So you tell her "go to Bob Doe and bring me some proof that he's actually your dad".

Alice goes to Bob and says, "hey, dad! I want to prove to cousin Charlie that I'm Alice Doe." (Charlie is you.)

He writes a little note that says "Alice is my daughter, signed Bob." Alice brings you the note.

Now, anyone could've written that note. So you show the note to your uncle Bob and ask him "did you write this and give it to Alice?"

"Yes, I did."

And now you know that Alice is who she says she is.

After reading the IndieWeb spec[archived] I think this is a good explanation of how it works.

Alice visits a website charlie.example.com. It asks her to use her URL to login, so she types https://alice.example.com.

The website charlie.example.com takes a look at alice.example.com, inspecting both its HTTP response headers and the HTML source code. It finds a link defining a special relationship:

<link href="https://bob.example.com" rel="authorization_endpoint">

This points to a resource that can validate Alice's identity, just like her dad did. So the website sends Alice to her dad by redirecting her to this URL:


When Alice is redirected to that URL, she should be logged in — just like her dad knew who she was, the website bob.example.com should know who she is and that she owns https://alice.example.com. Otherwise, anyone would be able to login as https://alice.example.com/.

The website bob.example.com asks her if she wants to confirm her identity:

Screenshot of a web dialog asking 'Confirm access. Are you sure you want to allow https://charlie.example.com/ to access your site https://alice.example.com/ ?'

She clicks "Yes", so bob.example.com redirects her back to charlie.example.com with a code:


The code is similar to the note Bob wrote. It should be short lived (10 minutes) and valid for only one use.

The website charlie.example.com receives the code and the original state. The state is used by charlie.example.com to verify that the response is for the login Alice initiated. The charlie.example.com website then sends the code back to bob.example.com, and gets back a response confirming that that code belongs to https://alice.example.com/.

This confirms to charlie.example.com that Alice owns https://alice.example.com/ and she can login successfully.

Note that everything depends on bob.example.com, the authorization endpoint, knowing that Alice is the owner of https://alice.example.com/. It can only give out codes if Alice is logged in on bob.example.com, If Alice is logged out, when she's redirected to bob.example.com after trying to log in on charlie.example.com, the authorization endpoint will not forward her back to charlie.example.com with a valid code.

This description covers only part of the IndieAuth specification, useful for authentication. The protocol also defines scopes that can be used for granular access, for example, reading but not editing a blog post.

(Also posted on IndieNews.)


You can engage with this post on Twitter or Webmention.