package envoy.service.auth.v2

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:30

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

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: 12]

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 api.v2.core.Metadata metadata_context = 11

  Dynamic metadata associated with the request.

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

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.

• 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`. This is set for HTTP/2 requests only. For HTTP/1.1, use "x-forwarded-for" header value to lookup the scheme of the request.

• 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.

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 api.v2.core.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. Example: * 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.

Used as request type in: Authorization.Check, v2alpha.Authorization.Check

• optional AttributeContext attributes = 1

  The request attributes.

Intended for gRPC and Network Authorization servers `only`.

Used as response type in: Authorization.Check, v2alpha.Authorization.Check

• optional google.rpc.Status status = 1

  Status `OK` allows the request. Any other status indicates the request should be denied.

• 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.

HTTP attributes for a denied response.

Used in: CheckResponse

• optional type.HttpStatus status = 1

  This field allows the authorization service to send a HTTP response status code to the downstream client other than 403 (Forbidden).

• repeated api.v2.core.HeaderValueOption headers = 2

  This field allows the authorization service to send HTTP response headers to the downstream client. Note that the `append` field in `HeaderValueOption` 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.

Used in: CheckResponse

• repeated api.v2.core.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 `append` field in `HeaderValueOption` 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.