Role Based Access Control (RBAC) (proto)

config.rbac.v3.RBAC

Role Based Access Control (RBAC) provides service-level and method-level access control for a service. Requests are allowed or denied based on the action and whether a matching policy is found. For instance, if the action is ALLOW and a matching policy is found the request should be allowed.

RBAC can also be used to make access logging decisions by communicating with access loggers through dynamic metadata. When the action is LOG and at least one policy matches, the access_log_hint value in the shared key namespace ‘envoy.common’ is set to true indicating the request should be logged.

Here is an example of RBAC configuration. It has two policies:

Service account cluster.local/ns/default/sa/admin has full access to the service, and so does “cluster.local/ns/default/sa/superuser”.
Any user can read (GET) the service at paths with prefix /products, so long as the destination port is either 80 or 443.

action: ALLOW
policies:
  "service-admin":
    permissions:
      - any: true
    principals:
      - authenticated:
          principal_name:
            exact: "cluster.local/ns/default/sa/admin"
      - authenticated:
          principal_name:
            exact: "cluster.local/ns/default/sa/superuser"
  "product-viewer":
    permissions:
        - and_rules:
            rules:
              - header:
                  name: ":method"
                  string_match:
                    exact: "GET"
              - url_path:
                  path: { prefix: "/products" }
              - or_rules:
                  rules:
                    - destination_port: 80
                    - destination_port: 443
    principals:
      - any: true

{
  "action": ...,
  "policies": {...}
}

action

(config.rbac.v3.RBAC.Action) The action to take if a policy 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 there is a policy that matches the request.

DENY: Allows the request if and only if there are no policies that match the request.

LOG: Allows all requests. If at least one policy matches, the dynamic metadata key access_log_hint is set to the value true under the shared key namespace envoy.common. If no policies match, it is set to false. Other actions do not modify this key.

policies: (repeated map<string, config.rbac.v3.Policy>) Maps from policy name to policy. A match occurs when at least one policy matches the request. The policies are evaluated in lexicographic order of the policy name.

config.rbac.v3.RBAC.AuditLoggingOptions

[config.rbac.v3.RBAC.AuditLoggingOptions proto]

Enum config.rbac.v3.RBAC.AuditLoggingOptions.AuditCondition

[config.rbac.v3.RBAC.AuditLoggingOptions.AuditCondition proto]

Deny and allow here refer to RBAC decisions, not actions.

NONE: (DEFAULT) ⁣Never audit.

ON_DENY: ⁣Audit when RBAC denies the request.

ON_ALLOW: ⁣Audit when RBAC allows the request.

ON_DENY_AND_ALLOW: ⁣Audit whether RBAC allows or denies the request.

Enum config.rbac.v3.RBAC.Action

[config.rbac.v3.RBAC.Action proto]

Should we do safe-list or block-list style access control?

ALLOW: (DEFAULT) ⁣The policies grant access to principals. The rest are denied. This is safe-list style access control. This is the default type.

DENY: ⁣The policies deny access to principals. The rest are allowed. This is block-list style access control.

LOG: ⁣The policies set the access_log_hint dynamic metadata key based on if requests match. All requests are allowed.

config.rbac.v3.Policy

[config.rbac.v3.Policy proto]

Policy specifies a role and the principals that are assigned/denied the role. A policy matches if and only if at least one of its permissions match the action taking place AND at least one of its principals match the downstream AND the condition is true if specified.

{
  "permissions": [],
  "principals": [],
  "condition": {...}
}

permissions: (repeated config.rbac.v3.Permission, REQUIRED) Required. The set of permissions that define a role. Each permission is matched with OR semantics. To match all actions for this policy, a single Permission with the any field set to true should be used.

principals: (repeated config.rbac.v3.Principal, REQUIRED) Required. The set of principals that are assigned/denied the role based on “action”. Each principal is matched with OR semantics. To match all downstreams for this policy, a single Principal with the any field set to true should be used.

condition: (.google.api.expr.v1alpha1.Expr) An optional symbolic expression specifying an access control condition. The condition is combined with the permissions and the principals as a clause with AND semantics. Only be used when checked_condition is not used.

config.rbac.v3.SourcedMetadata

[config.rbac.v3.SourcedMetadata proto]

SourcedMetadata enables matching against metadata from different sources in the request processing pipeline. It extends the base MetadataMatcher functionality by allowing specification of where the metadata should be sourced from, rather than only matching against dynamic metadata.

