data-plane-api/envoy/service/auth/v2/attribute_context.proto

syntax = "proto3";

// [#proto-status: draft]

package envoy.service.auth.v2;

import "envoy/api/v2/core/address.proto";

import "google/protobuf/timestamp.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.
message AttributeContext {
  // 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.
  message Peer {
    // The address of the peer, this is typically the IP address.
    // It can also be UDS path, or others.
    envoy.api.v2.core.Address address = 1;

    // 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.
    string service = 2;

    // 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.
    map<string, string> labels = 3;

    // 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
    // `Subject` or `Subject Alternative Names`. 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 `https://accounts.google.com/{userid}`
    string principal = 4;
  }

  // Represents a network request, such as an HTTP request.
  message Request {
    // The timestamp when the proxy receives the first byte of the request.
    google.protobuf.Timestamp time = 1;

    // Represents an HTTP request or an HTTP-like request.
    HttpRequest http = 2;

    // More request types are added here as necessary.
  }

  // This message defines attributes for an HTTP request.
  // HTTP/1.x, HTTP/2, gRPC are all considered as HTTP requests.
  message HttpRequest {
    // 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 id = 1;

    // The HTTP request method, such as `GET`, `POST`.
    string method = 2;

    // 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
    // lowercased, because HTTP header keys are case-insensitive.
    map<string, string> headers = 3;

    // The HTTP URL path.
    string path = 4;

    // The HTTP request `Host` or 'Authority` header value.
    string host = 5;

    // The HTTP URL scheme, such as `http` and `https`.
    string scheme = 6;

    // The HTTP URL query in the format of `name1=value`&name2=value2`, as it
    // appears in the first line of the HTTP request. No decoding is performed.
    string query = 7;

    // The HTTP URL fragment, excluding leading `#`. No URL decoding is performed.
    string fragment = 8;

    // The HTTP request size in bytes. If unknown, it must be -1.
    int64 size = 9;

    // The network protocol used with the request, such as
    // "http/1.1", "spdy/3", "h2", "h2c"
    string protocol = 10;
  }

  // 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.
  Peer source = 1;

  // 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.
  Peer destination = 2;

  // Represents a network request, such as an HTTP request.
  Request request = 4;

  // 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.
  map<string, string> context_extensions = 10;
}

// The following items are left out of this proto
// Request.Auth field for jwt tokens
// 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