External Processing Policy

Policy Name

External Processing

Summary

Sends the incoming HTTP requests or outgoing HTTP responses requests to an external gRPC service for additional processing

Category

Transformation

First Flex Gateway version available

v1.6.0

Returned Status Codes

403 - IP is rejected

Summary

The External Processing policy forwards the incoming HTTP request or outgoing HTTP response to an external gRPC service to modify the headers, trailers, body, or any combination of the three. You can also configure this policy to process either the request, response, or both.

Additionally, the external processing service can request different parts of the HTTP request or response after the initial gRPC request was sent by Flex Gateway to the external processing server. This enables you to send the minimum amount of data necessary. For example, Flex Gateway can initially send only the HTTP requests headers. Then, after some processing, the external processor can request the HTTP request body or trailers from Flex Gateway.

The parameters you set for sending the HTTP headers, trailers, and body only configure what is initially sent. The external processing service has access to all parts of the HTTP request or response regardless of what is configured. Configure the parameters to send all of the information that the processing service needs for every incoming HTTP request or response. For example, if the processing service needs the headers for every request but only needs the body for some of the requests, depending on the information found in the header, only configure the parameters to send the headers.

The External Processing policy is an extension of the External Processing filter native to Envoy. To learn more about the External Processing filter, see External Processing Filter. Not all External Processing filter parameters are available for the External Processing policy. To find what parameters are configurable, see Configuring Policy Parameters.

If other policies modify the HTTP request or response, ensure that you order the policies depending on if these modification should be present when the request is sent to the processing service or upstream service. For more information about ordering policies, see Ordering Policies.

Configuring Policy Parameters

Flex Gateway Local Mode

In Local Mode, you apply the External Processing policy to your API instance via declarative configuration files. Refer to the following policy definition and table of parameters:

- policyRef:
    name: native-ext-proc-flex
  config:
    uri: <string> // REQUIRED
    messageTimeout: <integer> // OPTIONAL
    requestHeaderMode: <string> // REQUIRED, default: "send"
    responseHeaderMode: <string> // REQUIRED, default: "send"
    requestBodyMode: <string> // REQUIRED, default: "none"
    responseBodyMode: <string> // REQUIRED, default: "none"
    requestTrailerMode: <string> // OPTIONAL, default: "send"
    responseTrailerMode: <string> // OPTIONAL, default: "send"

Parameter Required or Optional Default Value Description

Parameter	Required or Optional	Default Value	Description
`uri`	Required	NA	External processing server URI. For gRPC type servers, define the URI as `\h2://<ext.authz.com>:<port>`.
`messageTimeout`	Required	`1000`	Message timeout for the processing server in milliseconds.
`requestHeaderMode`	Required	`send`	Whether the HTTP requests headers are sent to the processing service. Supported values are `send` and `skip`.
`responseHeaderMode`	Required	`send`	Whether the HTTP response headers are sent to the processing service. Supported values are `send` and `skip`.
`requestBodyMode`	Required	`none`	Mode that the HTTP request body is sent in. Supported values are `none`, `streamed`, `buffered`, and `bufferedPartial`. Selecting `none` does not send the request body.
`responseBodyMode`	Required	`none`	Mode that the HTTP response body is sent in. Supported values are `none`, `streamed`, `buffered`, and `bufferedPartial`. Selecting `none` does not send the request body.
`requestTrailerMode`	Required	`send`	Whether the HTTP requests' trailer headers are sent to the processing service. Supported values are `send` and `skip`.
`responseTrailerMode`	Required	`send`	Whether the HTTP response trailer headers are sent to the processing service. Supported values are `send` and `skip`.

uri

Required

External processing server URI. For gRPC type servers, define the URI as \h2://<ext.authz.com>:<port>.

messageTimeout

Required

1000

Message timeout for the processing server in milliseconds.

requestHeaderMode

Required

send

Whether the HTTP requests headers are sent to the processing service. Supported values are send and skip.

responseHeaderMode

Required

send

Whether the HTTP response headers are sent to the processing service. Supported values are send and skip.

