Make token endpoint overrides consistent

[reiterate-app]

I originally raised this as a comment on #94 but since it touches on so many other issues I think it's best if it were addressed as its own issue. Apologies for getting it wrong the first time.

There are currently several different proposals for adding functionality to the token endpoint. Each of these proposals are indicating their specific overrides in slightly different ways, and that can lead to problems down the road:

• Someone who is new to IndieAuth and wanting to implement the spec from scratch will have to cross-reference several different sections to ensure all the various cases are covered
• Having multiple conflicting signifiers like this leads to weird edge cases and undefined behavior in the protocol
• Without a consistent calling method, there's no guide to how future extensions might work, except by continuing the "whatever works" hodgepodge. It would be nicer if, going forward, we had a clear approach to how future extensions can be added to the spec.

There's good reasons for why these inconsistencies currently exist. The separate proposals evolved independently and there wasn't any incentive for them to coordinate. Also there is a desire to ensure comparability with other auth protocols. These are all understandable and laudable goals, but perhaps with a bit of effort we can satisfy these desires while ensuring future consistency.

Token Endpoint Survey

I want to go through the current and existing proposals to record how each one wants to use the token endpoint. Each of these calls makes a POST to the token endpoint with the following parameters. Closing this issue would involve making a consistent way to determine the kind of request from the request parameters.

Authorization Code Exchange

This is the existing request currently in the spec, where a client exchanges an access code for a token

parameter	value
grant_type	"authorization_code"
code	code received from endpoint
client_id	The client's URL (same as initial request)
redirect_uri	Client's redirect URL (same as initial request)
code_verifier	For PCKE

Token Revocation

Also already in the spec. This is a request from the client to invalidate an existing access token.

parameter	value
action	"revoke"
token	previously granted access token

Token Introspection

A client asking if a given token is valid. Although this used to be a GET request to the token endpoint (and thus easily distinguishable) it is being moved to a POST request (to align with RFC7662 in #33) in PR #94 and thus runs into this issue.

parameter	value
token	previously granted access token

It's only distinguished from the Revocation Request by a lack of an action parameter. It's worth noting that the examples given in RFC7662 appear to indicate that the introspection endpoint is at a dedicated URL and does not share a URL with other endpoints.

Token Refresh

A client uses its previously-issued refresh token to request a new access token. Proposed in #90.

parameter	value
grant_type	"refresh_token"
refresh_token	Previously granted refresh token
client_id	Client URL (from initial request)
scope	token scope subset (optional)

This is using the distinguishing parameter grant_type, similar to the Token Exchange, but different from introspection and revocation.

Ticket Auth

Issue #87 proposes yet another override on the token endpoint (although there is discussion on this):

parameter	value
action	"ticket"
me	profile URL

So this is following the same action parameter as the revocation method

Issue #88 also has a lot of discussion on how the ticket endpoint should be implemented, whether it should be its own endpoint or yet another overload on the token endpoint, and it would benefit from having a clearly defined approach such as this issue is trying to achieve.

Proposals

Several solutions have been proposed to resolve this, each with its pros and cons.

Singular distinguishing parameter

We could ensure that all requests to the token endpoint include one parameter that distinguishes the request type. For example, requiring all requests to specify action would be sufficient, if we defined action parameters for each request.

@aaronpk has commented that this could break OAuth comparability, but I'm not sure that is the case.

Separate endpoints

We could break out he token endpoint into separate endpoints for each functionality. Token Auth has already been discussing this. Token introspection could also be separated into its own endpoint.

If we have different endpoints, it raises the issue of endpoint discoverability. If every endpoint is specified as a link reference in the header it could lead to clutter there. OAuth generally leaves endpoint discoverability up to the individual spec, so it could be specified as a sub-path on the token endpoint.

[jamietanna]

Discoverability would be solved using #43 - this may be a good opportunity to start looking into it as a way of more easily managing this?

[dshanske]

@reiterate-app Citing #88, the ticket endpoint is already a separate endpoint. The question in #88 is whether you should request external tokens from the ticket endpoint or the token endpoint. We're already in agreement you should redeem a ticket at the token endpoint, because you end up with a token managed by that endpoint. I'm leaning toward moving that into the ticket endpoint.

[dshanske]

So, the issue here appears to be multiple endpoints, versus one endpoint with multiple parameters. I don't see one being more or less confusing than the other.

[reiterate-app]

Discoverability would be solved using #43 - this may be a good opportunity to start looking into it as a way of more easily managing this?

I could get behind that. My main objection to using multiple endpoints is the clutter it introduces into the source documents (adding a link reference for every endpoint feels excessive). It looks like Discoverability was designed to address that very issue.

[reiterate-app]

So, the issue here appears to be multiple endpoints, versus one endpoint with multiple parameters. I don't see one being more or less confusing than the other.

I’m trying to come at this from the viewpoint of someone implementing the spec, and especially someone who is new to IndieAuth (and has to implement all this at once, instead of incrementally)

The question this person would ask themselves is, if I have an incoming request, how do I know what type of request it is?

if there are multiple endpoints, the answer is easy. You know they type of request based on the endpoint you receive it at. Done.

If there are multiple parameters, then answering this question involves at least a paragraph of text, and with every bit of functionality added that paragraph gets longer and more complicated.

I’m not saying that we have to have multiple endpoints (I suggested an alternative way to clean up the logic by adding some consistent parameters to the existing calls). But I think the existing ad hoc approach needs closer examination.

[sknebel]

(and has to implement all this at once, instead of incrementally)

That's only true to a degree. A lot of this is not needed for all cases, and can still be implemented incrementally.

[reiterate-app]

After discussion in the Pop-Up session, it was decided that the best approach is to go with Discoverability #43. We can break out all the existing token endpoint functions into their separate endpoints, and define those in the metadata file. Eventually the separate authorization_endpoint and token_endpoint will go away, as their endpoint locations will be defined in the metadata file as well.

For people with legacy implementations who don't want to change their code to implement separate endpoints, it will be easy enough for them to just set all endpoints to the same location in the metadata file. That will be allowed (or at least not explicitly forbidden).

[aaronpk]

This is complete now with the addition of the metadata document and definition of the new endpoints.