François' Blog

Proposed Changes to IndieAuth Protocol

Published on 2015-03-04 | Last modified on 2015-03-06

Update (2015-03-06): Aaron Parecki replied to this proposal here. I agree with his reply as it turns out IndieAuth is also used for authorization in addition to authentication.


This post proposes a few minimal changes to the IndieAuth protocol as well as their rationale. These changes were inspired by creating an alternative but mostly compatible IndieAuth implementation called IndieCert, using client certificates to authenticate users, or actually browsers. More information on IndieCert can be found in this blog post.

Optional client_id

Currently the protocol expects the use of the client_id parameter in the authentication request. This does not seem necessary as it is never used, just a remnant of OAuth 2.0. The redirect_uri is enough to establish the relying party's identity. So the proposal is to make client_id support OPTIONAL both for relying party as well as the IndieAuth services.

CSRF protection

It is advisable to implement CSRF protection. The state parameter can be used for that, or a new parameter, like csrf_token, as proposed by "SaferWeb: OAuth2.a or Let's Just Fix It" MUST be implemented.

This will protect against an attacker obtaining a code and tricking the user's browser to go to the relying party's callback endpoint, thus gaining access to the server on the attacker's behalf and potentially leaking private data to the attacker's account.

The CSRF token (or state) needs to be saved in a browser session that is created when the user tries to login to the relying party. The CSRF token is compared to the token specified on the callback URL after the user grants permission to the relying party to obtain the user's identity.

Terminology: authentication instead of authorization

IndieAuth is actually used for authentication and not authorization as is mentioned on the "Distributed IndieAuth" page. This should be modified to talk about authentication instead. Also the name of the authorization_endpoint should be changed to authentication_endpoint.

Additional "verify" endpoint

The "auth" endpoint in IndieAuth is currently used both for initiating the authentication (GET) as well as verifying the authentication code (POST). In order to support the option to ask for user consent before the identity of the user is released, it makes sense to have a separate verification endpoint as the POST on the authentication endpoint will be used for a form submit.

This is also relevant in the case of "Distributed IndieAuth" where the user mentions the authorization_endpoint, as a link relation on their home page. The proposal is to also allow for (optionally) defining a verification_endpoint link relationship on the user's homepage. For example:

<link rel="authentication_endpoint" href="">
<link rel="verification_endpoint" href="">

Content negotiation for "verify" endpoint

Currently the IndieAuth protocol uses a application/x-www-form-urlencoded formatted response instead of the currently more popular application/json response format, e.g. in OAuth 2.0. It is proposed to support "Content Negotiation" by checking the HTTP Accept header in the verification request and returning either application/x-www-form-urlencoded or application/json depending on the Accept header. The default can be either of those, but both MUST be supported.