ext_authz: support response headers on OK authorization checks (#14514)

Support adding response headers on OK authorization checks from ext_authz

Commit Message: ext_authz: support response headers on OK authorization checks
Additional Description:
Risk Level: low (opt-in feature, does nothing by default)
Testing: Added code to existing unit tests
Docs Changes: API protos documented
Release Notes: ext_authz: added :ref:`response_headers_to_add <envoy_v3_api_field_service.auth.v3.OkHttpResponse.response_headers_to_add>` to support sending response headers to downstream clients on OK external authorization checks.
Platform Specific Features:
Fixes #7986

Signed-off-by: John Esmet <john.esmet@gmail.com>

api/envoy/extensions/filters/http/ext_authz/v3/ext_authz.proto

@@ -182,6 +182,9 @@ message BufferSettings {
 // additional headers metadata may be added to the original client request. See
 // :ref:`allowed_upstream_headers
 // <envoy_api_field_extensions.filters.http.ext_authz.v3.AuthorizationResponse.allowed_upstream_headers>`
+// for details. Additionally, the filter may add additional headers to the client's response. See
+// :ref:`allowed_client_headers_on_success
+// <envoy_api_field_extensions.filters.http.ext_authz.v3.AuthorizationResponse.allowed_client_headers_on_success>`
 // for details.
 //
 // On other authorization response statuses, the filter will not allow traffic. Additional headers
@@ -252,6 +255,12 @@ message AuthorizationResponse {
   // (Host)* will be in the response to the client. When a header is included in this list, *Path*,
   // *Status*, *Content-Length*, *WWWAuthenticate* and *Location* are automatically added.
   type.matcher.v3.ListStringMatcher allowed_client_headers = 2;
+
+  // When this :ref:`list <envoy_api_msg_type.matcher.v3.ListStringMatcher>`. is set, authorization
+  // response headers that have a correspondent match will be added to the client's response when
+  // the authorization response itself is successful, i.e. not failed or denied. When this list is
+  // *not* set, no additional headers will be added to the client's response on success.
+  type.matcher.v3.ListStringMatcher allowed_client_headers_on_success = 4;
 }
 
 // Extra settings on a per virtualhost/route/weighted-cluster level.

api/envoy/service/auth/v3/external_auth.proto

@@ -50,7 +50,7 @@ message DeniedHttpResponse {
   type.v3.HttpStatus status = 1 [(validate.rules).message = {required: true}];
 
   // This field allows the authorization service to send HTTP response headers
-  // to the downstream client. Note that the `append` field in `HeaderValueOption` defaults to
+  // 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;
 
@@ -60,14 +60,14 @@ message DeniedHttpResponse {
 }
 
 // HTTP attributes for an OK response.
-// [#next-free-field: 6]
+// [#next-free-field: 7]
 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 `append` field in `HeaderValueOption` defaults to
+  // 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
@@ -96,6 +96,11 @@ message OkHttpResponse {
   // 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];
+
+  // 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;
 }
 
 // Intended for gRPC and Network Authorization servers `only`.

docs/root/version_history/current.rst

@@ -83,6 +83,8 @@ New Features
 * compression: add brotli :ref:`compressor <envoy_v3_api_msg_extensions.compression.brotli.compressor.v3.Brotli>` and :ref:`decompressor <envoy_v3_api_msg_extensions.compression.brotli.decompressor.v3.Brotli>`.
 * config: add `envoy.features.fail_on_any_deprecated_feature` runtime key, which matches the behaviour of compile-time flag `ENVOY_DISABLE_DEPRECATED_FEATURES`, i.e. use of deprecated fields will cause a crash.
 * dispatcher: supports a stack of `Envoy::ScopeTrackedObject` instead of a single tracked object. This will allow Envoy to dump more debug information on crash.
+* ext_authz: added :ref:`response_headers_to_add <envoy_v3_api_field_service.auth.v3.OkHttpResponse.response_headers_to_add>` to support sending response headers to downstream clients on OK authorization checks via gRPC.
+* ext_authz: added :ref:`allowed_client_headers_on_success <envoy_v3_api_field_extensions.filters.http.ext_authz.v3.AuthorizationResponse.allowed_client_headers_on_success>` to support sending response headers to downstream clients on OK external authorization checks via HTTP.
 * grpc_json_transcoder: added option :ref:`strict_http_request_validation <envoy_v3_api_field_extensions.filters.http.grpc_json_transcoder.v3.GrpcJsonTranscoder.strict_http_request_validation>` to reject invalid requests early.
 * grpc_json_transcoder: filter can now be configured on per-route/per-vhost level as well. Leaving empty list of services in the filter configuration disables transcoding on the specific route.
 * http: added support for `Envoy::ScopeTrackedObject` for HTTP/1 dispatching. Crashes while inside the dispatching loop should dump debug information.

source/extensions/filters/common/ext_authz/ext_authz.h

@@ -74,6 +74,10 @@ struct Response {
   // A set of HTTP headers returned by the authorization server, will be optionally added
   // (using "addCopy") to the request to the upstream server.
   Http::HeaderVector headers_to_add;
+  // A set of HTTP headers returned by the authorization server, will be optionally added
+  // (using "addCopy") to the response sent back to the downstream client on OK auth
+  // responses.
+  Http::HeaderVector response_headers_to_add;
   // A set of HTTP headers consumed by the authorization server, will be removed
   // from the request to the upstream server.
   std::vector<Envoy::Http::LowerCaseString> headers_to_remove;

source/extensions/filters/common/ext_authz/ext_authz_grpc_impl.cc

@@ -61,6 +61,12 @@ void GrpcClientImpl::onSuccess(std::unique_ptr<envoy::service::auth::v3::CheckRe
           authz_response->headers_to_remove.push_back(Http::LowerCaseString(header));
         }
       }
+      if (response->ok_response().response_headers_to_add_size() > 0) {
+        for (const auto& header : response->ok_response().response_headers_to_add()) {
+          authz_response->response_headers_to_add.emplace_back(
+              Http::LowerCaseString(header.header().key()), header.header().value());
+        }
+      }
     }
   } else {
     span.setTag(TracingConstants::get().TraceStatus, TracingConstants::get().TraceUnauthz);