Custom Resource Definitions

The CR AccessControl specifies the options to perform access control with a Microgateway Engine container.

Token introspection:
An introspection strategy (always or random) can be configured to check the validity of non–expired OIDC tokens. We recommend using the strategy always to check the token validity with each request. Note that this strategy consumes more system resources but provides the highest level of security.

The CR AccessControlPolicy is a Direct Attached Policy for the K8s Gateway API. It specifies the options to perform access control with an Airlock Microgateway.

Token introspection:
An introspection strategy (always or random) can be configured to check the validity of non–expired OIDC tokens. We recommend using the strategy always to check the token validity with each request. Note that this strategy consumes more system resources but provides the highest level of security.

The CR APIProtection contains the configuration for API security.

The CR ContentSecurity specifies the options to secure an upstream web application with a Microgateway Engine container. It does so by referencing various other CRs that cover different aspects of web application security.
If references are not explicitly configured, default settings designed to work with most upstream services will be applied.

The CR ContentSecurityPolicy is a Direct Attached Policy for the K8s Gateway API. It specifies the options to secure an upstream web application with a Microgateway. It does so by referencing various other CRs that cover different aspects of web application security.

The CR CSRFProtection provides the configuration options for cross-site request forgery (CSRF) protection.

The CR DenyRules configures request filtering using Airlock built-in and custom deny rules. Deny rules establish a negative security model. They define prohibited patterns that, when a match is found in a request, lead to it being blocked from reaching the upstream web application.

Different security levels can be configured on global and deny rule levels. This makes it possible to configure the balanced processing of requests with a high level of security and a low number of false positives simultaneously.

Override global settings for specific deny rules
For fine–tuning, i.e., to reduce the number of false positives, the security level or the threat handling mode for individual deny rules may be configured differently from the global settings. To do so, configure non–global security levels for deny rules using the ruleKeys or the types element.

Deny rule exceptions
Deny rule exceptions can be defined for different data elements.

Note that exceptions will only reduce blocks if the configured exception covers all data elements that trigger deny rules.

For example, if an exception is configured to unblock search parameters, a request containing a search and a language parameter could still be blocked if the language parameter triggers a deny rule. The same mechanism applies to other blocked data elements such as parameters, headers or JSON data.

Deny rule exceptions for JSON content
Body data of requests with content–type header application/json are parsed as JSON content and might cause false positives. Deny rule exceptions can be defined for JSON keys or values based on the access log information. Additionally, exceptions can be restricted to a defined JSONPath. In the JSONPath expressions, wildcards (*) can be used, like in this JSONPath syntax reference.

Example:

{ 
  "books": [ 
    { 
      "title": "DevSecOps Starters Guide", 
      "author": "Joe Bloggs", 
      "stars": 723 
    }, 
    { 
      "title": "JSONPath for Geeks", 
      "author": "Jane Smith", 
      "stars": 27 
    } 
  ] 
}

This JSON example contains 6 key–value pairs (aka leaves), 3 pairs for each book. The values of the JSON leaves can be filtered with the corresponding JSONPath from the following table.

JSONPath          | Value 
––––––––––––––––––|–––––––––––––––––––––––––––– 
$.books[0].title  | "DevSecOps Starters Guide", 
$.books[0].author | "Joe Bloggs", 
$.books[0].stars  | 723 
$.books[1].title  | "JSONPath for Geeks", 
$.books[1].author | "Jane Smith", 
$.books[1].stars  | 27

For instance, an exception for all books of authors named Joe can be configured as follows.

Example:

apiVersion: microgateway.airlock.com/v1alpha1
kind: DenyRules
metadata:
  name: my–webapp
 spec: 
  request: 
    builtIn:
      exceptions: 
        – blockedData: 
            json: 
              jsonPath: $.books[*].author 
              value: 
                matcher: 
                  contains: Joe

Custom deny rules
Custom deny rules can be configured to complement the built–in deny rules.

The CR EnvoyCluster is an additional Envoy Cluster resource that is added to those defined by the Airlock Microgateway. The CR allows configuring additional clusters if a native Envoy HTTP filter relies on it. For the CR EnvoyCluster, the Envoy configuration language must be used.
For an example targeting debugging, see article Debugging with Envoy filters.

The CR EnvoyConfiguration is the schema for the Envoy configurations API.

The CR EnvoyHTTPFilter is an additional Envoy HTTP Filter resource that is added to those defined by the Airlock Microgateway. If a feature is available as a native Envoy HTTP filter but is missing in the Microgateway CRs, the CR EnvoyHTTPFilter can be used to prepend the native Envoy HTTP filter. For the CRs EnvoyHTTPFilter and EnvoyCluster, the Envoy configuration language must be used.
For an example targeting debugging, see article Debugging with Envoy filters.

