search

w3c-ccg / vc-api

A specification for an HTTP API used to issue and verify Verifiable Credentials.
https://w3c-ccg.github.io/vc-api
Other
124 stars 47 forks source link

HOLDER APIs security not defined sufficiently #187

Open OR13 opened 3 years ago

OR13 commented 3 years ago

https://github.com/w3c-ccg/vc-http-api/blob/main/docs/holder.yml#L59

in particular, apis that are meant to only be exposed with authorization vs apis that are meant to be exposed without authorization.

OR13 commented 3 years ago

@msporny as I side note, I am surprised to see such a contentions change magically show up with the API spec, after months of requested changes... perhaps this was an error?

OR13 commented 3 years ago

I think we should split the APIs for holders by internal and external to avoid confusion.

msporny commented 3 years ago

I am surprised to see such a contentions change magically show up with the API spec, after months of requested changes... perhaps this was an error?

Yeah, that was an error -- @peacekeeper -- did you mean to submit an extension that was the thing that led to the current controversy around VC HTTP API? How did that get in there?

I think we should split the APIs for holders by internal and external to avoid confusion.

We need to figure out what the demarcation point is... the language matters here, we don't want to pick the wrong language because it'll confuse everyone.

There are a couple of dimensions here... 1) issuer/holder/verifier and then for each 2) internal vs. external... which means, we could end up with six different specifications (which would probably be terrible)... OR, we could split it along issuer, verifier, and presentation APIs, where the first two are "internal" and the last one is "external"... and then drop the "internal/external" terminology. I'd prefer the latter if we could swing it... but to do so, we'd need a complete list of all endpoints (and to get there, we'd need more use cases, or at least, talk to how each use case is solved using the API today).

I have created three diagrams to try to guide the group through this discussion today:

https://docs.google.com/document/d/1-u0_Ub6feiX6DH3jXFJFjt6n3CwKGpkmC3VISqDkWL4/edit#

Hopefully we can point out where the diagrams are wrong or go off the path people thought we were on, adjust, get some high level agreement on architecture... then use cases, then endpoints.... then hopefully figure out how we're grouping these things together.

It would be helpful if someone would catalog all endpoints we have and then try to put them into broad categories... like issue/verify/present OR internal vs. external OR something else that is a better grouping. We'll get there... more slowly than any of us would like.

OR13 commented 3 years ago

For reference, this how we expect the external holder APIs to work: https://github.com/w3c-ccg/traceability-interop/issues/11

noting that the authorization header to an "external api"... vs what I assume would be to an "internal api" for things like "build be a signed presentation".

msporny commented 11 months ago

The group discussed this on the 2023-12-05 telecon. @jandrieu volunteered to write a PR on this, to identify which endpoints need authorization and by whom. The only endpoints that didn't have authz at this point in time is the status checking endpoint and the start of some workflows/exchanges.

jandrieu commented 11 months ago

It turns out there are a few different authorization patterns

  1. coordinator talking to its service (must be secured, we don't care how)
  2. verifier coordinator talking to status service (must be unsecured, no authentication)
  3. holder coordinator talking to an issuer coordinator (issuer's choice)
  4. Workflow usage with three variants
    1. Administrator access to set up workflows must be secured somehow (mechanism not specified)
    2. Owner coordinator falls under #1 (talking to its own service)
    3. POST to a workflow exchange endpoint... UNKNOWN.

It's the last one that is the biggest question. Do exchange endpoints ALWAYS work (bearer tokens) or can there be some other securing mechanism? Is this a choice of the workflow configuration? It seems to Eric and I that it probably should not be a choice, to enable specific automated workflows, but I don't recall talking about how those exchange endpoints are secured.

Reading the flow in https://w3c-ccg.github.io/vc-api/#exchange-examples it appears that exchanges are expecting that the exchange was provided as part of a VPR and the resulting VP is sent to "authenticate and/or authorize" the holder.

That leads to a few questions:

  1. Are all exchange endpoints expecting VPs?
  2. Are VPs sufficient to authorize access? (How is that rule set when creating the exchange endpoint.
  3. Can endpoints be secured by other mechanisms? Is that allowed?