External Authorization

External Authorization

External authorization architecture overview
HTTP filter v3 API reference
This filter should be configured with the name envoy.filters.http.ext_authz.

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:

http_filters:
  - name: envoy.filters.http.ext_authz
    typed_config:
      "@type": type.googleapis.com/envoy.extensions.filters.http.ext_authz.v3.ExtAuthz
      grpc_service:
        envoy_grpc:
          cluster_name: ext-authz
        # Default is 200ms; override if your server needs e.g. warmup time.
        timeout: 0.5s
      include_peer_certificate: true

clusters:
  - name: ext-authz
    type: static
    http2_protocol_options: {}
    load_assignment:
      cluster_name: ext-authz
      endpoints:
      - lb_endpoints:
        - endpoint:
            address:
              socket_address:
                address: 127.0.0.1
                port_value: 10003
    # This timeout controls the initial TCP handshake timeout - not the timeout for the
    # entire request.
    connect_timeout: 0.25s

A sample filter configuration for a raw HTTP authorization server:

http_filters:
  - name: envoy.filters.http.ext_authz
    typed_config:
      "@type": type.googleapis.com/envoy.extensions.filters.http.ext_authz.v3.ExtAuthz
      http_service:
          server_uri:
            uri: 127.0.0.1:10003
            cluster: ext-authz
            timeout: 0.25s
            failure_mode_allow: false
      include_peer_certificate: true

clusters:
  - name: ext-authz
    connect_timeout: 0.25s
    type: logical_dns
    lb_policy: round_robin
    load_assignment:
      cluster_name: ext-authz
      endpoints:
      - lb_endpoints:
        - endpoint:
            address:
              socket_address:
                address: 127.0.0.1
                port_value: 10003

Per-Route Configuration

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.

route_config:
  name: local_route
  virtual_hosts:
  - name: local_service
    domains: ["*"]
    typed_per_filter_config:
      envoy.filters.http.ext_authz:
        "@type": type.googleapis.com/envoy.extensions.filters.http.ext_authz.v3.ExtAuthzPerRoute
        check_settings:
          context_extensions:
            virtual_host: local_service
    routes:
    - match: { prefix: "/static" }
      route: { cluster: some_service }
      typed_per_filter_config:
        envoy.filters.http.ext_authz:
          "@type": type.googleapis.com/envoy.extensions.filters.http.ext_authz.v3.ExtAuthzPerRoute
          disabled: true
    - match: { prefix: "/" }
      route: { cluster: some_service }

Statistics

The HTTP filter outputs statistics in the 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.
failure_mode_allowed	Counter	Total requests that were error(s) but were allowed through because of failure_mode_allow set to true.

Runtime

The fraction of requests for which the filter is enabled can be configured via the runtime_key value of the filter_enabled field.