Security #

Swagger Security #

In Swagger a top-level securityDefinitions object can define multiple authentication types or security schemes. Each of those security schemes must have a type property denoting its type.

FLAT supports the type basic for Basic Authentication as well as the type apiKey for Bearer Authentication. OAuth 2 Authorization with type oauth2 is currently not supported.

The following example defines the two security schemes BasicAuth and BearerAuth:

securityDefinitions:
  BasicAuth:
    type: basic
    …
  BearerAuth:
    type: apiKey
    …

Once defined, the security schemes can be referenced via the security property in order to apply them to your API. You can apply them to the whole API (security property at top-level), to a specific path (security directly below an endpoint definition), or even more specific to a single operation (security below an HTTP method identifier within an endpoint). More specific security schemes, defined deeper in the structure, override less specific ones defined at higher levels.

📎 Endpoint specific security is one of FLAT’s Swagger extensions.

The security property is an array of objects, where each of the object’s property names corresponds to one of the defined security schemes. All security schemes referenced within an object must be satisfied at the same time (logical AND). Multiple items in the array can be used to offer alternative security schemes (logical OR). An empty array [] means no authentication (→ Swagger’s authentication documentation):

swagger: "2.0"

security:                 # ← top level: Basic authentication for the whole API
  - BasicAuth: []
paths:
  /health:
    security: []          # ← endpoint: no authentication for /health
    …
  /info:
    security:             # ← endpoint: /info requires Basic OR Bearer authentication
      - BearerAuth: []
      - BasicAuth:  []
    …
  /login:
    post:
      security:           # ← endpoint/operation: POST /login requires both forms (AND)
        - BearerAuth: []
          BasicAuth:  []
      …

securityDefinitions:
  …

Defining Security Schemes #