package envoy.service.auth.v3

Get desktop application:
View/edit binary Protocol Buffers messages

A generic interface for performing authorization check on incoming requests to a networked service.

• rpc Check (CheckRequest, CheckResponse)

  external_auth.proto:32

  Performs authorization check based on the attributes associated with the incoming request, and returns status `OK` or not `OK`.

  message CheckRequest

  external_auth.proto:36

  • optional AttributeContext attributes = 1

    The request attributes.

  message CheckResponse

  external_auth.proto:117

  Intended for gRPC and Network Authorization servers ``only``.

  • optional google.rpc.Status status = 1

    Status ``OK`` allows the request. Any other status indicates the request should be denied, and for HTTP filter, if not overridden by :ref:`denied HTTP response status <envoy_v3_api_field_service.auth.v3.DeniedHttpResponse.status>` Envoy sends ``403 Forbidden`` HTTP status code by default.

  • oneof http_response

    An message that contains HTTP response attributes. This message is used when the authorization service needs to send custom responses to the downstream client or, to modify/add request headers being dispatched to the upstream.

    • DeniedHttpResponse denied_response = 2

      Supplies http attributes for a denied response.

    • OkHttpResponse ok_response = 3

      Supplies http attributes for an ok response.

  • optional google.protobuf.Struct dynamic_metadata = 4

    Optional response metadata that 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 <config_http_filters_ext_authz_dynamic_metadata>` for HTTP filter. - :ref:`envoy.filters.network.ext_authz <config_network_filters_ext_authz_dynamic_metadata>` for network filter.

An attribute is a piece of metadata that describes an activity on a network. For example, the size of an HTTP request, or the status code of an HTTP response. Each attribute has a type and a name, which is logically defined as a proto message field of the ``AttributeContext``. The ``AttributeContext`` is a collection of individual attributes supported by Envoy authorization system. [#comment: The following items are left out of this proto Request.Auth field for JWTs Request.Api for api management Origin peer that originated the request Caching Protocol request_context return values to inject back into the filter chain peer.claims -- from X.509 extensions Configuration - field mask to send - which return values from request_context are copied back - which return values are copied into request_headers] [#next-free-field: 14]

Used in: CheckRequest

• optional AttributeContext.Peer source = 1

  The source of a network activity, such as starting a TCP connection. In a multi hop network activity, the source represents the sender of the last hop.

• optional AttributeContext.Peer destination = 2

  The destination of a network activity, such as accepting a TCP connection. In a multi hop network activity, the destination represents the receiver of the last hop.

• optional AttributeContext.Request request = 4

  Represents a network request, such as an HTTP request.

• map<string, string> context_extensions = 10

  This is analogous to http_request.headers, however these contents will not be sent to the upstream server. Context_extensions provide an extension mechanism for sending additional information to the auth server without modifying the proto definition. It maps to the internal opaque context in the filter chain.

• optional config.core.v3.Metadata metadata_context = 11

  Dynamic metadata associated with the request.

• optional config.core.v3.Metadata route_metadata_context = 13

  Metadata associated with the selected route.

• optional AttributeContext.TLSSession tls_session = 12

  TLS session details of the underlying connection. This is not populated by default and will be populated only if the ext_authz filter has been specifically configured to include this information. For HTTP ext_authz, that requires :ref:`include_tls_session <config_http_filters_ext_authz>` to be set to true. For network ext_authz, that requires :ref:`include_tls_session <config_network_filters_ext_authz>` to be set to true.

This message defines attributes for an HTTP request. HTTP/1.x, HTTP/2, gRPC are all considered as HTTP requests. [#next-free-field: 14]

Used in: Request

• string id = 1

  The unique ID for a request, which can be propagated to downstream systems. The ID should have low probability of collision within a single day for a specific service. For HTTP requests, it should be X-Request-ID or equivalent.

• string method = 2

  The HTTP request method, such as ``GET``, ``POST``.

• map<string, string> headers = 3

  The HTTP request headers. If multiple headers share the same key, they must be merged according to the HTTP spec. All header keys must be lower-cased, because HTTP header keys are case-insensitive. Header value is encoded as UTF-8 string. Non-UTF-8 characters will be replaced by "!". This field will not be set if :ref:`encode_raw_headers <envoy_v3_api_field_extensions.filters.http.ext_authz.v3.ExtAuthz.encode_raw_headers>` is set to true.

• optional config.core.v3.HeaderMap header_map = 13

  A list of the raw HTTP request headers. This is used instead of :ref:`headers <envoy_v3_api_field_service.auth.v3.AttributeContext.HttpRequest.headers>` when :ref:`encode_raw_headers <envoy_v3_api_field_extensions.filters.http.ext_authz.v3.ExtAuthz.encode_raw_headers>` is set to true. Note that this is not actually a map type. ``header_map`` contains a single repeated field ``headers``. Here, only the ``key`` and ``raw_value`` fields will be populated for each HeaderValue, and that is only when :ref:`encode_raw_headers <envoy_v3_api_field_extensions.filters.http.ext_authz.v3.ExtAuthz.encode_raw_headers>` is set to true. Also, unlike the :ref:`headers <envoy_v3_api_field_service.auth.v3.AttributeContext.HttpRequest.headers>` field, headers with the same key are not combined into a single comma separated header.

• string path = 4

  The request target, as it appears in the first line of the HTTP request. This includes the URL path and query-string. No decoding is performed.

• string host = 5

  The HTTP request ``Host`` or ``:authority`` header value.

• string scheme = 6

  The HTTP URL scheme, such as ``http`` and ``https``.

• string query = 7

  This field is always empty, and exists for compatibility reasons. The HTTP URL query is included in ``path`` field.

• string fragment = 8

  This field is always empty, and exists for compatibility reasons. The URL fragment is not submitted as part of HTTP requests; it is unknowable.

• int64 size = 9

  The HTTP request size in bytes. If unknown, it must be -1.

• string protocol = 10

  The network protocol used with the request, such as "HTTP/1.0", "HTTP/1.1", or "HTTP/2". See :repo:`headers.h:ProtocolStrings <source/common/http/headers.h>` for a list of all possible values.

• string body = 11

  The HTTP request body.

• bytes raw_body = 12

  The HTTP request body in bytes. This is used instead of :ref:`body <envoy_v3_api_field_service.auth.v3.AttributeContext.HttpRequest.body>` when :ref:`pack_as_bytes <envoy_v3_api_field_extensions.filters.http.ext_authz.v3.BufferSettings.pack_as_bytes>` is set to true.

This message defines attributes for a node that handles a network request. The node can be either a service or an application that sends, forwards, or receives the request. Service peers should fill in the ``service``, ``principal``, and ``labels`` as appropriate. [#next-free-field: 6]

Used in: AttributeContext

• optional config.core.v3.Address address = 1

  The address of the peer, this is typically the IP address. It can also be UDS path, or others.

• string service = 2

  The canonical service name of the peer. It should be set to :ref:`the HTTP x-envoy-downstream-service-cluster <config_http_conn_man_headers_downstream-service-cluster>` If a more trusted source of the service name is available through mTLS/secure naming, it should be used.

• map<string, string> labels = 3

  The labels associated with the peer. These could be pod labels for Kubernetes or tags for VMs. The source of the labels could be an X.509 certificate or other configuration.

• string principal = 4

  The authenticated identity of this peer. For example, the identity associated with the workload such as a service account. If an X.509 certificate is used to assert the identity this field should be sourced from ``URI Subject Alternative Names``, ``DNS Subject Alternate Names`` or ``Subject`` in that order. The primary identity should be the principal. The principal format is issuer specific. Examples: - SPIFFE format is ``spiffe://trust-domain/path``. - Google account format is ``https://accounts.google.com/{userid}``.

• string certificate = 5

  The X.509 certificate used to authenticate the identify of this peer. When present, the certificate contents are encoded in URL and PEM format.

Represents a network request, such as an HTTP request.

Used in: AttributeContext

• optional google.protobuf.Timestamp time = 1

  The timestamp when the proxy receives the first byte of the request.

• optional HttpRequest http = 2

  Represents an HTTP request or an HTTP-like request.

This message defines attributes for the underlying TLS session.

Used in: AttributeContext

• string sni = 1

  SNI used for TLS session.

HTTP attributes for a denied response.

Used in: CheckResponse

• optional type.v3.HttpStatus status = 1

  This field allows the authorization service to send an HTTP response status code to the downstream client. If not set, Envoy sends ``403 Forbidden`` HTTP status code by default.

• repeated config.core.v3.HeaderValueOption headers = 2

  This field allows the authorization service to send HTTP response headers to the downstream client. Note that the :ref:`append field in HeaderValueOption <envoy_v3_api_field_config.core.v3.HeaderValueOption.append>` defaults to false when used in this message.

• string body = 3

  This field allows the authorization service to send a response body data to the downstream client.

HTTP attributes for an OK response. [#next-free-field: 9]

Used in: CheckResponse

• repeated config.core.v3.HeaderValueOption headers = 2

  HTTP entity headers in addition to the original request headers. This allows the authorization service to append, to add or to override headers from the original request before dispatching it to the upstream. Note that the :ref:`append field in HeaderValueOption <envoy_v3_api_field_config.core.v3.HeaderValueOption.append>` defaults to false when used in this message. By setting the ``append`` field to ``true``, the filter will append the correspondent header value to the matched request header. By leaving ``append`` as false, the filter will either add a new header, or override an existing one if there is a match.

• repeated string headers_to_remove = 5

  HTTP entity headers to remove from the original request before dispatching it to the upstream. This allows the authorization service to act on auth related headers (like ``Authorization``), process them, and consume them. Under this model, the upstream will either receive the request (if it's authorized) or not receive it (if it's not), but will not see headers containing authorization credentials. Pseudo headers (such as ``:authority``, ``:method``, ``:path`` etc), as well as the header ``Host``, may not be removed as that would make the request malformed. If mentioned in ``headers_to_remove`` these special headers will be ignored. When using the HTTP service this must instead be set by the HTTP authorization service as a comma separated list like so: ``x-envoy-auth-headers-to-remove: one-auth-header, another-auth-header``.

• optional google.protobuf.Struct dynamic_metadata = 3

  This field has been deprecated in favor of :ref:`CheckResponse.dynamic_metadata <envoy_v3_api_field_service.auth.v3.CheckResponse.dynamic_metadata>`. Until it is removed, setting this field overrides :ref:`CheckResponse.dynamic_metadata <envoy_v3_api_field_service.auth.v3.CheckResponse.dynamic_metadata>`.

• repeated config.core.v3.HeaderValueOption response_headers_to_add = 6

  This field allows the authorization service to send HTTP response headers to the downstream client on success. Note that the :ref:`append field in HeaderValueOption <envoy_v3_api_field_config.core.v3.HeaderValueOption.append>` defaults to false when used in this message.

• repeated config.core.v3.QueryParameter query_parameters_to_set = 7

  This field allows the authorization service to set (and overwrite) query string parameters on the original request before it is sent upstream.

• repeated string query_parameters_to_remove = 8

  This field allows the authorization service to specify which query parameters should be removed from the original request before it is sent upstream. Each element in this list is a case-sensitive query parameter name to be removed.