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

syntax = "proto3";

package envoy.service.auth.v2;

option java_outer_classname = "ExternalAuthProto";
option java_multiple_files = true;
option java_package = "io.envoyproxy.envoy.service.auth.v2";
option go_package = "v2";
option java_generic_services = true;

import "envoy/api/v2/core/base.proto";
import "envoy/type/http_status.proto";
import "envoy/service/auth/v2/attribute_context.proto";

import "google/rpc/status.proto";
import "validate/validate.proto";

// [#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 {
  // The request attributes.
  AttributeContext attributes = 1;
}

// HTTP attributes for a denied response.
message DeniedHttpResponse {
  // This field allows the authorization service to send a HTTP response status
  // code to the downstream client other than 403 (Forbidden).
  envoy.type.HttpStatus status = 1 [(validate.rules).message.required = true];

  // This field allows the authorization service to send HTTP response headers
  // to the downstream client.
  repeated envoy.api.v2.core.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.
message 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. By setting `append` field to `true` in the `HeaderValueOption`,
  // the filter will append the correspondent header value to the matched request header. Note that
  // by Leaving `append` as false, the filter will either add a new header, or override an existing
  // one if there is a match.
  repeated envoy.api.v2.core.HeaderValueOption headers = 2;
}

// Intended for gRPC and Network Authorization servers `only`.
message CheckResponse {
  // Status `OK` allows the request. Any other status indicates the request should be denied.
  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;
  }
}