syntax = "proto3"; package envoy.extensions.filters.http.ext_authz.v3; import "envoy/config/common/mutation_rules/v3/mutation_rules.proto"; import "envoy/config/core/v3/base.proto"; import "envoy/config/core/v3/config_source.proto"; import "envoy/config/core/v3/grpc_service.proto"; import "envoy/config/core/v3/http_uri.proto"; import "envoy/type/matcher/v3/metadata.proto"; import "envoy/type/matcher/v3/string.proto"; import "envoy/type/v3/http_status.proto"; import "google/protobuf/struct.proto"; import "google/protobuf/wrappers.proto"; import "envoy/annotations/deprecation.proto"; import "udpa/annotations/sensitive.proto"; import "udpa/annotations/status.proto"; import "udpa/annotations/versioning.proto"; import "validate/validate.proto"; option java_package = "io.envoyproxy.envoy.extensions.filters.http.ext_authz.v3"; option java_outer_classname = "ExtAuthzProto"; option java_multiple_files = true; option go_package = "github.com/envoyproxy/go-control-plane/envoy/extensions/filters/http/ext_authz/v3;ext_authzv3"; option (udpa.annotations.file_status).package_version_status = ACTIVE; // [#protodoc-title: External Authorization] // External Authorization :ref:`configuration overview `. // [#extension: envoy.filters.http.ext_authz] // [#next-free-field: 30] message ExtAuthz { option (udpa.annotations.versioning).previous_message_type = "envoy.config.filter.http.ext_authz.v3.ExtAuthz"; reserved 4; reserved "use_alpha"; // External authorization service configuration. oneof services { // gRPC service configuration (default timeout: 200ms). config.core.v3.GrpcService grpc_service = 1; // HTTP service configuration (default timeout: 200ms). HttpService http_service = 3; } // API version for ext_authz transport protocol. This describes the ext_authz gRPC endpoint and // version of messages used on the wire. config.core.v3.ApiVersion transport_api_version = 12 [(validate.rules).enum = {defined_only: true}]; // Changes filter's behavior on errors: // // 1. When set to true, the filter will ``accept`` client request even if the communication with // the authorization service has failed, or if the authorization service has returned a HTTP 5xx // error. // // 2. When set to false, ext-authz will ``reject`` client requests and return a ``Forbidden`` // response if the communication with the authorization service has failed, or if the // authorization service has returned a HTTP 5xx error. // // Note that errors can be ``always`` tracked in the :ref:`stats // `. bool failure_mode_allow = 2; // When ``failure_mode_allow`` and ``failure_mode_allow_header_add`` are both set to true, // ``x-envoy-auth-failure-mode-allowed: true`` will be added to request headers if the communication // with the authorization service has failed, or if the authorization service has returned a // HTTP 5xx error. bool failure_mode_allow_header_add = 19; // Enables filter to buffer the client request body and send it within the authorization request. // A ``x-envoy-auth-partial-body: false|true`` metadata header will be added to the authorization // request message indicating if the body data is partial. BufferSettings with_request_body = 5; // Clears route cache in order to allow the external authorization service to correctly affect // routing decisions. Filter clears all cached routes when: // // 1. The field is set to ``true``. // // 2. The status returned from the authorization service is a HTTP 200 or gRPC 0. // // 3. At least one ``authorization response header`` is added to the client request, or is used for // altering another client request header. // bool clear_route_cache = 6; // Sets the HTTP status that is returned to the client when the authorization server returns an error // or cannot be reached. The default status is HTTP 403 Forbidden. type.v3.HttpStatus status_on_error = 7; // When this is set to true, the filter will check the :ref:`ext_authz response // ` for invalid header & // query parameter mutations. If the side stream response is invalid, it will send a local reply // to the downstream request with status HTTP 500 Internal Server Error. // // Note that headers_to_remove & query_parameters_to_remove are validated, but invalid elements in // those fields should not affect any headers & thus will not cause the filter to send a local // reply. // // When set to false, any invalid mutations will be visible to the rest of envoy and may cause // unexpected behavior. // // If you are using ext_authz with an untrusted ext_authz server, you should set this to true. bool validate_mutations = 24; // Specifies a list of metadata namespaces whose values, if present, will be passed to the // ext_authz service. The :ref:`filter_metadata ` // is passed as an opaque ``protobuf::Struct``. // // Please note that this field exclusively applies to the gRPC ext_authz service and has no effect on the HTTP service. // // For example, if the ``jwt_authn`` filter is used and :ref:`payload_in_metadata // ` is set, // then the following will pass the jwt payload to the authorization server. // // .. code-block:: yaml // // metadata_context_namespaces: // - envoy.filters.http.jwt_authn // repeated string metadata_context_namespaces = 8; // Specifies a list of metadata namespaces whose values, if present, will be passed to the // ext_authz service. :ref:`typed_filter_metadata ` // is passed as a ``protobuf::Any``. // // Please note that this field exclusively applies to the gRPC ext_authz service and has no effect on the HTTP service. // // It works in a way similar to ``metadata_context_namespaces`` but allows Envoy and ext_authz server to share // the protobuf message definition in order to do a safe parsing. // repeated string typed_metadata_context_namespaces = 16; // Specifies a list of route metadata namespaces whose values, if present, will be passed to the // ext_authz service at :ref:`route_metadata_context ` in // :ref:`CheckRequest `. // :ref:`filter_metadata ` is passed as an opaque ``protobuf::Struct``. repeated string route_metadata_context_namespaces = 21; // Specifies a list of route metadata namespaces whose values, if present, will be passed to the // ext_authz service at :ref:`route_metadata_context ` in // :ref:`CheckRequest `. // :ref:`typed_filter_metadata ` is passed as an ``protobuf::Any``. repeated string route_typed_metadata_context_namespaces = 22; // Specifies if the filter is enabled. // // If :ref:`runtime_key ` is specified, // Envoy will lookup the runtime key to get the percentage of requests to filter. // // If this field is not specified, the filter will be enabled for all requests. config.core.v3.RuntimeFractionalPercent filter_enabled = 9; // Specifies if the filter is enabled with metadata matcher. // If this field is not specified, the filter will be enabled for all requests. type.matcher.v3.MetadataMatcher filter_enabled_metadata = 14; // Specifies whether to deny the requests, when the filter is disabled. // If :ref:`runtime_key ` is specified, // Envoy will lookup the runtime key to determine whether to deny request for // filter protected path at filter disabling. If filter is disabled in // typed_per_filter_config for the path, requests will not be denied. // // If this field is not specified, all requests will be allowed when disabled. // // If a request is denied due to this setting, the response code in :ref:`status_on_error // ` will // be returned. config.core.v3.RuntimeFeatureFlag deny_at_disable = 11; // Specifies if the peer certificate is sent to the external service. // // When this field is true, Envoy will include the peer X.509 certificate, if available, in the // :ref:`certificate`. bool include_peer_certificate = 10; // Optional additional prefix to use when emitting statistics. This allows to distinguish // emitted statistics between configured ``ext_authz`` filters in an HTTP filter chain. For example: // // .. code-block:: yaml // // http_filters: // - name: envoy.filters.http.ext_authz // typed_config: // "@type": type.googleapis.com/envoy.extensions.filters.http.ext_authz.v3.ExtAuthz // stat_prefix: waf # This emits ext_authz.waf.ok, ext_authz.waf.denied, etc. // - name: envoy.filters.http.ext_authz // typed_config: // "@type": type.googleapis.com/envoy.extensions.filters.http.ext_authz.v3.ExtAuthz // stat_prefix: blocker # This emits ext_authz.blocker.ok, ext_authz.blocker.denied, etc. // string stat_prefix = 13; // Optional labels that will be passed to :ref:`labels` in // :ref:`destination`. // The labels will be read from :ref:`metadata` with the specified key. string bootstrap_metadata_labels_key = 15; // Check request to authorization server will include the client request headers that have a correspondent match // in the :ref:`list `. If this option isn't specified, then // all client request headers are included in the check request to a gRPC authorization server, whereas no client request headers // (besides the ones allowed by default - see note below) are included in the check request to an HTTP authorization server. // This inconsistency between gRPC and HTTP servers is to maintain backwards compatibility with legacy behavior. // // .. note:: // // 1. For requests to an HTTP authorization server: in addition to the user's supplied matchers, ``Host``, ``Method``, ``Path``, // ``Content-Length``, and ``Authorization`` are **additionally included** in the list. // // .. note:: // // 2. For requests to an HTTP authorization server: value of ``Content-Length`` will be set to 0 and the request to the // authorization server will not have a message body. However, the check request can include the buffered // client request body (controlled by :ref:`with_request_body // ` setting), // consequently the value of *Content-Length* of the authorization request reflects the size of // its payload size. // // .. note:: // // 3. This can be overridden by the field ``disallowed_headers`` below. That is, if a header // matches for both ``allowed_headers`` and ``disallowed_headers``, the header will NOT be sent. type.matcher.v3.ListStringMatcher allowed_headers = 17; // If set, specifically disallow any header in this list to be forwarded to the external // authentication server. This overrides the above ``allowed_headers`` if a header matches both. type.matcher.v3.ListStringMatcher disallowed_headers = 25; // Specifies if the TLS session level details like SNI are sent to the external service. // // When this field is true, Envoy will include the SNI name used for TLSClientHello, if available, in the // :ref:`tls_session`. bool include_tls_session = 18; // Whether to increment cluster statistics (e.g. cluster..upstream_rq_*) on authorization failure. // Defaults to true. google.protobuf.BoolValue charge_cluster_response_stats = 20; // Whether to encode the raw headers (i.e. unsanitized values & unconcatenated multi-line headers) // in authentication request. Works with both HTTP and gRPC clients. // // When this is set to true, header values are not sanitized. Headers with the same key will also // not be combined into a single, comma-separated header. // Requests to gRPC services will populate the field // :ref:`header_map`. // Requests to HTTP services will be constructed with the unsanitized header values and preserved // multi-line headers with the same key. // // If this field is set to false, header values will be sanitized, with any non-UTF-8-compliant // bytes replaced with '!'. Headers with the same key will have their values concatenated into a // single comma-separated header value. // Requests to gRPC services will populate the field // :ref:`headers`. // Requests to HTTP services will have their header values sanitized and will not preserve // multi-line headers with the same key. // // It's recommended you set this to true unless you already rely on the old behavior. False is the // default only for backwards compatibility. bool encode_raw_headers = 23; // Rules for what modifications an ext_authz server may make to the request headers before // continuing decoding / forwarding upstream. // // If set to anything, enables header mutation checking against configured rules. Note that // :ref:`HeaderMutationRules ` // has defaults that change ext_authz behavior. Also note that if this field is set to anything, // ext_authz can no longer append to :-prefixed headers. // // If empty, header mutation rule checking is completely disabled. // // Regardless of what is configured here, ext_authz cannot remove :-prefixed headers. // // This field and ``validate_mutations`` have different use cases. ``validate_mutations`` enables // correctness checks for all header / query parameter mutations (e.g. for invalid characters). // This field allows the filter to reject mutations to specific headers. config.common.mutation_rules.v3.HeaderMutationRules decoder_header_mutation_rules = 26; // Enable / disable ingestion of dynamic metadata from ext_authz service. // // If false, the filter will ignore dynamic metadata injected by the ext_authz service. If the // ext_authz service tries injecting dynamic metadata, the filter will log, increment the // ``ignored_dynamic_metadata`` stat, then continue handling the response. // // If true, the filter will ingest dynamic metadata entries as normal. // // If unset, defaults to true. google.protobuf.BoolValue enable_dynamic_metadata_ingestion = 27; // Additional metadata to be added to the filter state for logging purposes. The metadata will be // added to StreamInfo's filter state under the namespace corresponding to the ext_authz filter // name. google.protobuf.Struct filter_metadata = 28; // When set to true, the filter will emit per-stream stats for access logging. The filter state // key will be the same as the filter name. // // If using Envoy gRPC, emits latency, bytes sent / received, upstream info, and upstream cluster // info. If not using Envoy gRPC, emits only latency. Note that stats are ONLY added to filter // state if a check request is actually made to an ext_authz service. // // If this is false the filter will not emit stats, but filter_metadata will still be respected if // it has a value. // // Field ``latency_us`` is exposed for CEL and logging when using gRPC or HTTP service. // Fields ``bytesSent`` and ``bytesReceived`` are exposed for CEL and logging only when using gRPC service. bool emit_filter_state_stats = 29; } // Configuration for buffering the request data. message BufferSettings { option (udpa.annotations.versioning).previous_message_type = "envoy.config.filter.http.ext_authz.v2.BufferSettings"; // Sets the maximum size of a message body that the filter will hold in memory. Envoy will return // ``HTTP 413`` and will *not* initiate the authorization process when buffer reaches the number // set in this field. Note that this setting will have precedence over :ref:`failure_mode_allow // `. uint32 max_request_bytes = 1 [(validate.rules).uint32 = {gt: 0}]; // When this field is true, Envoy will buffer the message until ``max_request_bytes`` is reached. // The authorization request will be dispatched and no 413 HTTP error will be returned by the // filter. bool allow_partial_message = 2; // If true, the body sent to the external authorization service is set with raw bytes, it sets // the :ref:`raw_body` // field of HTTP request attribute context. Otherwise, :ref:`body // ` will be filled // with UTF-8 string request body. // // This field only affects configurations using a :ref:`grpc_service // `. In configurations that use // an :ref:`http_service `, this // has no effect. bool pack_as_bytes = 3; } // HttpService is used for raw HTTP communication between the filter and the authorization service. // When configured, the filter will parse the client request and use these attributes to call the // authorization server. Depending on the response, the filter may reject or accept the client // request. Note that in any of these events, metadata can be added, removed or overridden by the // filter: // // *On authorization request*, a list of allowed request headers may be supplied. See // :ref:`allowed_headers // ` // for details. Additional headers metadata may be added to the authorization request. See // :ref:`headers_to_add // ` for // details. // // On authorization response status HTTP 200 OK, the filter will allow traffic to the upstream and // additional headers metadata may be added to the original client request. See // :ref:`allowed_upstream_headers // ` // for details. Additionally, the filter may add additional headers to the client's response. See // :ref:`allowed_client_headers_on_success // ` // for details. // // On other authorization response statuses, the filter will not allow traffic. Additional headers // metadata as well as body may be added to the client's response. See :ref:`allowed_client_headers // ` // for details. // [#next-free-field: 9] message HttpService { option (udpa.annotations.versioning).previous_message_type = "envoy.config.filter.http.ext_authz.v2.HttpService"; reserved 3, 4, 5, 6; // Sets the HTTP server URI which the authorization requests must be sent to. config.core.v3.HttpUri server_uri = 1; // Sets a prefix to the value of authorization request header ``Path``. string path_prefix = 2; // Settings used for controlling authorization request metadata. AuthorizationRequest authorization_request = 7; // Settings used for controlling authorization response metadata. AuthorizationResponse authorization_response = 8; } message AuthorizationRequest { option (udpa.annotations.versioning).previous_message_type = "envoy.config.filter.http.ext_authz.v2.AuthorizationRequest"; // Authorization request includes the client request headers that have a correspondent match // in the :ref:`list `. // This field has been deprecated in favor of :ref:`allowed_headers // `. // // .. note:: // // In addition to the user's supplied matchers, ``Host``, ``Method``, ``Path``, // ``Content-Length``, and ``Authorization`` are **automatically included** in the list. // // .. note:: // // By default, ``Content-Length`` header is set to ``0`` and the request to the authorization // service has no message body. However, the authorization request *may* include the buffered // client request body (controlled by :ref:`with_request_body // ` // setting) hence the value of its ``Content-Length`` reflects the size of its payload size. // type.matcher.v3.ListStringMatcher allowed_headers = 1 [deprecated = true, (envoy.annotations.deprecated_at_minor_version) = "3.0"]; // Sets a list of headers that will be included to the request to authorization service. Note that // client request of the same key will be overridden. repeated config.core.v3.HeaderValue headers_to_add = 2; } // [#next-free-field: 6] message AuthorizationResponse { option (udpa.annotations.versioning).previous_message_type = "envoy.config.filter.http.ext_authz.v2.AuthorizationResponse"; // When this :ref:`list ` is set, authorization // response headers that have a correspondent match will be added to the original client request. // Note that coexistent headers will be overridden. type.matcher.v3.ListStringMatcher allowed_upstream_headers = 1; // When this :ref:`list ` is set, authorization // response headers that have a correspondent match will be added to the original client request. // Note that coexistent headers will be appended. type.matcher.v3.ListStringMatcher allowed_upstream_headers_to_append = 3; // When this :ref:`list ` is set, authorization // response headers that have a correspondent match will be added to the client's response. Note // that when this list is *not* set, all the authorization response headers, except ``Authority // (Host)`` will be in the response to the client. When a header is included in this list, ``Path``, // ``Status``, ``Content-Length``, ``WWWAuthenticate`` and ``Location`` are automatically added. type.matcher.v3.ListStringMatcher allowed_client_headers = 2; // When this :ref:`list ` is set, authorization // response headers that have a correspondent match will be added to the client's response when // the authorization response itself is successful, i.e. not failed or denied. When this list is // *not* set, no additional headers will be added to the client's response on success. type.matcher.v3.ListStringMatcher allowed_client_headers_on_success = 4; // When this :ref:`list ` is set, authorization // response headers that have a correspondent match will be emitted as dynamic metadata to be consumed // by the next filter. This metadata lives in a namespace specified by the canonical name of extension filter // that requires it: // // - :ref:`envoy.filters.http.ext_authz ` for HTTP filter. // - :ref:`envoy.filters.network.ext_authz ` for network filter. type.matcher.v3.ListStringMatcher dynamic_metadata_from_headers = 5; } // Extra settings on a per virtualhost/route/weighted-cluster level. message ExtAuthzPerRoute { option (udpa.annotations.versioning).previous_message_type = "envoy.config.filter.http.ext_authz.v2.ExtAuthzPerRoute"; oneof override { option (validate.required) = true; // Disable the ext auth filter for this particular vhost or route. // If disabled is specified in multiple per-filter-configs, the most specific one will be used. // If the filter is disabled by default and this is set to false, the filter will be enabled // for this vhost or route. bool disabled = 1; // Check request settings for this route. CheckSettings check_settings = 2 [(validate.rules).message = {required: true}]; } } // Extra settings for the check request. message CheckSettings { option (udpa.annotations.versioning).previous_message_type = "envoy.config.filter.http.ext_authz.v2.CheckSettings"; // Context extensions to set on the CheckRequest's // :ref:`AttributeContext.context_extensions` // // You can use this to provide extra context for the external authorization server on specific // virtual hosts/routes. For example, adding a context extension on the virtual host level can // give the ext-authz server information on what virtual host is used without needing to parse the // host header. If CheckSettings is specified in multiple per-filter-configs, they will be merged // in order, and the result will be used. // // Merge semantics for this field are such that keys from more specific configs override. // // .. note:: // // These settings are only applied to a filter configured with a // :ref:`grpc_service`. map context_extensions = 1 [(udpa.annotations.sensitive) = true]; // When set to true, disable the configured :ref:`with_request_body // ` for a specific route. // // Please note that only one of *disable_request_body_buffering* or // :ref:`with_request_body ` // may be specified. bool disable_request_body_buffering = 2; // Enable or override request body buffering, which is configured using the // :ref:`with_request_body ` // option for a specific route. // // Please note that only one of ``with_request_body`` or // :ref:`disable_request_body_buffering ` // may be specified. BufferSettings with_request_body = 3; }