Attribute Context

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:

See network filter configuration overview and HTTP filter configuration overview.


[service.auth.v3.AttributeContext proto]

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.

  "source": "{...}",
  "destination": "{...}",
  "request": "{...}",
  "context_extensions": "{...}",
  "metadata_context": "{...}"

(service.auth.v3.AttributeContext.Peer) 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.


(service.auth.v3.AttributeContext.Peer) 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.


(service.auth.v3.AttributeContext.Request) Represents a network request, such as an HTTP request.


(repeated map<string, string>) 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.


(config.core.v3.Metadata) Dynamic metadata associated with the request.


[service.auth.v3.AttributeContext.Peer proto]

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.

  "address": "{...}",
  "service": "...",
  "labels": "{...}",
  "principal": "...",
  "certificate": "..."

(config.core.v3.Address) The address of the peer, this is typically the IP address. It can also be UDS path, or others.


(string) The canonical service name of the peer. It should be set to the HTTP x-envoy-downstream-service-cluster If a more trusted source of the service name is available through mTLS/secure naming, it should be used.


(repeated map<string, string>) 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) 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.

Example: * SPIFFE format is spiffe://trust-domain/path * Google account format is{userid}


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


[service.auth.v3.AttributeContext.Request proto]

Represents a network request, such as an HTTP request.

  "time": "{...}",
  "http": "{...}"

(Timestamp) The timestamp when the proxy receives the first byte of the request.


(service.auth.v3.AttributeContext.HttpRequest) Represents an HTTP request or an HTTP-like request.


[service.auth.v3.AttributeContext.HttpRequest proto]

This message defines attributes for an HTTP request. HTTP/1.x, HTTP/2, gRPC are all considered as HTTP requests.

  "id": "...",
  "method": "...",
  "headers": "{...}",
  "path": "...",
  "host": "...",
  "scheme": "...",
  "query": "...",
  "fragment": "...",
  "size": "...",
  "protocol": "...",
  "body": "...",
  "raw_body": "..."

(string) 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) The HTTP request method, such as GET, POST.


(repeated map<string, string>) 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.


(string) 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) The HTTP request Host or ‘Authority` header value.


(string) The HTTP URL scheme, such as http and https.


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


(string) 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) The HTTP request size in bytes. If unknown, it must be -1.


(string) The network protocol used with the request, such as “HTTP/1.0”, “HTTP/1.1”, or “HTTP/2”.

See headers.h:ProtocolStrings for a list of all possible values.


(string) The HTTP request body.


(bytes) The HTTP request body in bytes. This is used instead of body when pack_as_bytes is set to true.