Define OAuth2 requirements for /presentations/submissions

[brownoxford]

The goal of this issue is start discussion regarding the OAuth2 authentication requirements of the /presentations/submissions endpoint. This issue stems from the discussion on #187, and can be considered complete when the following items are resolved:

Please note: the following lists are displayed as GitHub task lists for visual effect, not to suggest that there are actually additional tasks to be done.

The state of the checkboxes in this description represent the in-progress resolution of this issue. Until the ready-for-close label is applied, this issue should be considered in-progress. This issue MUST NOT be closed until corresponding issues have been opened to implement the relevant conformance testing and, if necessary, modify the openapi spec.

Goal 1: Explicitly state OAuth2 requirements for the /presentations/submissions endpoint
One, and only one, of these options MUST be selected.

• The /presentations/submissions endpoint MAY require OAuth2
• The /presentations/submissions endpoint MUST require OAuth2
• The /presentations/submissions endpoint MUST NOT require OAuth2

Goal 2: Explicitly define scope requirements for this endpoint when authentication is in use:
One or more of these options MUST be selected unless the MUST NOT option was selected in Goal 1, in which case these options MUST NOT be selected. For requests that require OAuth2, each of the selected scopes MUST be present in an OAuth2 bearer token in order for the request to be permitted.

The following list of OAuth2 scopes is pulled from the current openapi.yaml file. If additional scopes are needed for the /presentations/submissions endpoint, they should be added here and an issue should be created to ensure that openapi.yaml is updated.

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

[BenjaminMoe]

Goal 1:

The /presentations/available endpoint MUST NOT require OAuth2

Opinion

This one should be non-ambiguous. The /presentations/submissions end-point uses did-authentication by definition. The OAuth version of this end point is POST /presentations, so if you wanted to use OAuth2 for presentations, you should use that end point.

[TallTed]

The /presentations/available /presentations/submissions endpoint MUST NOT require OAuth2

Justification?

I'm sure I don't fully understand either OAuth2 or the currently popular split of endpoints, as listed in the several "Define OAuth2 requirements" issues, but to the degree I do, it seems to me there are conceivable situations where one might want to require authentication for all endpoints one makes available, including /presentations/available /presentations/submissions. In itself, this might not require OAuth2, but I cannot see a reason to forbid OAuth2 for such use — which breaks from the MUST NOT above.

So please, why must OAuth2 be forbidden for this use?

[BenjaminMoe]

So please, why must OAuth2 be forbidden for this use?

/presentations/available and /presentations/submissions are a set that implicitly use did authorization.

1. A holder sends a request to a verifier on the /presentations/available end point
2. The verifier end point returns a domain and challenge
3. The holder signs over the challenge
4. The holder sends the signed presentation on the /presentations/submissions end point to the verifier
5. The verifier verifies the presentation by checking the signed challenge (and can choose to reject the presentation if the signature is incorrect, if the signature is not signed by a white-listed did, or if the credentials included in the verification does not meet some criteria specified by the verifier).
6. The verifier returns a response to indicate the presentation has either been accepted or rejected

The OAuth2 version of this flow is defined by the /presentations end-point.

A verifier supplies a holder with a client_id and client_secret to use for Authentication. The holder obtains a token with the client_id and client_secret.

1. The holder sends a presentation to the verifier with the token provided by OAuth2
2. The verifier returns a response that indicates that the presentation has been accepted or rejected.

In this case the token is providing the functionality that the signature role previously played. Where because the verifier has provided a holder with a client_id and client_secret it is understood who the sender is, and a signature is not required to prove identification for this end-point.

The reason that OAuth2 is forbidden by this end-point is because the authorization scheme is implied by the end-point definition. If you wanted to use the OAuth2 version of this flow you use /presentations, if you want to use the did-auth flow, you use
/presentations/available + /presentations/submissions.

[nissimsan]

+1 on #242 (comment).

Except, @BenjaminMoe I think you mean /presentations/submissions which is what this issue is about (you probably copy-pasted from the submissions-issue).

So, to be precise:

The /presentations/submissions endpoint MUST NOT require OAuth2

This is a DIDAuth endpoint. OAuth on top of it would be double-authentication.

[TallTed]

@BenjaminMoe --

The large comment is great! I think something similar should be in each of these detailed issues, preferably as the first comment following the opener, if not as part of the opener itself, especially the last paragraph, i.e. --

The reason that OAuth2 is forbidden by this end-point is because the authorization scheme is implied by the end-point definition. If you wanted to use the OAuth2 version of this flow you use /presentations, if you want to use the did-auth flow, you use /presentations/available + /presentations/submissions.

I do wonder why you're using checklists for the identified "Goals" (which don't seem like "Goals" to me, but I guess that's the term used in some programming methodology?).

"Goal 1" seems like a radio-button candidate, as when any one checkbox is ticked the others should not be -- i.e., they're all mutually exclusive.

"Goal 2" looks like it should have something checked, and that those checked items should be mentioned in the large comment, but maybe I'm misunderstanding something else?

---

All that said, in #242 (comment), you still have --

Goal 1:

The /presentations/available endpoint MUST NOT require OAuth2

-- which it appears, as @nissimsan noted (and as you have edited in several other comments on this issue), should be about /presentations/submissions, not /presentations/available.

[brownoxford]

OpenAPI documentation has been updated. Since OAuth2 is not required for this endpoint, we will not need to write specific negative testing to ensure that it is enabled. This can be closed out.

[nissimsan]

We did this.