Ext authz caching

.gitignore

@@ -40,6 +40,7 @@
 /api/bazel-*
 /bazel-*
 /ci/bazel-*
+/docs/bazel-*
 /mobile/bazel-*
 bazel.output.txt
 clang.bazelrc

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

@@ -4,6 +4,7 @@ package envoy.extensions.filters.http.ext_authz.v3;
 
 import "envoy/config/common/mutation_rules/v3/mutation_rules.proto";
 import "envoy/config/core/v3/base.proto";
+import "envoy/config/core/v3/extension.proto";
 import "envoy/config/core/v3/config_source.proto";
 import "envoy/config/core/v3/grpc_service.proto";
 import "envoy/config/core/v3/http_uri.proto";
@@ -30,7 +31,7 @@ option (udpa.annotations.file_status).package_version_status = ACTIVE;
 // External Authorization :ref:`configuration overview <config_http_filters_ext_authz>`.
 // [#extension: envoy.filters.http.ext_authz]
 
-// [#next-free-field: 33]
+// [#next-free-field: 34]
 message ExtAuthz {
   option (udpa.annotations.versioning).previous_message_type =
       "envoy.config.filter.http.ext_authz.v3.ExtAuthz";
@@ -397,6 +398,11 @@ message ExtAuthz {
   //
   // Defaults to ``false``.
   bool shadow_mode = 32;
+
+  // Optional configuration for a cache extension. If specified, the filter will
+  // attempt to lookup and populate the cache for authorization requests.
+  // The extension must implement the "envoy.filters.http.ext_authz.cache" interface.
+  config.core.v3.TypedExtensionConfig cache = 33;
 }
 
 // Serialized form of the shadow-mode authorization decision written to FilterState

docs/root/configuration/http/http_filters/ext_authz_filter.rst

@@ -176,6 +176,17 @@ In this configuration:
 This pattern provides clean separation between the decision logic (in the Lua filter) and the authorization
 enforcement (in ext_authz), while ensuring the ext_authz filter is only instantiated and invoked when needed.
 
+ExtAuthz Caching
+----------------
+The External Authorization filter supports caching authorization decisions to bypass the external authorization service call.
+
+To enable this, configure the :ref:`cache <envoy_v3_api_field_extensions.filters.http.ext_authz.v3.ExtAuthz.cache>` field with a cache extension configuration. The extension must implement the ``envoy.filters.http.ext_authz.cache`` interface.
+
+When caching is enabled, the filter will:
+1. Perform a cache lookup using the request attributes.
+2. If a cache hit occurs, the filter will bypass the external service call and apply the cached response (OK with mutations, Denied, or Error) directly.
+3. If a cache miss occurs, the filter will proceed with the live call to the external authorization service and, upon receiving a response, will populate the cache with the response.
+
 Statistics
 ----------
 .. _config_http_filters_ext_authz_stats:
@@ -199,6 +210,7 @@ The HTTP filter outputs statistics in the ``cluster.<route target cluster>.ext_a
   because it couldn't apply all header mutations"
   response_header_limits_reached, Counter, "Total responses for which ext_authz sent a local reply
   because it couldn't apply all header mutations"
+  invalid_cached_response, Counter, Total cached responses that failed to be Base64-decoded or parsed.
 
 Dynamic Metadata
 ----------------

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

@@ -469,6 +469,7 @@ ResponsePtr RawHttpClientImpl::toResponse(Http::ResponseMessagePtr message) {
                                 EMPTY_STRING,
                                 Http::Code::OK,
                                 Protobuf::Struct{}}};
+
     return std::move(ok.response_);
   }
 
@@ -496,6 +497,7 @@ ResponsePtr RawHttpClientImpl::toResponse(Http::ResponseMessagePtr message) {
                                   message->bodyAsString(),
                                   static_cast<Http::Code>(status_code),
                                   Protobuf::Struct{}}};
+
   return std::move(denied.response_);
 }
 

source/extensions/filters/http/ext_authz/BUILD

@@ -12,11 +12,25 @@ licenses(["notice"])  # Apache 2
 
 envoy_extension_package()
 
