aboutsummaryrefslogtreecommitdiffstats
path: root/posts/proposed_changes_to_indieauth_protocol.md
blob: f1a6c28538fc735c41a784bf058f8e1edebb3863 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
---
title: Proposed Changes to IndieAuth Protocol
published: 2015-03-04
modified: 2015-03-06
---

**Update (2015-03-06)**: Aaron Parecki replied to this proposal 
[here](https://aaronparecki.com/articles/2015/03/05/1/re-proposed-changes-to-indieauth-protocol). 
I agree with his reply as it turns out IndieAuth is also used for 
authorization in addition to authentication.

### Introduction

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](indiecert.html) 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="https://indiecert.net/auth">
<link rel="verification_endpoint" href="https://indiecert.net/verify">
```

#### 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.

### References

- [IndieAuth](https://indieauth.com)
- [IndieCert](https://indiecert.net)
- [Distributed IndieAuth](https://indiewebcamp.com/distributed-indieauth)
- [SaferWeb: OAuth2.a or Let's Just Fix It](http://homakov.blogspot.de/2012/08/saferweb-oauth2a-or-lets-just-fix-it.html)