The matcher can be configured to look up metadata from: * Dynamic metadata: Runtime metadata added by filters during request processing * Route metadata: Static metadata configured on the route entry

{
  "metadata_matcher": {...},
  "metadata_source": ...
}

metadata_matcher: (type.matcher.v3.MetadataMatcher, REQUIRED) Metadata matcher configuration that defines what metadata to match against. This includes the filter name, metadata key path, and expected value.

metadata_source: (config.rbac.v3.MetadataSource) Specifies which metadata source should be used for matching. If not set, defaults to DYNAMIC (dynamic metadata). Set to ROUTE to match against static metadata configured on the route entry.

config.rbac.v3.Permission

[config.rbac.v3.Permission proto]

Permission defines an action (or actions) that a principal can take.

{
  "and_rules": {...},
  "or_rules": {...},
  "any": ...,
  "header": {...},
  "url_path": {...},
  "destination_ip": {...},
  "destination_port": ...,
  "destination_port_range": {...},
  "metadata": {...},
  "not_rule": {...},
  "requested_server_name": {...},
  "matcher": {...},
  "uri_template": {...},
  "sourced_metadata": {...}
}

and_rules

(config.rbac.v3.Permission.Set) A set of rules that all must match in order to define the action.

Precisely one of and_rules, or_rules, any, header, url_path, destination_ip, destination_port, destination_port_range, metadata, not_rule, requested_server_name, matcher, uri_template, sourced_metadata must be set.

or_rules

(config.rbac.v3.Permission.Set) A set of rules where at least one must match in order to define the action.

Precisely one of and_rules, or_rules, any, header, url_path, destination_ip, destination_port, destination_port_range, metadata, not_rule, requested_server_name, matcher, uri_template, sourced_metadata must be set.

any

(bool) When any is set, it matches any action.

Precisely one of and_rules, or_rules, any, header, url_path, destination_ip, destination_port, destination_port_range, metadata, not_rule, requested_server_name, matcher, uri_template, sourced_metadata must be set.

header

(config.route.v3.HeaderMatcher) A header (or pseudo-header such as :path or :method) on the incoming HTTP request. Only available for HTTP request. Note: the pseudo-header :path includes the query and fragment string. Use the url_path field if you want to match the URL path without the query and fragment string.

Precisely one of and_rules, or_rules, any, header, url_path, destination_ip, destination_port, destination_port_range, metadata, not_rule, requested_server_name, matcher, uri_template, sourced_metadata must be set.

url_path

(type.matcher.v3.PathMatcher) A URL path on the incoming HTTP request. Only available for HTTP.

Precisely one of and_rules, or_rules, any, header, url_path, destination_ip, destination_port, destination_port_range, metadata, not_rule, requested_server_name, matcher, uri_template, sourced_metadata must be set.

destination_ip

(config.core.v3.CidrRange) A CIDR block that describes the destination IP.

Precisely one of and_rules, or_rules, any, header, url_path, destination_ip, destination_port, destination_port_range, metadata, not_rule, requested_server_name, matcher, uri_template, sourced_metadata must be set.

destination_port

(uint32) A port number that describes the destination port connecting to.

Precisely one of and_rules, or_rules, any, header, url_path, destination_ip, destination_port, destination_port_range, metadata, not_rule, requested_server_name, matcher, uri_template, sourced_metadata must be set.

destination_port_range

(type.v3.Int32Range) A port number range that describes a range of destination ports connecting to.

Precisely one of and_rules, or_rules, any, header, url_path, destination_ip, destination_port, destination_port_range, metadata, not_rule, requested_server_name, matcher, uri_template, sourced_metadata must be set.

metadata

(type.matcher.v3.MetadataMatcher) Metadata that describes additional information about the action. This field is deprecated; please use sourced_metadata instead.

Precisely one of and_rules, or_rules, any, header, url_path, destination_ip, destination_port, destination_port_range, metadata, not_rule, requested_server_name, matcher, uri_template, sourced_metadata must be set.

not_rule

(config.rbac.v3.Permission) Negates matching the provided permission. For instance, if the value of not_rule would match, this permission would not match. Conversely, if the value of not_rule would not match, this permission would match.

Precisely one of and_rules, or_rules, any, header, url_path, destination_ip, destination_port, destination_port_range, metadata, not_rule, requested_server_name, matcher, uri_template, sourced_metadata must be set.

requested_server_name