The CR GatewayParameters defines the configuration settings for deploying a Gateway in Kubernetes, including options for logging, service type, deployment strategy, and resource management.

apiVersion: gateway.networking.k8s.io/v1
kind: GatewayClass
metadata:
  name: airlock–microgateway
  namespace: airlock–gateway 
spec:
  controllerName: microgateway.airlock.com/gatewayclass–controller
  parametersRef:
    group: microgateway.airlock.com
    kind: GatewayParameters
    name: airlock–microgateway 
    namespace: airlock–gateway

apiVersion: gateway.networking.k8s.io/v1
kind: Gateway
metadata:
  name: gateway–secure
  namespace: airlock–gateway
spec:
  gatewayClassName: airlock–microgateway
  listeners:
  – name: http–listener
    protocol: HTTP
    port: 80
  infrastructure:
    parametersRef:
      group: microgateway.airlock.com
      kind: GatewayParameters
      name: airlock–microgateway 
      namespace: airlock–gateway  

The CR GraphQL allows referencing a GraphQL schema resource. The schema of this ConfigMap resource must be compatible with GraphQL schema definition (Oct. 2021). Introspection and mutation queries are supported.

Not all configurational aspects of GraphQL–related traffic are configured in the CR GraphQL. Even without a referenced schema, CR DenyRules and CR Limits settings are applied to query requests and can be configured to block or restrict them.

GraphQL queries are identified with parameters and keys and must match the parser's requirements – see CR Parser.

In case of a problem, such as an error in the referenced GraphQL schema, Airlock Microgateway logs information in the 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 `:`

The CR HeaderRewrites is the Schema for the header rewrites API.

With the configuration options, request and response headers can be added to or removed from upstream and downstream traffic.

The content of this CR is split into two main sections request and response. Both sections can be complemented with custom rules.

The following actions can be configured for both built–in and custom rules:

Logging
Header rewrite actions are not displayed in the access log by default. The CR HeaderRewrites features an Integration operation mode that enriches the access log output with information and details not logged in Production mode. The additional log information are useful for application integration and fault–finding tasks, i.e., to discover potential header–related issues.

Note that the extended logging output of the Integration mode results in larger log messages and requires more storage.

