Section OpenAPI Specification

Section - OpenAPI API Security

Prerequisites

  • OpenAPI validation requires a license for the API Gateway feature.
  • API specification format must be in OpenAPI version 3.0 as JSON. Specifications in other formats or versions, e.g., Swagger 2.0, must be converted before uploading. For Swagger to OpenAPI conversions, we recommend the Mermade converter which is available as a command-line tool.

OpenAPI configuration

After uploading the OpenAPI specification, configure and enable Enforce API validation for a mapping on the mapping detail page, Tab – API Security.

  • The OpenAPI filter supports the following validating parameters:
  • path
  • query
  • header
  • cookie

    • All data types and their constraints, such as enum, pattern, format, value ranges, and length ranges are supported. Body content checks are only applied to JSON documents and binary data.

  • The following OpenAPI features are currently not supported:
  • Content-Types other than JSON
  • Multipart requests
  • Callbacks

Logging

  • Logging during request handling:
  • WR-SG-BLOCK-115-00 – Noncompliant API usage
    • constraint – provides detailed information on the violated constraint.
    • position – denotes the position in the validated request document/parameter where a constraint was violated.
  • WR-SG-REJECT-115 – OpenAPI configuration is invalid
    • The configuration could not be loaded correctly. See CONF-115 entries in the log messages for investigation and error analysis.
  • Logging by the configuration loader:
  • SY-SG-CONF-115-00 – Config Loader: Error parsing OpenAPI specification
    • file – filename of the document where the error occurred
    • position – denotes the position in the specification where the error was found
  • SY-SG-CONF-115-01 – Config Loader: Unsupported OpenAPI feature
    • file – filename of the document where the error occurred
    • position – denotes the position in the specification where the error was found
    • SY-SG-CONF-115-02 – Config Loader: Error compiling pattern for OpenAPI string format
    • SY-SG-CONF-115-03 – Config Loader: Error compiling pattern for OpenAPI Content-Type matching

Expert settings

​Expert settings control certain aspects of the OpenAPI validation:

Expert Setting Key

Description

OpenApi.StringFormat.*

Patterns for custom value formats referenced by name in specifications.

OpenApi.Authentication.*

Positive-listed parameters for OAuth2 and OpenID Connect security schemes.

OpenApi.Check.Response

Enable or disable the response check (default false).

OpenApi.ContentType.*

List of Content-Type patterns.

Request.Json.Limits.*

Thresholds for preventing DoS attacks against the JSON parser.