(type.matcher.v3.StringMatcher) The request server from the client’s connection request. This is typically TLS SNI.

Attention

The behavior of this field may be affected by how Envoy is configured as explained below.

If the TLS Inspector filter is not added, and if a FilterChainMatch is not defined for the server name, a TLS connection’s requested SNI server name will be treated as if it wasn’t present.
A listener filter may overwrite a connection’s requested server name within Envoy.

Please refer to this FAQ entry to learn to setup SNI.

Precisely one of and_rules, or_rules, any, header, url_path, destination_ip, destination_port, destination_port_range, metadata, not_rule, requested_server_name, matcher, uri_template, sourced_metadata must be set.

matcher

(config.core.v3.TypedExtensionConfig) Extension for configuring custom matchers for RBAC.

Tip

This extension category has the following known extensions:

envoy.rbac.matchers.upstream_ip_port

Precisely one of and_rules, or_rules, any, header, url_path, destination_ip, destination_port, destination_port_range, metadata, not_rule, requested_server_name, matcher, uri_template, sourced_metadata must be set.

uri_template

(config.core.v3.TypedExtensionConfig) URI template path matching.

Tip

This extension category has the following known extensions:

envoy.path.match.uri_template.uri_template_matcher

Precisely one of and_rules, or_rules, any, header, url_path, destination_ip, destination_port, destination_port_range, metadata, not_rule, requested_server_name, matcher, uri_template, sourced_metadata must be set.

sourced_metadata

(config.rbac.v3.SourcedMetadata) Matches against metadata from either dynamic state or route configuration. Preferred over the metadata field as it provides more flexibility in metadata source selection.

Precisely one of and_rules, or_rules, any, header, url_path, destination_ip, destination_port, destination_port_range, metadata, not_rule, requested_server_name, matcher, uri_template, sourced_metadata must be set.

config.rbac.v3.Permission.Set

[config.rbac.v3.Permission.Set proto]

Used in the and_rules and or_rules fields in the rule oneof. Depending on the context, each are applied with the associated behavior.

{
  "rules": []
}

rules: (repeated config.rbac.v3.Permission, REQUIRED)

config.rbac.v3.Principal

[config.rbac.v3.Principal proto]

Principal defines an identity or a group of identities for a downstream subject.

{
  "and_ids": {...},
  "or_ids": {...},
  "any": ...,
  "authenticated": {...},
  "source_ip": {...},
  "direct_remote_ip": {...},
  "remote_ip": {...},
  "header": {...},
  "url_path": {...},
  "metadata": {...},
  "filter_state": {...},
  "not_id": {...},
  "sourced_metadata": {...}
}

and_ids

(config.rbac.v3.Principal.Set) A set of identifiers that all must match in order to define the downstream.

Precisely one of and_ids, or_ids, any, authenticated, source_ip, direct_remote_ip, remote_ip, header, url_path, metadata, filter_state, not_id, sourced_metadata must be set.

or_ids

(config.rbac.v3.Principal.Set) A set of identifiers at least one must match in order to define the downstream.

Precisely one of and_ids, or_ids, any, authenticated, source_ip, direct_remote_ip, remote_ip, header, url_path, metadata, filter_state, not_id, sourced_metadata must be set.

any

(bool) When any is set, it matches any downstream.

Precisely one of and_ids, or_ids, any, authenticated, source_ip, direct_remote_ip, remote_ip, header, url_path, metadata, filter_state, not_id, sourced_metadata must be set.

authenticated

(config.rbac.v3.Principal.Authenticated) Authenticated attributes that identify the downstream.

Precisely one of and_ids, or_ids, any, authenticated, source_ip, direct_remote_ip, remote_ip, header, url_path, metadata, filter_state, not_id, sourced_metadata must be set.

source_ip

(config.core.v3.CidrRange) A CIDR block that describes the downstream IP. This address will honor proxy protocol, but will not honor XFF.

This field is deprecated; either use remote_ip for the same behavior, or use direct_remote_ip.

Precisely one of and_ids, or_ids, any, authenticated, source_ip, direct_remote_ip, remote_ip, header, url_path, metadata, filter_state, not_id, sourced_metadata must be set.

direct_remote_ip

(config.core.v3.CidrRange) A CIDR block that describes the downstream remote/origin address. Note: This is always the physical peer even if the remote_ip is inferred from for example the x-forwarder-for header, proxy protocol, etc.

