Security Framework

[jricher]

---

Preview | Diff

[jricher]

Note that this doesn't add additional fields to the endpoint definitions because of limits in ReDoc not allowing display or definition of extensions. I hacked ReDoc locally to support additional security properties, and it looks like this:

From a definition that looks like:

  securitySchemes:
    vcHttpApiAuth:
      description: Control access to the API using OAuth 2.0 RAR or GNAP
      type: rar
      rarType: 'https://www.w3.org/TR/vc-http-api/issue'
      locations:
        - '<The absolute URL of the endpoint being called>'
      datatypes:
        - credential
      actions:
        - issue

[mprorock]

2. No examples of traditional scope based OAuth, such as those supported by Auth0 / Okta.

big +1 to getting scopes in there - this is the industry default right now and does not appear to be changing any time soon, so we should provide appropriate guidance on how to implement

[agropper]

I feel strongly that Justin's PR language should stay as MUST.

[TallTed]

SHOULD might be better than MAY for general interop ...

and at this stage of everything, SHOULD take { RAR, GNap, other } into consideration before going down another road might be better still, especially if such consideration leads to actionable feedback on this doc.

[jricher]

I disagree strongly to adding in scope descriptions.

[agropper]

I'm commenting based on the assumption that GNAP and OAuth2 will be co-equal SHOULDs for VC API authorization, meaning that API conformance testing will require both protocols to pass. (I know this is not settled but I'm hoping to keep this issue clear and moving forward.)

In the case of co-equal SHOULDs we then have the choice of specifying RAR in both cases or not. From my position, limiting RAR to only the GNAP authorization path would save no work for the implementers but could provide a measure of backward compatibility in some deployments at some cost in interoperability.

[msporny]

This PR has not seen any movement forward in over a year. Closing.