external_auth.proto

syntax = "proto3";

package envoy.service.auth.v3;

import "envoy/config/core/v3/base.proto";
import "envoy/service/auth/v3/attribute_context.proto";
import "envoy/type/v3/http_status.proto";

import "google/protobuf/struct.proto";
import "google/rpc/status.proto";

import "envoy/annotations/deprecation.proto";
import "udpa/annotations/status.proto";
import "udpa/annotations/versioning.proto";

option java_package = "io.envoyproxy.envoy.service.auth.v3";
option java_outer_classname = "ExternalAuthProto";
option java_multiple_files = true;
option go_package = "github.com/envoyproxy/go-control-plane/envoy/service/auth/v3;authv3";
option (udpa.annotations.file_status).package_version_status = ACTIVE;

// [#protodoc-title: Authorization service]

// The authorization service request messages used by external authorization :ref:`network filter
// <config_network_filters_ext_authz>` and :ref:`HTTP filter <config_http_filters_ext_authz>`.

// A generic interface for performing authorization check on incoming
// requests to a networked service.
service Authorization {
  // Performs authorization check based on the attributes associated with the
  // incoming request, and returns status `OK` or not `OK`.
  rpc Check(CheckRequest) returns (CheckResponse) {
  }
}

message CheckRequest {
  option (udpa.annotations.versioning).previous_message_type = "envoy.service.auth.v2.CheckRequest";

  // The request attributes.
  AttributeContext attributes = 1;
}

// HTTP attributes for a denied response.
message DeniedHttpResponse {
  option (udpa.annotations.versioning).previous_message_type =
      "envoy.service.auth.v2.DeniedHttpResponse";

  // 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.
  type.v3.HttpStatus status = 1;

  // 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.
  repeated config.core.v3.HeaderValueOption headers = 2;

  // This field allows the authorization service to send a response body data
  // to the downstream client.
  string body = 3;
}

// HTTP attributes for an OK response.
// [#next-free-field: 9]
message OkHttpResponse {
  option (udpa.annotations.versioning).previous_message_type =
      "envoy.service.auth.v2.OkHttpResponse";

  // 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 config.core.v3.HeaderValueOption headers = 2;

  // 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``.
  repeated string headers_to_remove = 5;

  // 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>`.
  google.protobuf.Struct dynamic_metadata = 3
      [deprecated = true, (envoy.annotations.deprecated_at_minor_version) = "3.0"];

  // 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.HeaderValueOption response_headers_to_add = 6;

  // This field allows the authorization service to set (and overwrite) query
  // string parameters on the original request before it is sent upstream.
  repeated config.core.v3.QueryParameter query_parameters_to_set = 7;

  // 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.
  repeated string query_parameters_to_remove = 8;
}

// Intended for gRPC and Network Authorization servers ``only``.
message CheckResponse {
  option (udpa.annotations.versioning).previous_message_type =
      "envoy.service.auth.v2.CheckResponse";

  // 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.
  google.rpc.Status status = 1;

  // 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.
  oneof http_response {
    // Supplies http attributes for a denied response.
    DeniedHttpResponse denied_response = 2;

    // Supplies http attributes for an ok response.
    OkHttpResponse ok_response = 3;
  }

  // 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.
  google.protobuf.Struct dynamic_metadata = 4;
}