rbac: add unified matcher for RBAC filters

api/envoy/config/rbac/v3/rbac.proto

@@ -310,3 +310,26 @@ message Principal {
     Principal not_id = 8;
   }
 }
+
+// Action defines the result of allowance or denial when a request matches the matcher.
+message Action {
+  // The name indicates the matcher name.
+  string name = 1 [(validate.rules).string = {min_len: 1}];
+
+  // The action to take if the matcher matches. Every action either allows or denies a request,
+  // and can also carry out action-specific operations.
+  //
+  // Actions:
+  //
+  //  * ALLOW: Allows the request if and only if the matcher that matches the
+  //    request.
+  //  * DENY: Allows the request if and only if the matcher that does not match
+  //    the request.
+  //  * LOG: Allows the request if and only if the matcher that matches the
+  //    request. If the matcher matches, the dynamic metadata key
+  //    `access_log_hint` is set to the value `true` under the shared key
+  //    namespace 'envoy.common'. If the matcher does not match, it is set to
+  //    `false`.
+  //
+  RBAC.Action action = 2;
+}

api/envoy/extensions/filters/http/rbac/v3/BUILD

@@ -8,5 +8,7 @@ api_proto_package(
     deps = [
         "//envoy/config/rbac/v3:pkg",
         "@com_github_cncf_udpa//udpa/annotations:pkg",
+        "@com_github_cncf_udpa//xds/annotations/v3:pkg",
+        "@com_github_cncf_udpa//xds/type/matcher/v3:pkg",
     ],
 )

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

@@ -4,6 +4,10 @@ package envoy.extensions.filters.http.rbac.v3;
 
 import "envoy/config/rbac/v3/rbac.proto";
 
+import "xds/annotations/v3/status.proto";
+import "xds/type/matcher/v3/matcher.proto";
+
+import "udpa/annotations/migrate.proto";
 import "udpa/annotations/status.proto";
 import "udpa/annotations/versioning.proto";
 
@@ -18,19 +22,41 @@ option (udpa.annotations.file_status).package_version_status = ACTIVE;
 // [#extension: envoy.filters.http.rbac]
 
 // RBAC filter config.
