Re: [AGENDA] VC HTTP API Work Item - July 13th 2021

I think you’re asking a confusing question.

Added work for the VC-HTTP-API? Zero.

Added work for an implementor? Depends on where you’re starting. If you’re trying to start from an existing OAuth2 implementation, it’s a medium amount because OAuth2 and GNAP are not wire compatible (by design) — but everything you’re changing has nothing to do with the piece I’m suggesting we defined. In fact, the RAR portion of your OAuth 2 implementation would be completely identical to the same piece of the GNAP request. 

And if you’re starting from a green field, then you’re building GNAP. There simply isn’t a decade+ of implementations and extensions for GNAP yet for the simple reason it hasn’t been out for a decade+, but there are a handful of piecemeal implementations that people are working on with more coming.

But let me be clear: I was not saying that specific implementations should be required to implement and use either of these. My read of the proposal, and my recommendation, is that one of the defined mechanisms for protecting access to the API be GNAP, and that another be OAuth2 with RAR. 

And I’m saying you can get :both: of those with one section of specification text, like I presented.

 — Justin

> On Jul 12, 2021, at 11:49 AM, Adrian Gropper <agropper@healthurl.com> wrote:
> 
> Hi Justin,
> 
> Thanks for your detailed preview of the proposals.
> 
> Given the entirety of your responses, is it possible for you to explain to the group how much added work it would be if the resolution of:
> > PROPOSAL: One of the authorization mechanisms for the VC-HTTP-API SHOULD be GNAP key-bound access tokens.
> 
> were to be MUST instead of SHOULD?
> 
> - Adrian
> 
> On Mon, Jul 12, 2021 at 11:33 AM Justin Richer <jricher@mit.edu <mailto:jricher@mit.edu>> wrote:
> I hope to attend the call tomorrow, but for now here are my thoughts on the proposals here:
> 
> > 
> > PROPOSAL: How a VC HTTP API client gets an authorization token is out of scope.
> > 
> 
> +1. The details of getting a token (ie, make this call using this protocol) are separate from the API being protected.
> 
> > PROPOSAL: How a VC HTTP API server validates an authorization token is out of
> > scope.
> 
> +1, for the same reasons as above.
> 
> > 
> > PROPOSAL: One of the authorization mechanisms for the VC-HTTP-API MUST be
> > OAuth 2 Bearer tokens.
> 
> +1, this is a reasonable baseline for the API to define, even with most of the rest of the details out of scope.
> 
> > 
> > PROPOSAL: One of the authorization mechanisms for the VC-HTTP-API SHOULD be
> > GNAP key-bound access tokens.
> 
> +1, while I would prefer this to be a MUST, this is acceptable.
> 
> > 
> > PROPOSAL: One of the authorization protocols for the VC-HTTP-API MUST be OAuth
> > 2 Client Credentials. NOTE: This one conflicts with the first proposal (on
> > purpose).
> 
> -1, and a big one. This brings in way too much detail to the API. It shouldn’t care about grant types, client types, or anything that happens in the process of getting the token at this level of detail. Saying this locks the API into one very specific and very narrow delegation and deployment pattern, and for no good reason. 
> 
> > 
> > PROPOSAL: The VC HTTP API MUST define access actions in terms of OAuth 2 RAR
> > structures.
> 
> +1. This is the core of the proposal I am making to the group. This would allow the API to define the separable actions that the API is capable of allowing, and the dimensions along which those are defined.
> 
> In other words, it lets you have a layer of interoperability that meshes with the API’s definition WITHOUT getting into details of “how you get a token” or “how you validate a token” or even “what goes inside a token”. 
> 
> 
> Also, a -1 to both the “separate / do not separate” proposals. I think it’s focusing on completely the wrong thing. We shouldn’t say how to use OAuth or GNAP apart from the following very limited things:
> 
>  - say you can use an access token (either bound or bearer depending on your use case)
>  - give a description of what you can ask for at this API (this is what RAR gives you, and would work with both OAuth2 and GNAP)
> 
> … and that’s it. Don’t say anything about grant types, especially client credentials. Don’t say anything about token formats or introspection. Don’t say anything about token contents. Don’t say anything about client types and deployments. 
> 
> It seems to be that I keep suggesting this one thing and the group keeps reacting negatively to something else that I have — many times — explicitly said not to do, and yet assigning that negative reaction to what I’m proposing. I am genuinely at a loss of how to clear up this confusion at this stage, but hopefully the above helps.
> 
>  — Justin