Initial proposal for New Security Schemes

[whitlockjc]

This purpose of this proposal is to rethink how Security Schemes are defined in OpenAPI. This proposal would separate the credential location(s) from the Security Scheme type and would allow for complete control over dictating where the credential(s) are provided for a Security Scheme. This proposal will add a generic way to retrieve a credential from anywhere in a request, and allow any Security Scheme to dictate where its supported credential(s) are instead of relying on OpenAPI-supported conventions/opinions. This proposal also separates the credential location(s) details from the other configurations associated with the Security Scheme (like JWKS details for JWT).

[orubel]

Bringing it up again folks. Since when a token is supplied during a client request (note I said, the token is supplied so this is AFTER the OAUTH handshake), the ROLE can be checked but it is NOT checked vs the request data being sent or the response data being returned that is defined in the doc.

As an ADMIN ROLE can request the same endpoint entirely differently than a USER ROLE and get an entirely different response dataset, all prior itterations as well as the current iteration of the OpenAPI spec are in direct violation of OWASP API3:2019 (https://apisecurity.io/encyclopedia/content/owasp/api3-excessive-data-exposure.htm)

without knowing what the roles are, this can be alleviated simply by allowing a STRING to be the KEY association for request/response datasets like so:

"REQUEST": {			            
    "permitAll":["username","password","email"],                                   
     "ROLE_ADMIN":["id"]			       
 },			        
"RESPONSE": {			        	
    "permitAll":["id","version"]			       
}

permitAll defines all roles defined in ROLE_GROUP that have access to this endpoint (the catchAll ) whereas Role_ADMIN is a specific RULE for ROLE_ADMIN allowing a concatenation onto the 'permitAll' data if your ROLE==ROLE_ADMIN

This document establishes these RULES for the request response so that ANYWHERE in the call flow, a device/service can now use this document to check these rules.

And I KNOW I KNOW... there are no ROLES and there never will be. But you will never be secure until you start addressing security. So... thats why I am bringing up security and how to address it because I have addressed this for the last 5 years and have helped multiple companies with a secure RELOADABLE schema.

[orubel]

and BTW, you can separate what you need for an intial handshake but you can't separate what you need for basic RBAC association with endpoints (as pointed out above). Every service would need to handle the rolecheck with the data check at the same time not separately... else errors or privilege escalation can occur (ie. excess data sent unchecked or returned unchecked - see OWASP API3:2019 )

Example: gateway checks your role and lets you in, but role is not associated with endpoint so it give generic endpoint call (which does not differentiate between USER/ADMIN). This could cause client to send too much data to server and server to return too much data to client per OWASP API3:2019

[MikeRalphson]

As a result of #2604 the filename for this proposal should change to use a dated prefix. Please could you update this PR to match? Apologies for the extra work.

[whitlockjc]

A few notes after presenting this to the Security SIG:

• I could see a case where the Credential Object might also allow for a credential property in place of a credentials property.
• I could see a case where OAS might have some pre-defined credential (or credential formats, like HTTP Auth)
• There may be a case where we might need to allow for more JWT claims described for the jwt Security Scheme (I know on the backend this could be useful but seeing as this isn't the intent, I am not sure there is a case for this but it came up in the meeting so we'll wait for examples.)

[kinlane]

I have republished @whitlockjc proposal within the security SIG, and copied the conversation thread from here over to an issue. We are going to work on the proposal over there in the security SIG repo, and when ready republish here as a formal proposal.

[whitlockjc]

I've dropped the ball on this, but since it's never been reasoned about, what should we do here?

[handrews]

Filed #3257 to revive and clarify our proposals process. Once we figure it out, we'll resolve this PR accordingly.

[darrelmiller]

Closing because the conversation is now happening in Moonwalk discussions https://github.com/OAI/sig-moonwalk/discussions/46