+// [#next-free-field: 6]
 message RBAC {
   option (udpa.annotations.versioning).previous_message_type =
       "envoy.config.filter.http.rbac.v2.RBAC";
 
   // Specify the RBAC rules to be applied globally.
   // If absent, no enforcing RBAC policy will be applied.
   // If present and empty, DENY.
-  config.rbac.v3.RBAC rules = 1;
+  config.rbac.v3.RBAC rules = 1
+      [(udpa.annotations.field_migrate).oneof_promotion = "rules_specifier"];
+
+  // The match tree to use when resolving RBAC action for incoming requests. Requests do not
+  // match any matcher will be denied.
+  // If absent, no enforcing RBAC matcher will be applied.
+  // If present and empty, deny all requests.
+  // If both rules and matcher are configured, the matcher will be ignored.
+  xds.type.matcher.v3.Matcher matcher = 4 [
+    (udpa.annotations.field_migrate).oneof_promotion = "rules_specifier",
+    (xds.annotations.v3.field_status).work_in_progress = true
+  ];
 
   // Shadow rules are not enforced by the filter (i.e., returning a 403)
   // but will emit stats and logs and can be used for rule testing.
   // If absent, no shadow RBAC policy will be applied.
-  config.rbac.v3.RBAC shadow_rules = 2;
+  config.rbac.v3.RBAC shadow_rules = 2
+      [(udpa.annotations.field_migrate).oneof_promotion = "shadow_rules_specifier"];
+
+  // The match tree to use for emitting stats and logs which can be used for rule testing for
+  // incoming requests.
+  // If absent, no shadow matcher will be applied.
+  // If both shadow rules and shadow matcher are configured, the shadow matcher will be ignored.
+  xds.type.matcher.v3.Matcher shadow_matcher = 5 [
+    (udpa.annotations.field_migrate).oneof_promotion = "shadow_rules_specifier",
+    (xds.annotations.v3.field_status).work_in_progress = true
+  ];
 
   // If specified, shadow rules will emit stats with the given prefix.
   // This is useful to distinguish the stat when there are more than 1 RBAC filter configured with

api/envoy/extensions/filters/network/rbac/v3/BUILD

@@ -8,5 +8,7 @@ api_proto_package(
     deps = [
         "//envoy/config/rbac/v3:pkg",
         "@com_github_cncf_udpa//udpa/annotations:pkg",
+        "@com_github_cncf_udpa//xds/annotations/v3:pkg",
+        "@com_github_cncf_udpa//xds/type/matcher/v3:pkg",
     ],
 )

api/envoy/extensions/filters/network/rbac/v3/rbac.proto

@@ -4,6 +4,10 @@ package envoy.extensions.filters.network.rbac.v3;
 
 import "envoy/config/rbac/v3/rbac.proto";
 
+import "xds/annotations/v3/status.proto";
+import "xds/type/matcher/v3/matcher.proto";
+
+import "udpa/annotations/migrate.proto";
 import "udpa/annotations/status.proto";
 import "udpa/annotations/versioning.proto";
 import "validate/validate.proto";
@@ -22,7 +26,7 @@ option (udpa.annotations.file_status).package_version_status = ACTIVE;
 //
 // Header should not be used in rules/shadow_rules in RBAC network filter as
 // this information is only available in :ref:`RBAC http filter <config_http_filters_rbac>`.
-// [#next-free-field: 6]
+// [#next-free-field: 8]
 message RBAC {
   option (udpa.annotations.versioning).previous_message_type =
       "envoy.config.filter.network.rbac.v2.RBAC";
@@ -41,12 +45,33 @@ message RBAC {
   // Specify the RBAC rules to be applied globally.
   // If absent, no enforcing RBAC policy will be applied.
   // If present and empty, DENY.
-  config.rbac.v3.RBAC rules = 1;
+  config.rbac.v3.RBAC rules = 1
+      [(udpa.annotations.field_migrate).oneof_promotion = "rules_specifier"];
+
+  // The match tree to use when resolving RBAC action for incoming connections. Connections do
+  // not match any matcher will be denied.
+  // If absent, no enforcing RBAC matcher will be applied.
+  // If present and empty, deny all connections.
+  // If both rules and matcher are configured, the matcher will be ignored.
+  xds.type.matcher.v3.Matcher matcher = 6 [
+    (udpa.annotations.field_migrate).oneof_promotion = "rules_specifier",
+    (xds.annotations.v3.field_status).work_in_progress = true
+  ];
 
   // Shadow rules are not enforced by the filter but will emit stats and logs
   // and can be used for rule testing.
   // If absent, no shadow RBAC policy will be applied.
-  config.rbac.v3.RBAC shadow_rules = 2;
+  config.rbac.v3.RBAC shadow_rules = 2
+      [(udpa.annotations.field_migrate).oneof_promotion = "shadow_rules_specifier"];
+
+  // The match tree to use for emitting stats and logs which can be used for rule testing for
+  // incoming connections.
+  // If absent, no shadow matcher will be applied.
+  // If both shadow rules and shadow matcher are configured, the shadow matcher will be ignored.
+  xds.type.matcher.v3.Matcher shadow_matcher = 7 [
+    (udpa.annotations.field_migrate).oneof_promotion = "shadow_rules_specifier",
+    (xds.annotations.v3.field_status).work_in_progress = true
+  ];
 
   // If specified, shadow rules will emit stats with the given prefix.
   // This is useful to distinguish the stat when there are more than 1 RBAC filter configured with

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

@@ -3,10 +3,10 @@
 Role Based Access Control (RBAC) Filter
 =======================================
 
-The RBAC filter is used to authorize actions (permissions) by identified downstream clients
-(principals). This is useful to explicitly manage callers to an application and protect it from
-unexpected or forbidden agents. The filter supports configuration with either a safe-list (ALLOW) or
-block-list (DENY) set of policies based off properties of the connection (IPs, ports, SSL subject)
+The RBAC filter is used to authorize actions by identified downstream clients. This is useful to
+explicitly manage callers to an application and protect it from unexpected or forbidden agents. The
+filter supports configuration with either a safe-list (ALLOW) or block-list (DENY) set of policies,
+or a matcher with different actions, based off properties of the connection (IPs, ports, SSL subject)
 as well as the incoming request's HTTP headers. This filter also supports policy in both enforcement
 and shadow mode, shadow mode won't effect real users, it is used to test that a new set of policies
 work before rolling out to production.

docs/root/configuration/listeners/network_filters/rbac_filter.rst

@@ -3,10 +3,10 @@
 Role Based Access Control (RBAC) Network Filter
 ===============================================
 
-The RBAC network filter is used to authorize actions (permissions) by identified downstream clients
-(principals). This is useful to explicitly manage callers to an application and protect it from
-unexpected or forbidden agents. The filter supports configuration with either a safe-list (ALLOW) or
-block-list (DENY) set of policies based on properties of the connection (IPs, ports, SSL subject).
+The RBAC network filter is used to authorize actions by identified downstream clients. This is useful
+to explicitly manage callers to an application and protect it from unexpected or forbidden agents.
+The filter supports configuration with either a safe-list (ALLOW) or block-list (DENY) set of policies,
+or a matcher with different actions, based on properties of the connection (IPs, ports, SSL subject).
 This filter also supports policy in both enforcement and shadow modes. Shadow mode won't effect real
 users, it is used to test that a new set of policies work before rolling out to production.
 

docs/root/intro/arch_overview/security/rbac_filter.rst

@@ -15,6 +15,10 @@ or as a :ref:`HTTP filter <config_http_filters_rbac>` or both. If the request is
 by the network filter then the connection will be closed. If the request is deemed unauthorized by
 the HTTP filter the request will be denied with 403 (Forbidden) response.
 
+The RBAC filter's rules can be either configured with a list of
+:ref:`policies <envoy_v3_api_field_config.rbac.v3.RBAC.policies>` or the
+:ref:`matching API <envoy_v3_api_msg_.xds.type.matcher.v3.Matcher>`.
+
 Policy
 ------
 
@@ -26,13 +30,26 @@ the request, for example, the method and path of a HTTP request. The principal s
 downstream client identities of the request, for example, the URI SAN of the downstream client
 certificate. A policy is matched if its permissions and principals are matched at the same time.
 
-Shadow Policy
--------------
+.. _arch_overview_rbac_matcher:
+
+Matcher
+-------
+Instead of specifying :ref:`policies <envoy_v3_api_field_config.rbac.v3.RBAC.policies>`, the RBAC
+filter can also be configured with the :ref:`matching API <envoy_v3_api_msg_.xds.type.matcher.v3.Matcher>`.
+:ref:`Network inputs <extension_category_envoy.matching.network.input>` are available for both RBAC
+network filter and HTTP filter, and :ref:`HTTP inputs <extension_category_envoy.matching.http.input>`
+are only available in HTTP filter.
+
+RBAC matchers are not compatible with the :ref:`matching API <envoy_v3_api_msg_.xds.type.matcher.v3.Matcher>`.
+
+Shadow Policy and Shadow Matcher
+--------------------------------
 
 The filter can be configured with a
-:ref:`shadow policy <envoy_v3_api_field_extensions.filters.http.rbac.v3.RBAC.shadow_rules>` that doesn't
-have any effect (i.e. not deny the request) but only emit stats and log the result. This is useful
-for testing a rule before applying in production.
+:ref:`shadow policy <envoy_v3_api_field_extensions.filters.http.rbac.v3.RBAC.shadow_rules>` or a
+:ref:`shadow matcher <envoy_v3_api_field_extensions.filters.http.rbac.v3.RBAC.shadow_matcher>` that
+doesn't have any effect (i.e. not deny the request) but only emit stats and log the result. This is
+useful for testing a rule before applying in production.
 
 .. _arch_overview_condition:
 

docs/root/version_history/current.rst

@@ -24,6 +24,7 @@ Removed Config or Runtime
 New Features
 ------------
 * ext_proc: added support for per-route :ref:`grpc_service <envoy_v3_api_field_extensions.filters.http.ext_proc.v3.ExtProcOverrides.grpc_service>`.
+* rbac: added :ref:`matcher <arch_overview_rbac_matcher>` for selecting connections and requests to different actions.
 
 Deprecated
 ----------

source/common/http/matching/inputs.cc

@@ -5,10 +5,20 @@
 namespace Envoy {
 namespace Http {
 namespace Matching {
+
+using HttpRequestHeadersDataInputFactory = HttpRequestHeadersDataInputFactoryBase<HttpMatchingData>;
+using HttpResponseHeadersDataInputFactory =
+    HttpResponseHeadersDataInputFactoryBase<HttpMatchingData>;
+using HttpRequestTrailersDataInputFactory =
+    HttpRequestTrailersDataInputFactoryBase<HttpMatchingData>;
+using HttpResponseTrailersDataInputFactory =
+    HttpResponseTrailersDataInputFactoryBase<HttpMatchingData>;
+
 REGISTER_FACTORY(HttpRequestHeadersDataInputFactory, Matcher::DataInputFactory<HttpMatchingData>);
 REGISTER_FACTORY(HttpResponseHeadersDataInputFactory, Matcher::DataInputFactory<HttpMatchingData>);
 REGISTER_FACTORY(HttpRequestTrailersDataInputFactory, Matcher::DataInputFactory<HttpMatchingData>);
 REGISTER_FACTORY(HttpResponseTrailersDataInputFactory, Matcher::DataInputFactory<HttpMatchingData>);
+
 } // namespace Matching
 } // namespace Http
 } // namespace Envoy