...

Text file src/github.com/datawire/ambassador/v2/api/envoy/service/auth/v4alpha/external_auth.proto

Documentation: github.com/datawire/ambassador/v2/api/envoy/service/auth/v4alpha

     1syntax = "proto3";
     2
     3package envoy.service.auth.v4alpha;
     4
     5import "envoy/config/core/v4alpha/base.proto";
     6import "envoy/service/auth/v4alpha/attribute_context.proto";
     7import "envoy/type/v3/http_status.proto";
     8
     9import "google/protobuf/struct.proto";
    10import "google/rpc/status.proto";
    11
    12import "udpa/annotations/status.proto";
    13import "udpa/annotations/versioning.proto";
    14import "validate/validate.proto";
    15
    16option java_package = "io.envoyproxy.envoy.service.auth.v4alpha";
    17option java_outer_classname = "ExternalAuthProto";
    18option java_multiple_files = true;
    19option java_generic_services = true;
    20option (udpa.annotations.file_status).package_version_status = NEXT_MAJOR_VERSION_CANDIDATE;
    21
    22// [#protodoc-title: Authorization Service ]
    23
    24// The authorization service request messages used by external authorization :ref:`network filter
    25// <config_network_filters_ext_authz>` and :ref:`HTTP filter <config_http_filters_ext_authz>`.
    26
    27// A generic interface for performing authorization check on incoming
    28// requests to a networked service.
    29service Authorization {
    30  // For v2alpha to work as expected, we need to convince
    31  // proto_sync.py that the v2alpha package is the previous version of
    32  // either this package or the v2 package. And to do that, you'd
    33  // "normally" use the
    34  // "(udpa.annotations.versioning).previous_message_type" option; but
    35  // we don't have a 'message' to put it on, we only have a 'service'.
    36  // Fortunately, proto_sync.py's parser is sloppy, and we can fool it
    37  // with a comment:
    38  //
    39  //   previous_message_type = "envoy.service.auth.v2alpha.Authorization";
    40  //
    41  // Now, we'd also "normally" do that in the v2 package, not here.
    42  // But, because the v2alpha package imports the v2 package, that'd
    43  // cause a cycle.
    44  //
    45  // The lesson is that the "have v2alpha be an alias for v2 instead
    46  // of duplicating the files" thing we did was a bad thing to do.
    47
    48  // Performs authorization check based on the attributes associated with the
    49  // incoming request, and returns status `OK` or not `OK`.
    50  rpc Check(CheckRequest) returns (CheckResponse) {
    51  }
    52}
    53
    54message CheckRequest {
    55  option (udpa.annotations.versioning).previous_message_type = "envoy.service.auth.v3.CheckRequest";
    56
    57  // The request attributes.
    58  AttributeContext attributes = 1;
    59}
    60
    61// HTTP attributes for a denied response.
    62message DeniedHttpResponse {
    63  option (udpa.annotations.versioning).previous_message_type =
    64      "envoy.service.auth.v3.DeniedHttpResponse";
    65
    66  // This field allows the authorization service to send a HTTP response status
    67  // code to the downstream client other than 403 (Forbidden).
    68  type.v3.HttpStatus status = 1 [(validate.rules).message = {required: true}];
    69
    70  // This field allows the authorization service to send HTTP response headers
    71  // to the downstream client. Note that the `append` field in `HeaderValueOption` defaults to
    72  // false when used in this message.
    73  repeated config.core.v4alpha.HeaderValueOption headers = 2;
    74
    75  // This field allows the authorization service to send a response body data
    76  // to the downstream client.
    77  string body = 3;
    78}
    79
    80// HTTP attributes for an OK response.
    81// [#next-free-field: 6]
    82message OkHttpResponse {
    83  option (udpa.annotations.versioning).previous_message_type =
    84      "envoy.service.auth.v3.OkHttpResponse";
    85
    86  reserved 3;
    87
    88  reserved "dynamic_metadata";
    89
    90  // HTTP entity headers in addition to the original request headers. This allows the authorization
    91  // service to append, to add or to override headers from the original request before
    92  // dispatching it to the upstream. Note that the `append` field in `HeaderValueOption` defaults to
    93  // false when used in this message. By setting the `append` field to `true`,
    94  // the filter will append the correspondent header value to the matched request header.
    95  // By leaving `append` as false, the filter will either add a new header, or override an existing
    96  // one if there is a match.
    97  repeated config.core.v4alpha.HeaderValueOption headers = 2;
    98
    99  // HTTP entity headers to remove from the original request before dispatching
   100  // it to the upstream. This allows the authorization service to act on auth
   101  // related headers (like `Authorization`), process them, and consume them.
   102  // Under this model, the upstream will either receive the request (if it's
   103  // authorized) or not receive it (if it's not), but will not see headers
   104  // containing authorization credentials.
   105  //
   106  // Pseudo headers (such as `:authority`, `:method`, `:path` etc), as well as
   107  // the header `Host`, may not be removed as that would make the request
   108  // malformed. If mentioned in `headers_to_remove` these special headers will
   109  // be ignored.
   110  //
   111  // When using the HTTP service this must instead be set by the HTTP
   112  // authorization service as a comma separated list like so:
   113  // ``x-envoy-auth-headers-to-remove: one-auth-header, another-auth-header``.
   114  repeated string headers_to_remove = 5;
   115}
   116
   117// Intended for gRPC and Network Authorization servers `only`.
   118message CheckResponse {
   119  option (udpa.annotations.versioning).previous_message_type =
   120      "envoy.service.auth.v3.CheckResponse";
   121
   122  // Status `OK` allows the request. Any other status indicates the request should be denied.
   123  google.rpc.Status status = 1;
   124
   125  // An message that contains HTTP response attributes. This message is
   126  // used when the authorization service needs to send custom responses to the
   127  // downstream client or, to modify/add request headers being dispatched to the upstream.
   128  oneof http_response {
   129    // Supplies http attributes for a denied response.
   130    DeniedHttpResponse denied_response = 2;
   131
   132    // Supplies http attributes for an ok response.
   133    OkHttpResponse ok_response = 3;
   134  }
   135
   136  // Optional response metadata that will be emitted as dynamic metadata to be consumed by the next
   137  // filter. This metadata lives in a namespace specified by the canonical name of extension filter
   138  // that requires it:
   139  //
   140  // - :ref:`envoy.filters.http.ext_authz <config_http_filters_ext_authz_dynamic_metadata>` for HTTP filter.
   141  // - :ref:`envoy.filters.network.ext_authz <config_network_filters_ext_authz_dynamic_metadata>` for network filter.
   142  google.protobuf.Struct dynamic_metadata = 4;
   143}

View as plain text