Clarification about security requirements combination

[baywet]

Hi everyone,

Recently re-read the security requirements part of the spec which currently has this text:

Security Requirement Objects that contain multiple schemes require that all schemes MUST be satisfied for a request to be authorized.
This enables support for scenarios where multiple query parameters or HTTP headers are required to convey security information.

When a list of Security Requirement Objects is defined on the OpenAPI Object or Operation Object, only one of the Security Requirement Objects in the list needs to be satisfied to authorize the request.

It seems to me those two statements are contradicting each other. Let's take an example if we have security schemes A and B defined the the component section. And an Operation that references both.

Does the request need to satisfy A AND B (first statement) or A OR B (second statement) ?

#4082 doesn't seem to change anything with that as of this writing.
And it seems we've had many questions about that in the past: #3236 #1216 #771 and many more.

From reading other issues I believe what's meant here is that "first level entries are OR, nested entries are AND", for lack of better wording.

I thought that since we're close to a patch release, we might take the chance to clean this one up as well.

[maisarissi]

It seems to me those two statements are contradicting each other. Let's take an example if we have security schemes A and B defined the the component section. And an Operation that references both.

Does the request need to satisfy A AND B (first statement) or A OR B (second statement) ?

I would say, depends on how the OpenAPI was specified. My understand was:

• A AND B

paths:
  /example:
    get:
      summary: Example endpoint
      description: This endpoint demonstrates the use of multiple OAuth2 flows.
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: Hello, world!
      security:
        - OAuth2:
            - read
          ApiKeyAuth: []

A OR B:

paths:
  /example:
    get:
      summary: Example endpoint
      description: This endpoint demonstrates the use of multiple OAuth2 flows.
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: Hello, world!
      security:
        - OAuth2:
            - read
        - ApiKeyAuth: [] ##here is the difference

Per what I could understand, the latter is saying we can use OAuth2 OR ApiKey, as opposite to the former, which requires both.

[darrelmiller]

@maisarissi Exactly. The first is an array of one security requirement object that contains references to two schemes. The second is an array of two security requirement objects where each one has just one scheme.

Maybe we can figure out a way to fix this in moonwalk because it confuses EVERYONE.

[baywet]

Thanks for joining the discussion here. While the representation is super tedious and could be improved in Moonwalk, my initial concern was mostly about making the second statement clearer in the patch release to at least try address some of the confusion in the meantime.

[miqui]

@baywet Here are some more examples: https://swagger.io/docs/specification/v3_0/authentication/

Can you take these examples and propose how would you describe the OR and AND cases , so that they are less confusing ?

[baywet]

What do you think of this?

A Security Requirement Object MAY refer to multiple security schemes in which case all schemes MUST be satisfied for a request to be authorized.

When the security field is defined on the OpenAPI Object or Operation Object and contains multiple Security Requirement Objects, only one of the entries in the list needs to be satisfied to authorize the request.

And if we want it to me more verbose I'd add this back to the first paragraph:

This enables support for scenarios where multiple query parameters or HTTP headers are required to convey security information.

But also add that to the second

This enables support for scenarios where the API supports alternative security schemes, or when they are optional.

[LasneF]

i just closed , but mentionned those 2 oldies (6+years old) , the #1698 looks overkill , and for now lets keep on the scope mentionned there

[miqui]

Vincent : PR for 3.1.1

[baywet]

Created the PR #4123