OpenAPI Specification Enforcement

OpenAPI specification enforcement helps reduce an API’s attack surface by ensuring that only requests and responses that match the intended contract are accepted. Instead of relying solely on backend services to handle unexpected input, Airlock Microgateway validates traffic at the edge against a strict OpenAPI 3.0 definition. Requests that violate the specification are blocked. This makes APIs more resilient against malformed, undocumented, or malicious requests, improves consistency between producers and consumers, and helps detect integration errors early.

Prerequisites

A Gateway Deployment.
An HTTPRoute routes traffic to your application.

Configuration

This section shows how to configure Airlock Microgateway to enforce an OpenAPI specifiation.

Create a ConfigMap resource

Prepare your OpenAPI 3.0 specification in JSON format.
Notice
Specifications in other formats/versions (e.g., Swagger 2.0) must be converted before use. For Swagger-to-OpenAPI conversions, we recommend the Mermade converter, which is available as a command-line tool.
Create a Kubernetes ConfigMap and store the spec under the key openapi.json:

As plaintext JSON in data if the file size does not exceed the Kubernetes ConfigMap size limit (1 MiB)

Terminal box

kubectl create configmap <your-openapi-api-spec> --from-file=./openapi.json

As compressed (ZSTD, GZIP, or ZIP) and base64-encoded JSON in binaryData if the file size exceeds the Kubernetes ConfigMap size limit (1 MiB)
To compress with zsdt, do the following:

Terminal box

zstd -o openapi.json.zst openapi.json

kubectl apply -f - <<EOF
apiVersion: v1
kind: ConfigMap
metadata:
  name: <your-openapi-api-spec>
binaryData:
  openapi.json: $(base64 < ./openapi.json.zst | tr -d '\r\n')
EOF

To compress with gzip, do the following:

Terminal box

gzip -c openapi.json > openapi.json.gz

kubectl apply -f - <<EOF
apiVersion: v1
kind: ConfigMap
metadata:
  name: <your-openapi-api-spec>
binaryData:
  openapi.json: $(base64 < ./openapi.json.gz | tr -d '\r\n')
EOF

To compress with zip, do the following:

Terminal box

zip openapi.zip openapi.json

kubectl apply -f - <<EOF
apiVersion: v1
kind: ConfigMap
metadata:
  name: <your-openapi-api-spec>
binaryData:
  openapi.json: $(base64 < ./openapi.json.zip | tr -d '\r\n')
EOF

Notice

Using binaryData increases operational overhead. Microgateway must decode base64 and decompress the content, which adds CPU and memory usage and startup time.

Use compression only when the uncompressed file would exceed the ConfigMap size limit.

Create an OpenAPI resource

Create an OpenAPI that references the ConfigMap with the OpenAPI specification and defines how violations are handled (e.g., Block or LogOnly). Response validation is optional and can be enabled explicitly.

Example

apiVersion: microgateway.airlock.com/v1alpha1
kind: OpenAPI
metadata:
  name: <your-openapi-api>
spec:
  settings:
    schema:
      source:
        configMapRef:
          name: <your-openapi-api-spec>
    threatHandlingMode: Block
  response:
    unsecured: {}

Create an APIProtection resource

Create an APIProtection that applies based on the path which OpenAPI schema must be applied.

Example

apiVersion: microgateway.airlock.com/v1alpha1
kind: APIProtection
metadata:
  name: <your-api-protection>
spec:
  policies:
    - name: <your-rest-api-exception>
      requestConditions:
        path:
          matcher:
            prefix: /rest/no-validation
      noValidation: {}
    - name: <your-rest-api>
      requestConditions:
        path:
          matcher:
            prefix: /rest
      openAPIRef:
        name: open-api-example

Use noValidation: {} to configure validation exceptions for certain paths.

Create or extend a ContentSecurityPolicy resource

Create or extend a ContentSecurityPolicy that targets your HTTPRoute and refers to APIProtection.

Example

apiVersion: microgateway.airlock.com/v1alpha1
kind: ContentSecurityPolicy
metadata:
  name: <your-content-security-policy>
spec:
  targetRefs:
    - group: gateway.networking.k8s.io
      kind: HTTPRoute
      name: <your-webapplication>

  secured:
    apiProtectionRef:
      name: <your-api-protection>

Logging

Access log

Requests that violate the OpenAPI specification are logged in the Airlock Microgateway access log, just like any other blocked request.

Empty OpenAPI specification

If an empty OpenAPI specification is configured, all affected requests are rejected and the access log contains the message OpenAPI schema is empty.

Application log

If problems occur in the configured OpenAPI specification, details are written to the Airlock Microgateway application log.

Syntax errors

If the OpenAPI specification cannot be parsed, error messages are logged with details about the issue.

Examples:

Example

Failed to parse OpenAPI configuration "<OpenAPI–reference–name>": JSON parse error: Missing a name for object member. offset 36

Example

Failed to parse OpenAPI configuration "<OpenAPI–reference–name>": JSON parse error: Missing a comma or '}'...

Example

Failed to parse OpenAPI configuration "<OpenAPI–reference–name>": Expected key "in" not found $.paths./WebApplication.post.parameters[0]

Notice

If the Microgateway was initially configured and an invalid OpenAPI specification is applied, the Microgateway Engine container rejects the new configuration and continues to use the previous valid one.

If the Microgateway Engine container is restarted in this state, it will fail to start. This affects all services, including those not configured with an OpenAPI specification.

Unsupported features

If the OpenAPI specification contains unsupported features, the following log message is written.

Example:

Example

Unsupported feature in OpenAPI configuration "<OpenAPI–reference–name>": Content-type "application/xml" is not supported. Therefore content with this content-type will pass unfiltered. $.paths./TestServlet.post.requestBody.content.application/xml

Notice

The OpenAPI specification is enforced even if it contains unsupported features.

Only the unsupported features are ignored (fail-open); all other parts of the specification remain enforced.

Limitations

The Microgateway OpenAPI implementation currently does not support the follwing features:

OpenAPI version other than 3.0
OpenAPI schemas in YAML format
Multipart requests
Callback definitions
For requests with form-urlencoded parameters, additionalProperties is only supported as a boolean
XML and YAML content types (passed unchecked even if specified in a schema)