+envoy_cc_library(
+    name = "auth_cache_interface",
+    hdrs = ["auth_cache.h"],
+    deps = [
+        "//envoy/config:typed_config_interface",
+        "//envoy/http:header_map_interface",
+        "//envoy/stream_info:stream_info_interface",
+        "//envoy/tracing:tracer_interface",
+        "//source/extensions/filters/common/ext_authz:ext_authz_interface",
+        "@envoy_api//envoy/service/auth/v3:pkg_cc_proto",
+    ],
+)
+
 envoy_cc_library(
     name = "ext_authz",
     srcs = ["ext_authz.cc"],
     hdrs = ["ext_authz.h"],
     deps = [
+        ":auth_cache_interface",
         "//envoy/http:codes_interface",
         "//envoy/stats:stats_macros",
         "//source/common/buffer:buffer_lib",
@@ -44,6 +58,7 @@ envoy_cc_extension(
     srcs = ["config.cc"],
     hdrs = ["config.h"],
     deps = [
+        ":auth_cache_interface",
         ":ext_authz",
         "//envoy/registry",
         "//envoy/stats:stats_macros",

source/extensions/filters/http/ext_authz/auth_cache.h

@@ -0,0 +1,69 @@
+#pragma once
+
+#include <memory>
+
+#include "envoy/config/typed_config.h"
+#include "envoy/http/filter.h"
+#include "envoy/http/header_map.h"
+#include "envoy/service/auth/v3/external_auth.pb.h"
+#include "envoy/stream_info/stream_info.h"
+#include "envoy/tracing/tracer.h"
+
+#include "source/common/protobuf/protobuf.h"
+#include "source/extensions/filters/common/ext_authz/ext_authz.h"
+
+namespace Envoy {
+namespace Extensions {
+namespace HttpFilters {
+namespace ExtAuthz {
+
+struct RequestAttributes {
+  const Http::RequestHeaderMap& headers_;
+  Protobuf::Map<std::string, std::string> context_extensions_;
+  envoy::config::core::v3::Metadata metadata_context_;
+  envoy::config::core::v3::Metadata route_metadata_context_;
+};
+
+class AuthCache {
+public:
+  virtual ~AuthCache() = default;
+
+  using LookupCallback = std::function<void(Filters::Common::ExtAuthz::ResponsePtr&&)>;
+
+  /**
+   * Looks for a matching request/response pair in the cache.
+   * If lookup fails or misses, the callback should be invoked with nullptr.
+   * Lifetimes of the arguments passed to it must last until onDestroy is called.
+   * @param decoder_callbacks The stream decoder filter callbacks.
+   * @param attributes The RequestAttributes containing authorization context.
+   * @param cb The callback to invoke when the lookup completes.
+   */
+  virtual void lookup(Http::StreamDecoderFilterCallbacks& decoder_callbacks,
+                      const RequestAttributes& attributes, LookupCallback&& cb) = 0;
+
+  /**
+   * Inserts a response into the cache.
+   * @param response The Response received from the authz service.
+   */
+  virtual void insert(const Filters::Common::ExtAuthz::Response& response) = 0;
+
+  /**
+   * Called when the filter is being destroyed. The cache implementation must
+   * abort any in-progress asynchronous operations before returning.
+   */
+  virtual void onDestroy() = 0;
+};
+
+using AuthCachePtr = std::unique_ptr<AuthCache>;
+
+class AuthCacheFactory : public Config::TypedFactory {
+public:
+  virtual AuthCachePtr createAuthCache(const Protobuf::Message& config,
+                                       Server::Configuration::ServerFactoryContext& context) = 0;
+  std::string category() const override { return "envoy.filters.http.ext_authz.cache"; }
+};
+
+} // namespace ExtAuthz
+} // namespace HttpFilters
+} // namespace Extensions
+} // namespace Envoy

source/extensions/filters/http/ext_authz/config.cc

@@ -13,6 +13,7 @@
 #include "source/common/protobuf/utility.h"
 #include "source/extensions/filters/common/ext_authz/ext_authz_grpc_impl.h"
 #include "source/extensions/filters/common/ext_authz/ext_authz_http_impl.h"
+#include "source/extensions/filters/http/ext_authz/auth_cache.h"
 #include "source/extensions/filters/http/ext_authz/ext_authz.h"
 
 namespace Envoy {
@@ -25,6 +26,18 @@ Http::FilterFactoryCb ExtAuthzFilterConfig::createFilterFactoryFromProtoWithServ
     const std::string& stats_prefix, Server::Configuration::ServerFactoryContext& server_context) {
   const auto filter_config = std::make_shared<FilterConfig>(proto_config, server_context.scope(),
                                                             stats_prefix, server_context);
+
+  AuthCacheFactory* const cache_factory =
+      proto_config.has_cache()
+          ? &Config::Utility::getAndCheckFactory<AuthCacheFactory>(proto_config.cache())
+          : nullptr;
+  const std::shared_ptr<Protobuf::Message> shared_cache_config =
+      cache_factory != nullptr
+          ? Config::Utility::translateAnyToFactoryConfig(proto_config.cache().typed_config(),
+                                                         server_context.messageValidationVisitor(),
+                                                         *cache_factory)
+          : nullptr;
+
   // The callback is created in main thread and executed in worker thread, variables except factory
   // context must be captured by value into the callback.
   Http::FilterFactoryCb callback;
@@ -36,12 +49,16 @@ Http::FilterFactoryCb ExtAuthzFilterConfig::createFilterFactoryFromProtoWithServ
     const auto client_config =
         std::make_shared<Extensions::Filters::Common::ExtAuthz::ClientConfig>(
             proto_config, timeout_ms, proto_config.http_service().path_prefix(), server_context);
-    callback = [filter_config = std::move(filter_config), client_config,
-                &server_context](Http::FilterChainFactoryCallbacks& callbacks) {
+    callback = [filter_config = std::move(filter_config), client_config, &server_context,
+                cache_factory, shared_cache_config](Http::FilterChainFactoryCallbacks& callbacks) {
       auto client = std::make_unique<Extensions::Filters::Common::ExtAuthz::RawHttpClientImpl>(
           server_context.clusterManager(), client_config);
-      callbacks.addStreamFilter(
-          std::make_shared<Filter>(filter_config, std::move(client), server_context));
+      AuthCachePtr cache =
+          cache_factory != nullptr
+              ? cache_factory->createAuthCache(*shared_cache_config, server_context)
+              : nullptr;
+      callbacks.addStreamFilter(std::make_shared<Filter>(filter_config, std::move(client),
+                                                         server_context, std::move(cache)));
     };
   } else {
     // gRPC client.
@@ -56,16 +73,21 @@ Http::FilterFactoryCb ExtAuthzFilterConfig::createFilterFactoryFromProtoWithServ
     Envoy::Grpc::GrpcServiceConfigWithHashKey config_with_hash_key =
         Envoy::Grpc::GrpcServiceConfigWithHashKey(proto_config.grpc_service());
     callback = [&server_context, filter_config = std::move(filter_config), timeout,
-                config_with_hash_key](Http::FilterChainFactoryCallbacks& callbacks) {
+                config_with_hash_key, cache_factory,
+                shared_cache_config](Http::FilterChainFactoryCallbacks& callbacks) {
       auto client_or_error = server_context.clusterManager()
                                  .grpcAsyncClientManager()
                                  .getOrCreateRawAsyncClientWithHashKey(
                                      config_with_hash_key, server_context.scope(), true);
       THROW_IF_NOT_OK_REF(client_or_error.status());
       auto client = std::make_unique<Filters::Common::ExtAuthz::GrpcClientImpl>(
           client_or_error.value(), timeout);
-      callbacks.addStreamFilter(
-          std::make_shared<Filter>(filter_config, std::move(client), server_context));
+      AuthCachePtr cache =
+          cache_factory != nullptr
+              ? cache_factory->createAuthCache(*shared_cache_config, server_context)
+              : nullptr;
+      callbacks.addStreamFilter(std::make_shared<Filter>(filter_config, std::move(client),
+                                                         server_context, std::move(cache)));
     };
   }
   return callback;