1syntax = "proto3";
2
3package envoy.service.auth.v3;
4
5import "envoy/config/core/v3/base.proto";
6import "envoy/service/auth/v3/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.v3";
17option java_outer_classname = "ExternalAuthProto";
18option java_multiple_files = true;
19option java_generic_services = true;
20option (udpa.annotations.file_status).package_version_status = ACTIVE;
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.v2.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.v2.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.v3.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.v2.OkHttpResponse";
85
86 // HTTP entity headers in addition to the original request headers. This allows the authorization
87 // service to append, to add or to override headers from the original request before
88 // dispatching it to the upstream. Note that the `append` field in `HeaderValueOption` defaults to
89 // false when used in this message. By setting the `append` field to `true`,
90 // the filter will append the correspondent header value to the matched request header.
91 // By leaving `append` as false, the filter will either add a new header, or override an existing
92 // one if there is a match.
93 repeated config.core.v3.HeaderValueOption headers = 2;
94
95 // HTTP entity headers to remove from the original request before dispatching
96 // it to the upstream. This allows the authorization service to act on auth
97 // related headers (like `Authorization`), process them, and consume them.
98 // Under this model, the upstream will either receive the request (if it's
99 // authorized) or not receive it (if it's not), but will not see headers
100 // containing authorization credentials.
101 //
102 // Pseudo headers (such as `:authority`, `:method`, `:path` etc), as well as
103 // the header `Host`, may not be removed as that would make the request
104 // malformed. If mentioned in `headers_to_remove` these special headers will
105 // be ignored.
106 //
107 // When using the HTTP service this must instead be set by the HTTP
108 // authorization service as a comma separated list like so:
109 // ``x-envoy-auth-headers-to-remove: one-auth-header, another-auth-header``.
110 repeated string headers_to_remove = 5;
111
112 // This field has been deprecated in favor of :ref:`CheckResponse.dynamic_metadata
113 // <envoy_v3_api_field_service.auth.v3.CheckResponse.dynamic_metadata>`. Until it is removed,
114 // setting this field overrides :ref:`CheckResponse.dynamic_metadata
115 // <envoy_v3_api_field_service.auth.v3.CheckResponse.dynamic_metadata>`.
116 google.protobuf.Struct dynamic_metadata = 3 [deprecated = true];
117}
118
119// Intended for gRPC and Network Authorization servers `only`.
120message CheckResponse {
121 option (udpa.annotations.versioning).previous_message_type =
122 "envoy.service.auth.v2.CheckResponse";
123
124 // Status `OK` allows the request. Any other status indicates the request should be denied.
125 google.rpc.Status status = 1;
126
127 // An message that contains HTTP response attributes. This message is
128 // used when the authorization service needs to send custom responses to the
129 // downstream client or, to modify/add request headers being dispatched to the upstream.
130 oneof http_response {
131 // Supplies http attributes for a denied response.
132 DeniedHttpResponse denied_response = 2;
133
134 // Supplies http attributes for an ok response.
135 OkHttpResponse ok_response = 3;
136 }
137
138 // Optional response metadata that will be emitted as dynamic metadata to be consumed by the next
139 // filter. This metadata lives in a namespace specified by the canonical name of extension filter
140 // that requires it:
141 //
142 // - :ref:`envoy.filters.http.ext_authz <config_http_filters_ext_authz_dynamic_metadata>` for HTTP filter.
143 // - :ref:`envoy.filters.network.ext_authz <config_network_filters_ext_authz_dynamic_metadata>` for network filter.
144 google.protobuf.Struct dynamic_metadata = 4;
145}
View as plain text