Re: VC-HTTP-API - A follow up on the RAR presentation

Mike, thanks for sending this clarification. Some responses inline:

> On Jun 29, 2021, at 9:50 PM, Mike Varley <mike.varley@securekey.com> wrote:
> 
> (original title for this email was planned to be  “Red Fish, Blue Fish, OAuth Fish, RAR Fish”…)
> (sorry this is long)
>  
> Thanks to Justin again for the presentation on RAR and where it can fit with the VC-HTTP-API. I wanted to take this opportunity to attempt at defining the coloured boxes (Yellow, Green, Purple?), and highlighting a few proposals I saw fly by that SecureKey would support (and why).
>  
> First on RAR, there were some questions around the access_token format, and Justin pointed out that RAR makes no statement on access_token formats (see of https://datatracker.ietf.org/doc/html/draft-ietf-oauth-rar#section-4 <https://datatracker.ietf.org/doc/html/draft-ietf-oauth-rar#section-4>). To be clear, RAR specifies an additional _request_ parameter that richly describes (in JSON) the permissions/authorizations being requested; the Authorization Server is left returning (eventually) an access_token that permits a client to call the VC-HTTP-API endpoint – and the format/structure of this access_token is left to the AS and the VC-HTTP-API endpoint (it can be ‘opaque’, or a JWT, or a ZCAP… RAR has no position.) The JSON in the presentation strawman where request parameters, not access token formats. (It wasn’t 100% clear to me initially, so I am hoping this helps others as well).

Yes, my apologies if this wasn’t clear. I tried to reiterate that this has nothing to do with token formats or token contents, it’s about asking for a token that does something specific. And since what you’re asking for is the ability to do specific things on a specific API, that API can define what those different things are.

>  
> Second on the ‘boxes’ in the presentation; @Justin <mailto:justin@bspk.io>, and other, does the following begin to describe the functional realms of each ‘box’?
>  
> Yellow (end-user, agent, authorization server[AS]) : The protocol involved in connecting end-users, their agents (browsers, wallets, agents, apps…) to the authorization server to consent to an authorization request by a client (service).
>  
> Green (AS, client application, resource-server == VC-HTTP-API): the protocol for clients (server apps or otherwise) to request an authorization and receive an access token, and how to present that access_token to the resource server (VC-HTTP-API endpoint).
>  
> Purple (resource server, AS) : the protocol/means by which the VC-HTTP-API processes the access_token to trust the authorization and permit the requested function (opaque tokens require a callback, encrypted tokens require key negotiation, signed tokens require key exchange/setup… ZCAPs attenuated delegated auth or brute force JWT…)

This is all spot on, and why I drew the VC-HTTP-API in a different place for each box. The boxes are three different situations, three different diagrams overlaid on one larger picture. They are all independent of each other. None of them depend on each other, either.

>  
> And finally, some proposals that I have seen and SK would support, as an implementor of this API with use cases we want to build and demonstrate: (your mileage may vary, but just getting SK’s current position on record)
>  
> P1: Only the ‘Green Box’ is in scope for the VC-HTTP-API
> The VC-HTTP-API is a resource with several functions (issue/verify/”fetch”/”present”/”construct”) and clients need an interoperable way to request access _for these functions_, and to present access tokens to the endpoints. How clients connect with AS and end-users is a complex, nuanced and use-case specific problem – and one worth discussing – but at the VC-HTTP-API is not involved in that “yellow box” dance/handshake: it only processes access tokens – so a client needs to know how to ask for permissions (green box) and how to present the resulting token (green box). Since this is, in nature, a decentralized architecture, the VC-HTTP-API could be one-and-the-same as the AZ, or it could be a completely independent cloud resource that is willing to dynamically trust AS’s in the wild – don’t ask me how -- purple box – but this is also not the concern of the client-to-VC-HTTP-API endpoint (it becomes very use case and deployment specific again, IMHO).
>  

Exactly. And to be even more clear: VC-HTTP-API shouldn’t define a method of actually asking for or presenting a token, from a full protocol perspective. That is what protocols like OAuth 2 and GNAP define. What VC-HTTP-API should do, I propose, is say that when you want to get an access token using one of those protocols to do actions _USING THIS API_, you should do so by describing what you want using these RAR structures.

> P2: VC-HTTP-API MUST support OAuth 2.0 as an authorization protocol.
> For SK, at this time, OAuth 2.0 is a necessary and sufficient protocol for delivering delegated authorization for server-to-server authorization AND user delegated authorization. OAuth 2.0 is not perfect, but it is broad enough to allow for a wide range of use cases (including OIDC) – and it is accepted and implemented in market today, with a wide range of documented security concerns and best practices.
>  

I have no hard stance on this being a MUST, but agree the idea has merit as proposed.

> P3: VC-HTTP-API MAY support RAR
> There seem to be interest on the call today to leverage RAR as a method for requesting refined resource access; SK would support developing this request structure if the group wanted to move in that direction; with the caveat that not all implementations must use this method, and so far as it focuses on the VC-HTTP-API functions, and does not expand to include “yellow” or “purple” concerns (which are important, interesting, nuanced and use-case specific).

I wouldn’t phrase it this way. I would rather say “A VC-HTTP-API using OAuth2 with RAR MUST use the following authorization details types:” with full definitions of what those types and their components mean. I would go so far as to making it the RECOMMENDED option, with typical language around defined interoperability. Functionally this doesn’t change the requirements for implementors — they can use it or not as they best see fit. But without strong ties to the details of what “use RAR” means, there’s not much hope of interop.

>  
> P4: VC-HTTP-API MAY support GNAP
> SK is a big fan and strong supporter of GNAP; we see it being extremely useful in not only “yellow box” scenarios, but also in protocols beyond DIDs and VCs. That being said, we do not see it playing a vital role at this time with the VC-HTTP-API, and we do not want to make it a dependency as there are no ‘enterprise grade’ off-the-shelf implementations for customers to adopt today. Also, in this case, “MAY” needs to be clearly defined, and should not be an empty placeholder. For example, “MAY support GNAP for requesting authorization as with RAR defined above…” is better than “MUST support OAuth 2.0, MAY support GNAP or Giraffe”. The option to extend a spec is (almost) always implied, for proprietary integrations, or new specs can be written to openly describe an interop pattern; no need to ‘sorta endorse’ another spec without details.

Again, I would rather this be “A VC-HTTP-API using GNAP MUST use the following access types:” with full definitions of those types and what their components mean.

For both of these last two points, saying “MAY support” isn’t a particularly useful statement without additional details being more spelled out.


 — Justin

>  
> Thank-you for reading this far. I look forward to feedback.
>  
> MV
>  
>  
>  
> ---
> Vacation Alert: July 1 – July 9
> This email and any attachments are for the sole use of the intended recipients and may be privileged, confidential or otherwise exempt from disclosure under law. Any distribution, printing or other use by anyone other than the intended recipient is prohibited. If you are not an intended recipient, please contact the sender immediately, and permanently delete this email and its attachments.
>