requestBodyMode

Required

none

Mode that the HTTP request body is sent in. Supported values are none, streamed, buffered, and bufferedPartial. Selecting none does not send the request body.

responseBodyMode

Required

none

Mode that the HTTP response body is sent in. Supported values are none, streamed, buffered, and bufferedPartial. Selecting none does not send the request body.

requestTrailerMode

Required

send

Whether the HTTP requests' trailer headers are sent to the processing service. Supported values are send and skip.

responseTrailerMode

Required

send

Whether the HTTP response trailer headers are sent to the processing service. Supported values are send and skip.

Leaving a required value blank configures the parameter with the default value. No value is set for optional values left blank.

Resource Configuration Example

This configuration streams the request headers, trailers, and body to the external processing server. This configuration does not send any part of the response to the external processing server.

- policyRef:
    name: native-ext-proc-flex
  config:
    uri: h2://<ext.authz.com>:<port>
    messageTimeout: <integer> // OPTIONAL
    responseHeaderMode: skip
    requestBodyMode: streamed
    responseTrailerMode: skip

Flex Gateway Connected Mode

When you apply the External Processing policy to your API from the UI, configure the following parameters:

Parameter Description

Parameter	Description
External processing server URI	External processing server URI. For gRPC type servers, define the URI as `\h2://<ext.authz.com>:<port>`.
Message timeout	Message timeout for the processing server in milliseconds.
Request header processing mode	Whether the requests headers are sent to the processing service.
Response header processing mode	Whether the response headers are sent to the processing service.
Request body processing mode	Mode that the request body is sent in.
Response body processing mode	Mode that the response body is sent in.
Request trailer processing mode	Whether the requests trailers are sent to the processing service.
Response trailer processing mode	Whether the response trailers are sent to the processing service.

External processing server URI

External processing server URI. For gRPC type servers, define the URI as \h2://<ext.authz.com>:<port>.

Message timeout

Message timeout for the processing server in milliseconds.

Request header processing mode

Whether the requests headers are sent to the processing service.

Response header processing mode

Whether the response headers are sent to the processing service.

Request body processing mode

Mode that the request body is sent in.

Response body processing mode

Mode that the response body is sent in.

Request trailer processing mode

Whether the requests trailers are sent to the processing service.

Response trailer processing mode

Whether the response trailers are sent to the processing service.

How This Policy Works

The following diagram demonstrates the order in which requests and responses flow when the External Processing policy is applied:

80%

The client makes an HTTP request to Flex Gateway.
Flex Gateway forwards the initial parts of the client HTTP request that you configure to the external processing service. At this point, the external processing service can request additional parts of the request.
After Flex Gateway receives the modified HTTP request, Flex Gateway sends the HTTP request to the upstream API service.
Flex Gateway receives the HTTP response from the upstream API service and forwards the initial parts of the HTTP response that you configure to the external processing service. At this point, the external processing service can request additional parts of the HTTP response.
Flex Gateway returns the modified HTTP response from the external processing service to the client.

By default, if Flex Gateway cannot establish a connection to the gRPC service or if the gRPC service returns an error, the policy fails.

Envoy Policy Limitations

Policies that extend filters native to Envoy have certain monitoring limitations when running in connected mode.

Policy Violation Metrics

Envoy filter policies do not support the Policy Violations metric in either the API instance Key Metrics or Anypoint Monitoring. However, Envoy filter policies do support the Response Code metric.

Applying an Envoy filter policy does not affect the Policy Violations metrics for other policies applied to the API instance. Flex Gateway reports the Policy Violations metrics for non-Envoy filter policies as normal, but these metrics are incomplete as they do not include Envoy filter policy violations.

To learn more about Flex Gateway Metrics, refer to Viewing Key Metrics for Flex Gateway APIs.

API Alerts

Envoy filter policies do not support policy violation API alerts. To monitor an Envoy filter policy with an API alert, add an alert that monitors response codes and specify the response error code of your policy.

To learn more about adding alerts, refer to Using Flex Gateway API Alerts.