Precisely one of and_ids, or_ids, any, authenticated, source_ip, direct_remote_ip, remote_ip, header, url_path, metadata, filter_state, not_id, sourced_metadata must be set.

remote_ip

(config.core.v3.CidrRange) A CIDR block that describes the downstream remote/origin address. Note: This may not be the physical peer and could be different from the direct_remote_ip. E.g, if the remote ip is inferred from for example the x-forwarder-for header, proxy protocol, etc.

Precisely one of and_ids, or_ids, any, authenticated, source_ip, direct_remote_ip, remote_ip, header, url_path, metadata, filter_state, not_id, sourced_metadata must be set.

header

(config.route.v3.HeaderMatcher) A header (or pseudo-header such as :path or :method) on the incoming HTTP request. Only available for HTTP request. Note: the pseudo-header :path includes the query and fragment string. Use the url_path field if you want to match the URL path without the query and fragment string.

Precisely one of and_ids, or_ids, any, authenticated, source_ip, direct_remote_ip, remote_ip, header, url_path, metadata, filter_state, not_id, sourced_metadata must be set.

url_path

(type.matcher.v3.PathMatcher) A URL path on the incoming HTTP request. Only available for HTTP.

Precisely one of and_ids, or_ids, any, authenticated, source_ip, direct_remote_ip, remote_ip, header, url_path, metadata, filter_state, not_id, sourced_metadata must be set.

metadata

(type.matcher.v3.MetadataMatcher) Metadata that describes additional information about the principal. This field is deprecated; please use sourced_metadata instead.

Precisely one of and_ids, or_ids, any, authenticated, source_ip, direct_remote_ip, remote_ip, header, url_path, metadata, filter_state, not_id, sourced_metadata must be set.

filter_state

(type.matcher.v3.FilterStateMatcher) Identifies the principal using a filter state object.

Precisely one of and_ids, or_ids, any, authenticated, source_ip, direct_remote_ip, remote_ip, header, url_path, metadata, filter_state, not_id, sourced_metadata must be set.

not_id

(config.rbac.v3.Principal) Negates matching the provided principal. For instance, if the value of not_id would match, this principal would not match. Conversely, if the value of not_id would not match, this principal would match.

Precisely one of and_ids, or_ids, any, authenticated, source_ip, direct_remote_ip, remote_ip, header, url_path, metadata, filter_state, not_id, sourced_metadata must be set.

sourced_metadata

(config.rbac.v3.SourcedMetadata) Matches against metadata from either dynamic state or route configuration. Preferred over the metadata field as it provides more flexibility in metadata source selection.

Precisely one of and_ids, or_ids, any, authenticated, source_ip, direct_remote_ip, remote_ip, header, url_path, metadata, filter_state, not_id, sourced_metadata must be set.

config.rbac.v3.Principal.Set

[config.rbac.v3.Principal.Set proto]

Used in the and_ids and or_ids fields in the identifier oneof. Depending on the context, each are applied with the associated behavior.

{
  "ids": []
}

ids: (repeated config.rbac.v3.Principal, REQUIRED)

config.rbac.v3.Principal.Authenticated

[config.rbac.v3.Principal.Authenticated proto]

Authentication attributes for a downstream.

{
  "principal_name": {...}
}

principal_name: (type.matcher.v3.StringMatcher) The name of the principal. If set, The URI SAN or DNS SAN in that order is used from the certificate, otherwise the subject field is used. If unset, it applies to any user that is authenticated.

config.rbac.v3.Action

[config.rbac.v3.Action proto]

Action defines the result of allowance or denial when a request matches the matcher.

{
  "name": ...,
  "action": ...
}

name: (string, REQUIRED) The name indicates the policy name.

action

(config.rbac.v3.RBAC.Action) 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: If the request gets matched on ALLOW, it is permitted.

DENY: If the request gets matched on DENY, it is not permitted.

LOG: If the request gets matched on LOG, it is permitted. Besides, the dynamic metadata key access_log_hint under the shared key namespace envoy.common will be set to the value true.

If the request cannot get matched, it will fallback to DENY.

Log behavior:

If the RBAC matcher contains at least one LOG action, the dynamic metadata key access_log_hint will be set based on if the request get matched on the LOG action.

Enum config.rbac.v3.MetadataSource

[config.rbac.v3.MetadataSource proto]

DYNAMIC: (DEFAULT) ⁣Query dynamic metadata

ROUTE: ⁣Query route metadata