GraphQL Schema Validation

GraphQL schema validation reduces the attack surface of GraphQL endpoints by ensuring that only requests matching the intended schema are accepted. Airlock Microgateway validates GraphQL traffic at the edge against a defined schema and blocks queries that violate it. This makes GraphQL APIs more resilient to malformed, undocumented, or malicious requests, improves consistency between clients and services, and helps detect integration errors early. It also lets you control whether introspection and mutations are allowed, so GraphQL endpoints expose only the operations intended for use. GraphQL queries, variables, and operation names can be extracted from either HTTP query parameters or JSON request bodies.

Prerequisites

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

Configuration

This section describes all configuration aspects covered by the CR GraphQL. Note that the CR Limits defines restrictions for GraphQL queries as well as general JSON limits and parameter lengths. These settings affect how GraphQL requests are handled. In addition, GraphQL query field values are subject to the settings in the CR DenyRules, which may also affect request processing.

Create a ConfigMap resource

Prepare your GraphQL schema.
Notice
The schema must be compatible with the GraphQL schema definition (Oct. 2021). Introspection and mutation queries are supported.
Create a Kubernetes ConfigMap and store the schema under the key schema.graphql.

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-graphql-schema> --from-file=./schema.graphql

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 schema.graphql.zst schema.graphql

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

To compress with gzip, do the following:

Terminal box

gzip -c schema.graphql > schema.graphql.gz

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

To compress with zip, do the following:

Terminal box

zip schema.graphql.zip schema.graphql.json

kubectl apply -f - <<EOF
apiVersion: v1
kind: ConfigMap
metadata:
  name: <your-graphql-schema>
binaryData:
  openapi.json: $(base64 < ./schema.graphql.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 a GraphQL resource

Create a GraphQL that references the ConfigMap with the GraphQL schema and defines how violations are handled (e.g. Block or LogOnly). Introspection and mutations can optionally be allowed.

Example

apiVersion: microgateway.airlock.com/v1alpha1
kind: GraphQL
metadata:
  name: <your-graphql>
spec:
  settings:
    threatHandlingMode: Block
    allowIntrospection: false
    allowMutations: true
    schema:
      source:
        configMapRef:
          name: <your-graphql-schema>

Create an APIProtection resource

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

Example

apiVersion: microgateway.airlock.com/v1alpha1
kind: APIProtection
metadata:
  name: <your-api-protection>
spec:
  policies:
    - name: GraphQL endpoint
      requestConditions:
        path:
          matcher:
            prefix: /graphql
      graphQLRef:
        name: <your-graphql>

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>

Troubleshooting

Invalid schema

If the provided GraphQL schema is invalid (e.g., due to syntax errors), the following will occur:

The Microgateway Engine logs an error in the application log.
GraphQL validation fails.
Requests are blocked.

Application log:

Example

[2024–06–12 14:08:43.436][125742][critical][main] [external/envoy/source/server/server.cc:414] error initializing config '  /home/mgw/airlock/airlock–microgateway–engine/config/graphql.yaml': Failed to parse GraphQL configuration "graphql_config": schema parse error: Parse error at 1:16 
Unexpected `abc[Name]` 
Expected `:`