Define OAuth2 authorization mechanism

[msporny]

It has been 10+ months since the group first discussed API endpoint authorization. At this point, we have 5 implementations demonstrating some level of interoperability with OAuth2 as the authorization mechanism most implementations are using. There are another two implementations (Traceability Profile) that are not integrated with the test suite yet, but use OAuth2 as well.

The group should determine if now is the right time to define OAuth2 authorization in the specification.

[msporny]

The group discussed this on 2022-08-23. Manu asked if we wanted to implement OAuth2. @dlongley noted that we will want to say "If you implement OAuth2, you MUST implement it in this way" and also note that "another authorization mechanisms that support delegation might be defined in the future".

The group resolved to do the following on the call:

RESOLVED: Define OAuth2 as an authorization mechanism in the VC API noting that if it is implemented it MUST be implemented in the way defined in the VC API. Note that another authorization mechanism covering delegation might be defined in the future.

[dlongley]

In our implementation, OAuth2 tokens have an audience of the particular issuer instance: e.g., <origin>/issuers/zc612332f3.

The scopes are generalized to read/write actions on particular endpoints:

read:/ would allow reading on any API on a particular instance. write:/ would allow reading on any API on a particular instance.

write:/credentials/issue would only allow writing to that particular API.

[msporny]

The question around scope names was explored on the call. The scope names discussed were "read/write" for endpoints with endpoints (DB/ZCAP aligned) vs. "verbs" associated with endpoints (Traceability).

For read/write scope names, the generalized pattern is: "read/write ENDPOINT".

For verb scope names (Traceability) -- issue/credential, read/credential, provide to people as clear/attenuated permission as possible. When this was built, they were happy to have bigger conversation w/ bigger VC API group, but current idea was best effort -- if there are reasons to switch, happy to explore. The biggest idea was "pick a scheme, stick to it, happy with it so far".

The Traceability cohort currently uses these scopes:

https://w3c-ccg.github.io/traceability-interop/draft/#scopes

resolve:dids
issue:credentials
verify:credentials
read:credentials
update:credentials
prove:presentations
verify:presentations
submit:presentations