Example log output in Integration mode:

   "airlock": { 
    "header_rewrites": { 
      "response": [ 
        { 
          "headers": [ 
            "content–type" 
          ], 
          "type": "remove–rule", 
          "applied_rules": [ 
            "Remove Content Type Response Header" 
          ], 
          "action": "remove" 
        } 
      ], 
      "request": [ 
        { 
          "type": "allow–rule", 
          "applied_rules": [ 
            "Standard Allowed Request Headers", 
            "Allow custom request headers", 
            "Propagate X–Forwarded–For to upstream" 
          ], 
          "action": "remove", 
          "headers": [ 
            "front–end–https", 
            "x–forwarded–host", 
            "x–forwarded–port", 
            "x–forwarded–proto", 
            "x–forwarded–server", 
            "x–real–ip", 
            "accept–encoding" 
          ] 
        } 
      ] 
    },

The CR IdentityPropagation specifies how the identity of the authenticated user is propagated from the Microgateway Engine to the back–end. For example, it is possible to set a header containing an OIDC idToken claim.

The CR JWKS provides the configuration for JSON Web Key Set providers and endpoints, including certificate verification settings.

The CR JWT configures client authentication via a JSON Web Token.

Airlock Microgateway performs various size checks on requests with a default configuration to repel denial of service (DoS) attacks. The CR Limits can be used to configure these limit checks on the root level. All limits are calculated in bytes.

Size limits like bodySize, nameLength , etc., can be specified in bytes or Kubernetes memory limit units.

Threat handling mode settings
When a request causes a block due to reaching the request size limit in Block mode, it is possible that the total request size is not fully logged. For example, it can happen that the actual parameter name length is not part of the logging information because the request size limit has already been reached before and the request is already blocked. This behavior is to mitigate the risk of being vulnerable to DoS attacks.

The logs may vary depending on the settings.threatHandlingMode. In Block mode, only the available information is logged to still protect against denial of service attacks. This could lead to some information being missing whereas in LogOnly mode, all limits–related information is logged.

The following examples show two types of limit violations, body size and JSON key length, in both threat–handling modes.
As expected, the body.size value is not shown in Block mode in opposition to the JSON key.length value (which requires parsing the JSON body for length calculation).

# body size, block 
 
    "limits": { 
      "matches": [ 
        { 
          "blocked_data": { 
            "body": {} 
          }, 
          "rule": "Built–in: Request body size", 
          "threat_handling_mode": "block" 
        } 
      ] 
    },

# body size, logOnly 
 
    "limits": { 
      "matches": [ 
        { 
          "blocked_data": { 
            "body": { 
              "size": 219 
            } 
          }, 
          "rule": "Built–in: Request body size", 
          "threat_handling_mode": "logOnly" 
        } 
      ] 
    },

# JSON key length, block 
 
    "limits": { 
      "matches": [ 
        { 
          "blocked_data": { 
            "json_key": { 
              "json_path": "$['username']", 
              "key": "username", 
              "length": 12 
            } 
          }, 
          "rule": "Built–in: JSON key length", 
          "threat_handling_mode": "block" 
        } 
      ] 
    },

# JSON key length, logOnly 
 
    "limits": { 
      "matches": [ 
        { 
          "blocked_data": { 
            "json_key": { 
              "json_path": "$['username']", 
              "key": "username", 
              "length": 12 
            } 
          }, 
          "rule": "Built–in: JSON key length", 
          "threat_handling_mode": "logOnly" 
        } 
      ] 
    }, 

The article Access log field reference provides additional information listing all log fields including short descriptions.

Limit–based block and attack types in logs and metrics
In addition to the obvious block type limits, limit–based blocks (or potential blocks in LogOnly mode) can occur based on other Microgateway features that also make use of the configured limits and appear in logs and metrics. All configured limit types can trigger a single request block or multiple potential blocks in LogOnly mode.

For example, Airlock Microgateway Engine metrics can contain the following metric labels:

microgateway_http_downstream_rq_threats_blocked_total{block_type="graphql", attack_type="parameter_body_size", envoy_cluster_name="YourClusterName"}

The metrics block count in the example above has been triggered by a graphql query in a JSON body exceeding the parameter_body_size limit. The label metrics naming is closely related to the CR Limits configuration for intuitive understanding. For example, if a request exceeds the request.limited.general.bodySize value, the corresponding metric label for attack types would be general_body_size.

The CR ODICProvider specifies an OpenID Connect Provider (OP), such as Airlock IAM, with the required authorization and token validation endpoints.

The CR OIDCRelyingParty specifies how the Airlock Microgateway Engine interacts with an OpenID Provider (OP) such as Airlock IAM.

The Secret requires the key client.secret for the password string as in the following example:

apiVersion: v1 
kind: Secret 
metadata: 
  name: oidc–client–secret 
stringData: 
  client.secret: "myClientSecret1234"

The CR OpenAPI contains the configuration for the OpenAPI specification.
Enforcing a tight OpenAPI specification reduces the attack surface significantly. HTTP requests and responses are checked against the OpenAPI specification and will be blocked in case of a violation.

Logging
In case of a problem in the configured OpenAPI specification, Airlock Microgateway logs information in the application log.

Feature scope and configuration options

The CR Parser contains the configuration for content parsers (default and custom).
Airlock Microgateway Engine parses the request body before applying filters (deny rules, limits, OpenAPI, GraphQL) to a request's content. The parser selection is based on the Content–Type header.

GraphQL query parsing
The parser can identify and parse GraphQL queries from different types of requests.

The parameter names/JSON keys are “query”, “variables” and “operationName”, where the former is required for GraphQL query identification.

The key “operationName” is used as an identifier for logging if present.

The CR RedisProvider contains a client configuration for connecting to a Redis database. For caching session handling information, a Redis database can be deployed within or outside the Microgateway cluster.

With tls: {} enabled only certificates which are signed by a CA that is trusted by any of the root CA certificates, built into the Microgateway Session Agent’s base image, are accepted until configured otherwise.

The CR SessionHandling contains the configuration for session handling and specifies the Redis database where sessions should be stored.

The CR SidecarGateway contains the configuration of how to configure the Airlock Microgateway Engine when used as a Sidecar Container within the Pod of an application.

The following example shows a simple CR SidecarGateway configuration.

Example Deployment:

apiVersion: apps/v1  
kind: Deployment  
metadata:  
  labels:  
    app: echo–server  
  name: echo–server  
spec:  
  selector:  
    matchLabels:  
      app: echo–server  
  template:  
    metadata:  
      annotations:  
        sidecar.microgateway.airlock.com/excludeInboundPorts: "9998,9999" 
        sidecar.microgateway.airlock.com/serviceMesh: "none" 
      labels:  
        sidecar.microgateway.airlock.com/inject: "true"  
        app: echo–server  
        version: 1.0.0
    spec:
      ...    

Example SidecarGateway:

apiVersion: microgateway.airlock.com/v1alpha1 
kind: SidecarGateway 
metadata: 
  name: sidecar–gateway–example 
spec: 
  podSelector: 
    matchLabels: 
      app: example–app 
  applications: 
    – containerPort: 5051
      routes: 
        – pathPrefix: / 
          secured: 
            contentSecurityRef: 
              name: content–security–example   

For more information, see also TLS secrets in Kubernetes.

For the default and a simple example configuration, see CR SidecarGateway reference documentation, spec.applications.downstream.tls or spec.applications.upstream.tls.

Client certificate settings for downstream mTLS
To secure access to the application with mutual TLS (mTLS), Airlock Microgateway needs to instruct clients to provide a valid client certificate during a TLS handshake. The exact behavior can be configured using the downstream.tls.clientCertificate option.

The following example shows available client certificate verification settings:

...
      downstream:
        tls:
          enable: true
          secretRef:
            name: server–cert–secret
          clientCertificate:
            required: 
              trustedCA:
                verificationDepth: 1
                certificates:
                  – secretRef:
                      name:  trusted–ca–secret 
              crl:
                validationMode: VerifyChain
                lists:                                   
                  – secretRef:
                      name: crl–secret  
              allowedSANs:
                – sanType: DNS
                  matcher: 
                    exact: "api.example.com"
                                            
              certificatePinning: 
                allowedHashes: 
                – a434460ca545...
                allowedSPKIs: 
                – seFTOlIPG28LywSNn6wbPqRiV6GRJ66z+0J0Cwt2lMQ=
... 

Use the following table as a starting point when configuring the Secret files required for mTLS.

apiVersion: v1
kind: Secret
metadata:
  name: trusted–ca–secret
data:
  ca.crt: <base64 encoded ca certificate>

apiVersion: v1
kind: Secret
metadata:
  name: crl–secret
data:
  ca.crl: <base64 encoded crl>

For the default and example configuration, see CR SidecarGateway reference documentation, spec.applications.downstream.tls.

HTTP protocol settings:
The HTTP protocol version used for downstream and upstream traffic is automatically selected by default based on the capabilities of upstream and downstream systems.

For the default and example configuration, see CR SidecarGateway reference documentation, spec.applications.downstream.protocol or spec.applications.upstream.protocol.

Downstream remote IP settings:
In Kubernetes/Openshift environments, it is extremely unlikely for an external client to have a direct connection to an application. Usually, requests pass through one or more reverse proxy layers, hiding the client's real IP address. Sometimes, the client remote IP is an input parameter to Microgateway features like deny rule exceptions based on a client IP range. Other times, it is simply important to log the correct client IP.

Therefore, the remoteIP settings define how the remote IP address of a client is identified.

For the default and example configuration, see CR SidecarGateway reference documentation, spec.applications.downstream.

Request normalization settings:
With the option requestNormalizations it is possible to transform the request path before it is matched or routed. See Envoy path transformation for more information.

For the default and example configuration, see CR SidecarGateway reference documentation, spec.applications.downstream.

Limiting request headers length:
The maximum size of the request header block, encompassing all headers and their values, can be restricted by setting a header length limit. Additional limits on requests can be configured in the CR Limits.

For the default and example configuration, see CR SidecarGateway reference documentation, spec.applications.downstream.restrictions.http.

Filtering:
By default, all traffic is filtered and secured using reasonable default security settings. However, with todays web applications consisting of different parts, for example HTML pages and REST APIs, with different requirements, specific security policies can be applied using CR ContentSecurity.

The CR Telemetry contains the configuration for telemetry (logging, metrics, and tracing).

The CR Telemetry can be used to customize the default log format of Airlock Microgateway.

The CR Telemetry reference documentation contains the default access log configuration and an example configuration. The default configuration can be used as a starting point for customization.

The access log format can be configured in the Envoy format dictionary style. Both command operators, standard Envoy command operators and Airlock Microgateway custom command operators, may be used in the configuration.

Log correlation:
The behavior of Airlock Microgateway Engine when receiving an x–request–id header can be configured with the keys allowDownstreamRequestID and alterRequestID under the setting correlation.request. These two settings allow configuring the booleans explained in Envoy UUID request id configuration.

The CR TokenExchange configures an OAuth Token Exchange (RFC 8693). This feature may be used when the upstream backend requires a different token than the downstream JWT or OIDC Access Token.

{
  "airlock": {
    "access_control": {
      "policy": "policy_name",
      "authenticated": true,
      "authorized": true,
      "type": "jwt",
      "user_id": "...",
      "status": "complete",
      "details": {
        "jwt": {
          "token": { ... },
          ...
        },
        "token_exchange": {
          "sequence": [
            { "type": "jwt", "iss": "...", "sub": "...", "cached": true }
          ]
        }
      }
    }
  }
}