Delegate authorization to an external service

This topic describes how to use the external authorization Envoy extension to delegate data plane authorization requests to external systems.

Workflow

Complete the following steps to use the external authorization extension:

  1. Configure an EnvoyExtensions block in a service defaults or proxy defaults configuration entry.
  2. Apply the configuration entry.

Add the EnvoyExtensions

Add Envoy extension configurations to a proxy defaults or service defaults configuration entry. Place the extension configuration in an EnvoyExtensions block in the configuration entry.

  • When you configure Envoy extensions on proxy defaults, they apply to every service.
  • When you configure Envoy extensions on service defaults, they apply to a specific service.

Consul applies Envoy extensions configured in proxy defaults before it applies extensions in service defaults. As a result, the Envoy extension configuration in service defaults may override configurations in proxy defaults.

The following example shows a service defaults configuration entry for the api service that directs the Envoy proxy to make gRPC authorization requests to the authz service:

Delegate authorization to external services - 图1

api-auth-service-defaults.hcl

  1. Kind = "service-defaults"
  2. Name = "api"
  3. EnvoyExtensions = [
  4.   {
  5.     Name = "builtin/ext-authz"
  6.     Arguments = {
  7.       ProxyType = "connect-proxy"
  8.       Config = {
  9.         GrpcService = {
  10.           Target = {
  11.             Service = {
  12.               Name = "authz"
  13.             }
  14.           }
  15.         }
  16.       }
  17.     }
  18.   }
  19. ]

Delegate authorization to external services - 图2

api-auth-service-defaults.json

  1. "Kind": "service-defaults",
  2. "Name": "api",
  3. "EnvoyExtensions": [{
  4.   "Name": "builtin/ext-authz",
  5.   "Arguments": {
  6.     "ProxyType": "connect-proxy",
  7.     "Config": {
  8.       "GrpcService": {
  9.         "Target": {
  10.           "Service": {
  11.             "Name": "authz"
  12.             }
  13.           }
  14.         }
  15.       }
  16.     }
  17.   }
  18. ]

Delegate authorization to external services - 图3

api-auth-service-defaults

  1. apiVersion: consul.hashicorp.com/v1alpha1
  2. kind: ServiceDefaults
  3. metadata:
  4.   name: api
  5.   namespace: default
  6. spec:
  7.   envoyExtensions:
  8.   - name: builtin/ext-authz
  9.     arguments:
  10.       proxyType: connect-proxy
  11.       config:
  12.         grpcService:
  13.           target:
  14.             service:
  15.               name: authz
  16.               namespace: authz

Refer to the external authorization extension configuration reference for details on how to configure the extension.

Refer to the proxy defaults configuration entry reference and service defaults configuration entry reference for details on how to define the configuration entries.

Warning: Adding Envoy extensions default proxy configurations may have unintended consequences. We recommend configuring EnvoyExtensions in service defaults configuration entries in most cases.

Unsupported Envoy configuration fields

The following Envoy configurations are not supported:

ConfigurationWorkaround
deny_at_disableDisable filter by removing it from the service’s configuration in the configuration entry.
failure_mode_allowSet the EnvoyExtension.Required field to true in the service defaults configuration entry or proxy defaults configuration entry.
filter_enabledSet the EnvoyExtension.Required field to true in the service defaults configuration entry or proxy defaults configuration entry.
filter_enabled_metadataSet the EnvoyExtension.Required field to true in the service defaults configuration entry or proxy defaults configuration entry.
transport_api_versionConsul only supports v3 of the transport API. As a result, there is no workaround for implementing the behavior of this field.

Apply the configuration entry

If your network is deployed to virtual machines, use the consul config write command and specify the proxy defaults or service defaults configuration entry to apply the configuration. For Kubernetes-orchestrated networks, use the kubectl apply command. The following example applies the extension in a proxy defaults configuration entry.

  1. $ consul config write api-auth-service-defaults.hcl
  1. $ consul config write api-auth-service-defaults.json
  1. $ kubectl apply -f api-auth-service-defaults.yaml