External authorization

The external authorization session filter calls an external authorization service when a new UDP session is established, to check whether the session is authorized. The session’s downstream source and destination addresses are sent as the source and destination peers of the request. If the session is denied, it is dropped and no upstream is created.

The filter uses the gRPC Authorization API defined by CheckRequest. A failed check, or an error when failure_mode_allow is not set, causes the session to be dropped.

By default, datagrams that arrive while the authorization call is in flight are dropped. Configuring buffer_options enables buffering of those datagrams, which are then replayed if the session is allowed.

Note

This filter authorizes a session by its source and destination addresses only and does not inspect datagram contents. It is not intended to authorize DNS requests, since the DNS query is not made available to the authorization service.

This filter should be configured with the type URL type.googleapis.com/envoy.extensions.filters.udp.udp_proxy.session.ext_authz.v3.FilterConfig.
v3 API reference

Authorization request

The CheckRequest is populated from the session’s addresses:

CheckRequest field	Value
`attributes.source.address.socket_address`	Downstream source IP and port.
`attributes.destination.address.socket_address`	Local address the datagrams were received on.

Authorization response

The session outcome is taken from the CheckResponse:

an OK status allows the session.
a denied response (non-OK status, no error_response) drops the session.
an error (a gRPC failure or timeout, or a response carrying an error_response) drops the session unless failure_mode_allow is set.

Statistics

Every configured filter has statistics rooted at udp.session.ext_authz.<stat_prefix>. with the following statistics:

Name	Type	Description
ok	Counter	Number of sessions allowed by the authorization service
denied	Counter	Number of sessions denied by the authorization service
error	Counter	Number of errors contacting the authorization service
failure_mode_allowed	Counter	Number of sessions allowed on error due to failure_mode_allow
total	Counter	Total number of authorization checks issued
buffer_overflow	Counter	Number of datagrams dropped while waiting for the authorization response due to the buffer being full
active	Gauge	Number of authorization checks currently in flight