Swagger - Adding multiple security parameters to the same schema definition

Question

Aim

To include multiple security headers to every request made within the API

Problem

I am trying to add multiple headers to my Swagger YAML security definitions. I have trawled though the API but not have alot of luck But am finding that when making the 'Try-This-Operation' I am required to select one. Rather than able to use both. Is this correct or am I doing something incorrectly?

Snippet

securityDefinitions:
  userEmail:
    type: apiKey
    name: User Email
    in: header
  clientId:
    type: apiKey
    name: Client Id
    in: header

security: [ { userEmail: [], clientId: []  } ]

Alternative?

If I am trying to do this impossible ... Is it possible to specify these parameters as default for all the rest paths within the swagger document?

I am new to Swagger this week any have found everything else without problem ... but I cannot find any good example of this.

If any guidance could be given that would be incredibly helpful Many thanks

Answer 1

Your SecurityDefintions object looks ok. Beware that

security: [ { userEmail: [], clientId: []  } ]

means the API client MUST use userEmail authentication AND clientId authentication at once! You probably meant:

security: [ { userEmail: [] }, { clientId: []  } ]

which means the API client MUST use either userEmail authentication OR clientId authentication.

To avoid repeating this definition over and over again you can use the global security property that applies to all paths without their own security object:

security: [ { userEmail: [] }, { clientId: []  } ]
paths:
  "/foo":
    get:
    post:

or make use of a reference for explicitness or for multiple common values:

paths:
  "/foo":
    get:
      security:
        "$ref": "#/definitions/lowSecurity"
    post:
      security:
        "$ref": "#/definitions/highSecurity"
definitions:
  lowSecurity:  [ { foo: [] }, { bar: []  } ]
  highSecurity: [ { foo: [] } ]

Reference

The Swagger2 specification states under Operation Object:

security: [Security Requirement Object]

A declaration of which security schemes are applied for this operation. The list of values describes alternative security schemes that can be used (that is, there is a logical OR between the security requirements). This definition overrides any declared top-level security. To remove a top-level security declaration, an empty array can be used.

The Security Requirement Object is described like this:

Lists the required security schemes to execute this operation. The object can have multiple security schemes declared in it which are all required (that is, there is a logical AND between the schemes).

The name used for each property MUST correspond to a security scheme declared in the Security Definitions.

Answer 2

OAS 3: https://swagger.io/docs/specification/authentication/

Using Multiple Authentication Types

Some REST APIs support several authentication types. The security section lets you combine the security requirements using logical OR and AND to achieve the desired result. security uses the following logic:

security:    # A OR B
  - A
  - B

security:    # A AND B
  - A
    B

security:    # (A AND B) OR (C AND D)
  - A
    B
  - C
    D