External Authorization
External authorization architecture overview
This filter should be configured with the type URL
type.googleapis.com/envoy.extensions.filters.http.ext_authz.v3.ExtAuthz.
The external authorization filter calls an external gRPC or HTTP service to check whether an incoming HTTP request is authorized or not. If the request is deemed unauthorized, then the request will be denied normally with 403 (Forbidden) response. Note that sending additional custom metadata from the authorization service to the upstream, to the downstream or to the authorization service is also possible. This is explained in more details at HTTP filter.
The content of the requests that are passed to an authorization service is specified by CheckRequest.
The HTTP filter, using a gRPC/HTTP service, can be configured as follows. You can see all the configuration options at HTTP filter.
Configuration Examples
A sample filter configuration for a gRPC authorization server:
26 http_filters:
27 - name: envoy.filters.http.ext_authz
28 typed_config:
29 "@type": type.googleapis.com/envoy.extensions.filters.http.ext_authz.v3.ExtAuthz
30 grpc_service:
31 envoy_grpc:
32 cluster_name: ext-authz
33 # Default is 200ms; override if your server needs e.g. warmup time.
34 timeout: 0.5s
35 include_peer_certificate: true
41 - name: ext-authz
42 type: STATIC
43 typed_extension_protocol_options:
44 envoy.extensions.upstreams.http.v3.HttpProtocolOptions:
45 "@type": type.googleapis.com/envoy.extensions.upstreams.http.v3.HttpProtocolOptions
46 explicit_http_config:
47 http2_protocol_options: {}
48 load_assignment:
49 cluster_name: ext-authz
50 endpoints:
51 - lb_endpoints:
52 - endpoint:
53 address:
54 socket_address:
55 address: 127.0.0.1
56 port_value: 10003
Note
One of the features of this filter is to send HTTP request body to the configured gRPC authorization server as part of the check request.
A sample configuration is as follows:
26 http_filters:
27 - name: envoy.filters.http.ext_authz
28 typed_config:
29 "@type": type.googleapis.com/envoy.extensions.filters.http.ext_authz.v3.ExtAuthz
30 grpc_service:
31 envoy_grpc:
32 cluster_name: ext-authz
33 with_request_body:
34 max_request_bytes: 1024
35 allow_partial_message: true
36 pack_as_bytes: true
Please note that by default check request carries the HTTP request body as UTF-8 string and it fills the body field. To pack the request body as raw bytes, it is needed to set pack_as_bytes field to true. In effect to that, the raw_body field will be set and body field will be empty.
A sample filter configuration for a raw HTTP authorization server:
26 http_filters:
27 - name: envoy.filters.http.ext_authz
28 typed_config:
29 "@type": type.googleapis.com/envoy.extensions.filters.http.ext_authz.v3.ExtAuthz
30 http_service:
31 server_uri:
32 uri: 127.0.0.1:10003
33 cluster: ext-authz
34 timeout: 0.25s
35 failure_mode_allow: false
36 include_peer_certificate: true
41 clusters:
42 - name: ext-authz
43 type: LOGICAL_DNS
44 lb_policy: ROUND_ROBIN
45 load_assignment:
46 cluster_name: ext-authz
47 endpoints:
48 - lb_endpoints:
49 - endpoint:
50 address:
51 socket_address:
52 address: 127.0.0.1
53 port_value: 10003
Per-Route Configuration
15 route_config:
16 name: local_route
17 virtual_hosts:
18 - name: local_service
19 domains: ["*"]
20 typed_per_filter_config:
21 envoy.filters.http.ext_authz:
22 "@type": type.googleapis.com/envoy.extensions.filters.http.ext_authz.v3.ExtAuthzPerRoute
23 check_settings:
24 context_extensions:
25 virtual_host: local_service
26 routes:
27 - match:
28 prefix: /static
29 route:
30 cluster: ext-authz
31 typed_per_filter_config:
32 envoy.filters.http.ext_authz:
33 "@type": type.googleapis.com/envoy.extensions.filters.http.ext_authz.v3.ExtAuthzPerRoute
34 disabled: true
35 - match:
36 prefix: /
37 route:
38 cluster: ext-authz
A sample virtual host and route filter configuration.
In this example we add additional context on the virtual host, and disabled the filter for /static prefixed routes.
Statistics
The HTTP filter outputs statistics in the cluster.<route target cluster>.ext_authz. namespace.
Name |
Type |
Description |
|---|---|---|
ok |
Counter |
Total responses from the filter. |
error |
Counter |
Total errors contacting the external service. |
denied |
Counter |
Total responses from the authorizations service that were to deny the traffic. |
disabled |
Counter |
Total requests that are allowed without calling external services due to the filter is disabled. |
failure_mode_allowed |
Counter |
Total requests that were error(s) but were allowed through because of failure_mode_allow set to true. |
Dynamic Metadata
The External Authorization filter supports emitting dynamic metadata as an opaque google.protobuf.Struct.
When using a gRPC authorization server, dynamic metadata will be emitted only when the CheckResponse contains a non-empty dynamic_metadata field.
When using an HTTP authorization server, dynamic metadata will be emitted only when there are response headers from the authorization server that match the configured dynamic_metadata_from_headers, if set. For every response header that matches, the filter will emit dynamic metadata whose key is the name of the matched header and whose value is the value of the matched header.
Both the HTTP and gRPC external authorization filters support a dynamic metadata field called ext_authz_duration which records the time it takes to complete an authorization request in milliseconds.
This field will not be populated if the request does not complete.
Runtime
The fraction of requests for which the filter is enabled can be configured via the runtime_key value of the filter_enabled field.
Tracing
The ext_authz span keeps the sampling status of the parent span, i.e. in the tracing backend we will either see both the parent span and the child ext_authz span, or none of them.
Logging
When emit_filter_state_stats is set to true,
ext_authz exposes fields latency_us, bytesSent and bytesReceived for usage in CEL and logging.
* filter_state["envoy.filters.http.ext_authz"].latency_us)
* %FILTER_STATE(envoy.filters.http.ext_authz:FIELD:latency_us)%