.. _envoy_v3_api_file_envoy/extensions/filters/http/ext_authz/v3/ext_authz.proto: External Authorization ====================== This documentation is for the Envoy v3 API. As of Envoy v1.18 the v2 API has been removed and is no longer supported. If you are upgrading from v2 API config you may wish to view the v2 API documentation: :ref:`config/filter/http/ext_authz/v2/ext_authz.proto ` .. _extension_envoy.filters.http.ext_authz: This extension may be referenced by the qualified name ``envoy.filters.http.ext_authz`` .. note:: This extension is intended to be robust against untrusted downstream traffic. It assumes that the upstream is trusted. .. tip:: This extension extends and can be used with the following extension category: - :ref:`envoy.filters.http ` External Authorization :ref:`configuration overview `. .. _envoy_v3_api_msg_extensions.filters.http.ext_authz.v3.ExtAuthz: extensions.filters.http.ext_authz.v3.ExtAuthz --------------------------------------------- :repo:`[extensions.filters.http.ext_authz.v3.ExtAuthz proto] ` .. code-block:: json { "grpc_service": "{...}", "http_service": "{...}", "transport_api_version": "...", "failure_mode_allow": "...", "with_request_body": "{...}", "clear_route_cache": "...", "status_on_error": "{...}", "metadata_context_namespaces": [], "filter_enabled": "{...}", "filter_enabled_metadata": "{...}", "deny_at_disable": "{...}", "include_peer_certificate": "...", "stat_prefix": "...", "bootstrap_metadata_labels_key": "..." } .. _envoy_v3_api_field_extensions.filters.http.ext_authz.v3.ExtAuthz.grpc_service: grpc_service (:ref:`config.core.v3.GrpcService `) gRPC service configuration (default timeout: 200ms). External authorization service configuration. Only one of :ref:`grpc_service `, :ref:`http_service ` may be set. .. _envoy_v3_api_field_extensions.filters.http.ext_authz.v3.ExtAuthz.http_service: http_service (:ref:`extensions.filters.http.ext_authz.v3.HttpService `) HTTP service configuration (default timeout: 200ms). External authorization service configuration. Only one of :ref:`grpc_service `, :ref:`http_service ` may be set. .. _envoy_v3_api_field_extensions.filters.http.ext_authz.v3.ExtAuthz.transport_api_version: transport_api_version (:ref:`config.core.v3.ApiVersion `) API version for ext_authz transport protocol. This describes the ext_authz gRPC endpoint and version of messages used on the wire. .. _envoy_v3_api_field_extensions.filters.http.ext_authz.v3.ExtAuthz.failure_mode_allow: failure_mode_allow (`bool `_) Changes filter's behaviour 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 `. .. _envoy_v3_api_field_extensions.filters.http.ext_authz.v3.ExtAuthz.with_request_body: with_request_body (:ref:`extensions.filters.http.ext_authz.v3.BufferSettings `) 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. .. _envoy_v3_api_field_extensions.filters.http.ext_authz.v3.ExtAuthz.clear_route_cache: clear_route_cache (`bool `_) 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. .. _envoy_v3_api_field_extensions.filters.http.ext_authz.v3.ExtAuthz.status_on_error: status_on_error (:ref:`type.v3.HttpStatus `) Sets the HTTP status that is returned to the client when there is a network error between the filter and the authorization server. The default status is HTTP 403 Forbidden. .. _envoy_v3_api_field_extensions.filters.http.ext_authz.v3.ExtAuthz.metadata_context_namespaces: metadata_context_namespaces (**repeated** `string `_) Specifies a list of metadata namespaces whose values, if present, will be passed to the ext_authz service as an opaque *protobuf::Struct*. 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 .. _envoy_v3_api_field_extensions.filters.http.ext_authz.v3.ExtAuthz.filter_enabled: filter_enabled (:ref:`config.core.v3.RuntimeFractionalPercent `) 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. .. _envoy_v3_api_field_extensions.filters.http.ext_authz.v3.ExtAuthz.filter_enabled_metadata: filter_enabled_metadata (:ref:`type.matcher.v3.MetadataMatcher `) Specifies if the filter is enabled with metadata matcher. If this field is not specified, the filter will be enabled for all requests. .. _envoy_v3_api_field_extensions.filters.http.ext_authz.v3.ExtAuthz.deny_at_disable: deny_at_disable (:ref:`config.core.v3.RuntimeFeatureFlag `) 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. .. _envoy_v3_api_field_extensions.filters.http.ext_authz.v3.ExtAuthz.include_peer_certificate: include_peer_certificate (`bool `_) 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`. .. _envoy_v3_api_field_extensions.filters.http.ext_authz.v3.ExtAuthz.stat_prefix: stat_prefix (`string `_) 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. .. _envoy_v3_api_field_extensions.filters.http.ext_authz.v3.ExtAuthz.bootstrap_metadata_labels_key: bootstrap_metadata_labels_key (`string `_) Optional labels that will be passed to :ref:`labels` in :ref:`destination`. The labels will be read from :ref:`metadata` with the specified key. .. _envoy_v3_api_msg_extensions.filters.http.ext_authz.v3.BufferSettings: extensions.filters.http.ext_authz.v3.BufferSettings --------------------------------------------------- :repo:`[extensions.filters.http.ext_authz.v3.BufferSettings proto] ` Configuration for buffering the request data. .. code-block:: json { "max_request_bytes": "...", "allow_partial_message": "...", "pack_as_bytes": "..." } .. _envoy_v3_api_field_extensions.filters.http.ext_authz.v3.BufferSettings.max_request_bytes: max_request_bytes (`uint32 `_) 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 `. .. _envoy_v3_api_field_extensions.filters.http.ext_authz.v3.BufferSettings.allow_partial_message: allow_partial_message (`bool `_) 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. .. _envoy_v3_api_field_extensions.filters.http.ext_authz.v3.BufferSettings.pack_as_bytes: pack_as_bytes (`bool `_) 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. .. _envoy_v3_api_msg_extensions.filters.http.ext_authz.v3.HttpService: extensions.filters.http.ext_authz.v3.HttpService ------------------------------------------------ :repo:`[extensions.filters.http.ext_authz.v3.HttpService proto] ` 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. .. code-block:: json { "server_uri": "{...}", "path_prefix": "...", "authorization_request": "{...}", "authorization_response": "{...}" } .. _envoy_v3_api_field_extensions.filters.http.ext_authz.v3.HttpService.server_uri: server_uri (:ref:`config.core.v3.HttpUri `) Sets the HTTP server URI which the authorization requests must be sent to. .. _envoy_v3_api_field_extensions.filters.http.ext_authz.v3.HttpService.path_prefix: path_prefix (`string `_) Sets a prefix to the value of authorization request header *Path*. .. _envoy_v3_api_field_extensions.filters.http.ext_authz.v3.HttpService.authorization_request: authorization_request (:ref:`extensions.filters.http.ext_authz.v3.AuthorizationRequest `) Settings used for controlling authorization request metadata. .. _envoy_v3_api_field_extensions.filters.http.ext_authz.v3.HttpService.authorization_response: authorization_response (:ref:`extensions.filters.http.ext_authz.v3.AuthorizationResponse `) Settings used for controlling authorization response metadata. .. _envoy_v3_api_msg_extensions.filters.http.ext_authz.v3.AuthorizationRequest: extensions.filters.http.ext_authz.v3.AuthorizationRequest --------------------------------------------------------- :repo:`[extensions.filters.http.ext_authz.v3.AuthorizationRequest proto] ` .. code-block:: json { "allowed_headers": "{...}", "headers_to_add": [] } .. _envoy_v3_api_field_extensions.filters.http.ext_authz.v3.AuthorizationRequest.allowed_headers: allowed_headers (:ref:`type.matcher.v3.ListStringMatcher `) Authorization request includes the client request headers that have a correspondent match in the :ref:`list `. .. note:: In addition to the the user's supplied matchers, ``Host``, ``Method``, ``Path``, ``Content-Length``, and ``Authorization`` are **automatically included** to 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. .. _envoy_v3_api_field_extensions.filters.http.ext_authz.v3.AuthorizationRequest.headers_to_add: headers_to_add (**repeated** :ref:`config.core.v3.HeaderValue `) 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. .. _envoy_v3_api_msg_extensions.filters.http.ext_authz.v3.AuthorizationResponse: extensions.filters.http.ext_authz.v3.AuthorizationResponse ---------------------------------------------------------- :repo:`[extensions.filters.http.ext_authz.v3.AuthorizationResponse proto] ` .. code-block:: json { "allowed_upstream_headers": "{...}", "allowed_upstream_headers_to_append": "{...}", "allowed_client_headers": "{...}", "allowed_client_headers_on_success": "{...}", "dynamic_metadata_from_headers": "{...}" } .. _envoy_v3_api_field_extensions.filters.http.ext_authz.v3.AuthorizationResponse.allowed_upstream_headers: allowed_upstream_headers (:ref:`type.matcher.v3.ListStringMatcher `) 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. .. _envoy_v3_api_field_extensions.filters.http.ext_authz.v3.AuthorizationResponse.allowed_upstream_headers_to_append: allowed_upstream_headers_to_append (:ref:`type.matcher.v3.ListStringMatcher `) When this :ref:`list ` is set, authorization response headers that have a correspondent match will be added to the client's response. Note that coexistent headers will be appended. .. _envoy_v3_api_field_extensions.filters.http.ext_authz.v3.AuthorizationResponse.allowed_client_headers: allowed_client_headers (:ref:`type.matcher.v3.ListStringMatcher `) 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. .. _envoy_v3_api_field_extensions.filters.http.ext_authz.v3.AuthorizationResponse.allowed_client_headers_on_success: allowed_client_headers_on_success (:ref:`type.matcher.v3.ListStringMatcher `) 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. .. _envoy_v3_api_field_extensions.filters.http.ext_authz.v3.AuthorizationResponse.dynamic_metadata_from_headers: dynamic_metadata_from_headers (:ref:`type.matcher.v3.ListStringMatcher `) 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. .. _envoy_v3_api_msg_extensions.filters.http.ext_authz.v3.ExtAuthzPerRoute: extensions.filters.http.ext_authz.v3.ExtAuthzPerRoute ----------------------------------------------------- :repo:`[extensions.filters.http.ext_authz.v3.ExtAuthzPerRoute proto] ` Extra settings on a per virtualhost/route/weighted-cluster level. .. code-block:: json { "disabled": "...", "check_settings": "{...}" } .. _envoy_v3_api_field_extensions.filters.http.ext_authz.v3.ExtAuthzPerRoute.disabled: disabled (`bool `_) 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. Precisely one of :ref:`disabled `, :ref:`check_settings ` must be set. .. _envoy_v3_api_field_extensions.filters.http.ext_authz.v3.ExtAuthzPerRoute.check_settings: check_settings (:ref:`extensions.filters.http.ext_authz.v3.CheckSettings `) Check request settings for this route. Precisely one of :ref:`disabled `, :ref:`check_settings ` must be set. .. _envoy_v3_api_msg_extensions.filters.http.ext_authz.v3.CheckSettings: extensions.filters.http.ext_authz.v3.CheckSettings -------------------------------------------------- :repo:`[extensions.filters.http.ext_authz.v3.CheckSettings proto] ` Extra settings for the check request. .. code-block:: json { "context_extensions": "{...}", "disable_request_body_buffering": "..." } .. _envoy_v3_api_field_extensions.filters.http.ext_authz.v3.CheckSettings.context_extensions: context_extensions (**repeated** map<`string `_, `string `_>) 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`. .. _envoy_v3_api_field_extensions.filters.http.ext_authz.v3.CheckSettings.disable_request_body_buffering: disable_request_body_buffering (`bool `_) When set to true, disable the configured :ref:`with_request_body ` for a route.