Clarify relationship between authorization_endpoint and token_endpoint in protocol flow diagram

[barnabywalters]

Currently, the protocol flow diagram shows the auth and token endpoints as being distinct entities to the same degree as the user’s browser or homepage. However, the spec assumes that the two endpoints are closely linked i.e. live in the same web app, have access to the same storage etc.

To make their relationship clearer, I propose the following:

• Surround the columns for the two endpoints in a coloured border to indicate that they’re related and share the same “edge” with regards to the other endpoints and entities involved
• Potentially, additionally clarify how the protocol functions by including a third “storage” column within in the same outline, with arrows to and from indicating at which point the auth code is stored and referred to. I’m more ambivalent about this addition as it would complicate the diagram, and auth codes don’t necessarily have to be stored, they can be self-encoded.

If more detailed architecture and/or application diagrams are made, I propose similar measures are taken there to clarify the relationship between the two endpoints (#26, #27)

[Zegnat]

I would just want to have a good thing about how to do it without making it look like it is a must for the two services to be one and the same thing. It is actually completely fine for the two endpoints to communicate with eachother using the old IndieAuth specced way of inter-communications. It is just that the August 2020 update declared it underused, which is written up as out of scope in the spec:

The specifics of how the token endpoint verifies the authorization code are out of scope of this document, as typically the authorization endpoint and token endpoint are part of the same system and can share storage or another private communication mechanism.

I do not know if this out of scope is best attributed by having a special arrow between the two lanes labelled as such, or by adding a box around them, or what. I just do not want the diagram to give people the idea it must be boxed in as one service.

(Boxed in, get it? I’ll see myself out.)

[barnabywalters]

Perhaps a dashed border around the two endpoints, with a footnote noting that they can potentially be located on different services, but that the diagram assumes that they’re part of the same service for simplicity?

Did the auth <-> token endpoint communication protocol get written up as an extension anywhere? If so, the footnote could link to it.

[aaronpk]

I don't think anybody cared enough to write it up as an extension yet

[Zegnat]

Did the auth <-> token endpoint communication protocol get written up as an extension anywhere? If so, the footnote could link to it.

I think we only really established two implementations? IndieAuth.com which is planned to be deprecated, and my own MinToken which I will also be replacing for my use. But it should be easy enough to write it up as an extension by just copying the old spec, if anyone were to show an interest.

[aaronpk]

I've added a box around the authorization server parts, I agree it makes it a bit clearer. Done in 1f4f4ad