Ensure that GNAP can be an Authorization protocol extension

[msporny]

The group should define how GNAP can be utilized for performing authorization and delegation through an Authorization protocol extension. The discussion thread that led to the raising of this issue can be found here:

https://lists.w3.org/Archives/Public/public-credentials/2021May/0002.html

The suggestion is that the specification should 1) have a section that discusses authorization and delegation mechanisms and extensibility, and 2) ensure that (through extension) GNAP is one of the authorization and delegation options.

[msporny]

We need to define more concrete language in the specification that covers authorization mechanisms such as GNAP, OAuth2, etc... or say nothing at all.

The next step here is to write a PR with more concrete language than exists in the current specification related to any authorization mechanism that a proposer would like to see in the VC API specification.

[mavarley]

I was considering a PR for this item in light of the discussion on issue #279 ; particularly the range of techniques to authenticate/authorize calls to this API. I believe there is a range; and perhaps the spec should define those ranges and recommendations. If the group agrees with the approach I can word smith a PR, but something along the lines of:

API Authorization

The VC API is meant to be a generic API that can be useful in many scenarios that require the issuance, holding, presenting and verifying Verifiable Credentials. As such there are the following classifications of use cases that the implementor should consider.

Public. A Public API is one that can be called with no authorization. Examples include an open witness or timestamp service (a trusted service that can digitally sign a message with a timestamp for an audit trail purpose), or an open retail coupon endpoint ("15% off cheeseburgers"). Public verifiers may exist as well, acting as a agnostic third party to a trust scenario.

Permissioned: Permissionsed authorization requires the entity making the API call to have an access control token issued from a mutually trusted source (like an authorization service in OAuth 2.0 Client Credential grant scenarios). These permissions grant access to the API but make no assumptions about credential subjects, previous interactions, or the like. Permissioned access is particularly useful in service-to-service based workflows, where credential subjects are not directly involved. The VC API test suite operates in a Permissioned mode, and all implementations acting on the test suite MUST support the OAuth 2.0 Client Credentials Grant.

Bound. Bound authorization involves scenarios where the API calls are tightly coupled, linked, or bound to another out-of-band process that has authenticated the holder/subject to the API interaction. These use cases include but are not limited to, for example, issuance of subject specific identity claims directly to the subject in question, or verification of credentials to qualify the holder for service at the verifier. Examples of methods to bind activity on one channel to a VC API call include CHAPI, OpenID Connect, and Grant Negotiation Authorization protocol. Developers implementing bound authorization will need to take steps to ensure the appropriate level of assurance is achieved in the flow to properly protect the binding.

The VC API provides methods for increasing the level of assurance within an exchange, by allowing the server to request additional assertions from the holder to 'step up' the trusted channel. In this way a Public API endpoint could migrate to a Bound API exchange.

(then maybe we have an example of methods / best practices on how to achieve a bound level of API authorization).

Thoughts on the above approach?

It still keeps specific OAuth/ CHAPI/ GNAP/ ZCAP protocol details out of scope; but I believe it provides implementors some level of guidance on how to approach protecting the API. It also clearly states the expectations of the test suite for interoperability and compliance testing.

Thoughts?

[msporny]

Thoughts on the above approach?

In general, I personally agree with the approach and really like most of the language provided above. There are at least three things I'm concerned that we're going to get push back from the group on are:

1. Any statements about the test suite in the core specification -- @jricher specifically cautioned the group to not confuse the spec with the test suite. I'll admit that I don't think I've ever seen a spec make normative statements about the test suite; groups tend to prefer to decouple the operations of the test suite as much as they can from the spec. Concrete ask: strike the following statement -- The VC API test suite operates in a Permissioned mode, and all implementations acting on the test suite MUST support the OAuth 2.0 Client Credentials Grant. -- we're going to do that anyway, because the implementers want to do that, but the spec should probably stay silent. We can put that documentation in the test suite / reports / etc. Some implementers are still operating in "public" mode.
2. In general, I like the "public/permissioned/bound" concepts -- we'll need to nitpick on the language... and it feels analogous to NIST Levels of Assurance. So, perhaps we should steal some language from other IETF/W3C authz docs (if that language exists already, or NIST, or in the worst case -- define some language ourselves). I don't have alternatives for "public/permissioned/bound" at present... but perhaps if we spend some time debating the definition of those things, the terms will become more clear. It feels like from an LoA perspective, it's 1) "we have almost idea who is interacting with the endpoint", 2) "we know which registered client is interacting with the endpoint", and 3) "we have some idea of the subject that's interacting with the endpoint". I'll note that we can know 1 and 3 without discovering 2 with CHAPI / VC API today - so, it's not a continuum, which is where the LoA analogy breaks down.
3. @jricher was pretty explicit in what he wanted -- concrete specification text instead of the wishy-washy text we have in the current spec. He noted that he had raised a PR to address his concerns before, and that PR has yet to be merged. I'm pointing that out as an example of the level of detail that at least one person in the group is requesting. I agree that we should (eventually) have language that is effectively: "If you authz via X, then you MUST do Y". The language you propose above, @mavarley, is a framework on how to think about authz wrt. VC API.

All that said, it would be great to have some variation of the text above in the spec @mavarley ... I believe it's an appropriate mental model for thinking about the VC API... and we can fine tune it later as we get more clarity. My suggestion would be to avoid the "If you're using OAuth, then you MUST" language for now as that's the stuff that got hackles up the last time. I acknowledge that avoid that is not going to address this specific issue, so we'll still need a PR for the more specific language that @jricher and others are asking for. The trick there might be to agree to define at least 3 simultaneously -- OAuth2, GNAP, ZCAPs.

Thoughts?

[mavarley]

In general, I like the "public/permissioned/bound" concepts -- we'll need to nitpick on the language...

I believe the OAuth terminology may be "public/confidential/delegated" but terms may have deeper implications on the security profiles of the clients -- dunno if we want to go there.

Agree with the other points as well. I also agree that concrete specs for interoperability (and recommended best practices) are important. (You'll notice I totally hand-waved the 'make sure it's secure enough for your use case, eh? good' above :) ).

[TallTed]

@mavarley —

require the issuance, holding, presenting and verifying Verifiable Credentials.

All the verbs should agree with each other... How about —

require the issuance, possession, presentation, and/or verification of Verifiable Credentials.

— or —

require that Verifiable Credentials be issued, held, presented, and/or verified.

(ETA — I'll save other wordsmithing for the PR. Comments are a terrible place for collaborative editing.)

[msporny]

The group discussed this on the 2023-12-05 call:

@msporny noted that the API is authz mechanism agnostic. @mavarley's comment above was noted as a good direction. There were no objections for stating that the API is authz-mechanisms agnostic. The proposal was to start from @mavarley 's text and update it to match the current understanding in the group.