External authorization extension configuration reference

This topic describes how to configure the external authorization Envoy extension, which configures Envoy proxies to request authorization from an external service. Refer to Delegate authorization to an external service for usage information.

Configuration model

The following list outlines the field hierarchy, data types, and requirements for the external authorization configuration. Place the configuration inside the EnvoyExtension.Arguments field in the proxy defaults or service defaults configuration entry. Refer to the following documentation for additional information:

• EnvoyExtensions in proxy defaults
• EnvoyExtensions in service defaults
• Envoy External Authorization documentation

Click on a property name to view additional details, including default values.

• Name: string | required | must be set to builtin/ext-authz
• Arguments: map | required
  • ProxyType: string | required | connect-proxy
  • InsertOptions: map
    • Location: string
    • FilterName: string
  • Config: map | required
    • BootstrapMetadataLabelsKey: string
    • ClearRouteCache: boolean | false | HTTP only
    • GrpcService: map
      • Target: map | required
        • Service: map
          • Name: string
          • Namespace: string | EnterpriseEnterprise
          • Partition: string | EnterpriseEnterprise
        • URI: string
        • Timeout: string | 1s
      • Authority: string
      • InitialMetadata: list
        • Key: string
        • Value: string
    • HttpService: map
      • Target: map | required
        • Service: string
          • Name: string
          • Namespace: string | EnterpriseEnterprise
          • Partition: string | EnterpriseEnterprise
        • URI: string
        • Timeout: string | 1s
      • PathPrefix: string
      • AuthorizationRequest: map
        • AllowedHeaders: list
          • Contains: string
          • Exact: string
          • IgnoreCase: boolean
          • Prefix: string
          • SafeRegex: string
        • HeadersToAdd: list
          • Key: string
          • Value: string
      • AuthorizationResponse: map
        • AllowedUpstreamHeaders: list
          • Contains: string
          • Exact: string
          • IgnoreCase: boolean
          • Prefix: string
          • SafeRegex: string
          • Suffix: string
        • AllowedUpstreamHeadersToAppend: list
          • Contains: string
          • Exact: string
          • IgnoreCase: boolean
          • Prefix: string
          • SafeRegex: string
          • Suffix: string
        • AllowedClientHeaders: list
          • Contains: string
          • Exact: string
          • IgnoreCase: boolean
          • Prefix: string
          • SafeRegex: string
          • Suffix: string
        • AllowedClientHeadersOnSuccess: list
          • Contains: string
          • Exact: string
          • IgnoreCase: boolean
          • Prefix: string
          • SafeRegex: string
          • Suffix: string
        • DynamicMetadataFromHeaders: list
          • Contains: string
          • Exact: string
          • IgnoreCase: boolean
          • Prefix: string
          • SafeRegex: string
          • Suffix: string
    • IncludePeerCertificate: boolean | false
    • MetadataContextNamespaces: list of strings | HTTP only
    • StatusOnError: number | 403 | HTTP only
    • StatPrefix: string | response
    • WithRequestBody: map | HTTP only
      • MaxRequestBytes: number
      • AllowPartialMessage: boolean | false
      • PackAsBytes: boolean | false

Complete configuration

When each field is defined, an ext-authz configuration has the following form:

Name = "builtin/ext-authz" 
Arguments = {
   ProxyType = "connect-proxy"
   InsertOptions = {
      Location = "<location in the filter chain>" 
      FilterName = "<filter relative to the location>"
   }
   Config = {
      BootstrapMetadataLabelsKey = "<key from bootstrap metadata>"
      ClearRouteCache = false // HTTP only
      GrpcService = {
         Target = {
            Service = {
               Name = "<upstream service to send gRPC authorization requests to>"
               Namespace = "<namespace containing the upstream service>"
               Partition = "<partition containing the upstream service>"
            URI = "<URI of the upstream service>"   
            Timeout = "1s"
         Authority = "<authority header to send in the gRPC request>"     
         InitialMetadata = [
            "<Key>" : "<value>"  
      HttpService = {
         Target = {
            Service = {
               Name = "<upstream service to send gRPC authorization requests to>"
               Namespace = "<namespace containing the upstream service>"
               Partition = "<partition containing the upstream service>"
            URI = "<URI of the upstream service>"   
            Timeout = "1s"
            }
         }
         PathPrefix = "/<authorization-request-header-prefix>/"    
         AuthorizationRequest = {
            AllowedHeaders = [
               Contains = "<client request headers must contain this value>",   
               Exact = "<client request headers can only be this value>",   
               IgnoreCase = false,  
               Prefix = "<client request headers must begin with this value>",   
               SafeRegex = "<client request headers can match this regex pattern>"
            ]   
            HeadersToAdd = [ 
               "<header key>" = "<header value>"
            ]
         }  
         AuthorizationResponse = {
            AllowedUpstreamHeaders = [
               Contains = "<authorization response headers must contain this value>",   
               Exact = "<authorization response headers can only be this value>",   
               IgnoreCase = false,  
               Prefix = "<authorization response headers must begin with this value>",   
               SafeRegex = "<authorization response headers can match this regex pattern>"
               Suffix = "<authorization response headers must end with this value>"
            ]   
            AllowedUpstreamHeadersToAppend = [
               Contains = "<authorization response headers must contain this value>",   
               Exact = "<authorization response headers can only be this value>",   
               IgnoreCase = false,  
               Prefix = "<authorization response headers must begin with this value>",   
               SafeRegex = "<authorization response headers can match this regex pattern>"
               Suffix = "<authorization response headers must end with this value>"   
             ]   
            AllowedClientHeaders = [
               Contains = "<client response headers must contain this value>",   
               Exact = "<client response headers can only be this value>",   
               IgnoreCase = false,  
               Prefix = "<client response headers must begin with this value>",   
               SafeRegex = "<client response headers can match this regex pattern>"
               Suffix = "<client response headers must end with the value>"
            ]   
            AllowedClientHeadersOnSuccess = [
               Contains = "<client response headers must contain this value>",   
               Exact = "<client response headers can only be this value>",   
               IgnoreCase = false,  
               Prefix = "<client response headers must begin with this value>",   
               SafeRegex = "<client response headers can match this regex pattern>"
               Suffix = "<client response headers must end with the value>"
            DynamicMetadataFromHeaders = [
               Contains = "<authorization response headers must contain this value>",   
               Exact = "<authorization response headers can only be this value>",   
               IgnoreCase = false,  
               Prefix = "<authorization response headers must begin with this value>",   
               SafeRegex = "<authorization response headers can match this regex pattern>"
               Suffix = "<authorization response headers must end with the value>"
            ]
      IncludePeerCertificate = false
      MetadataContextNamespaces = [ 
         "<metadata namespace>"
      ]
      StatusOnError = 403 // HTTP only
      StatPrefix = "response"
      WithRequestBody = {   //HTTP only
         MaxRequestBytes = <uint32 value specifying the max size of the message body>  
         AllowPartialMessage = false
         PackAsBytes = false

Specification

This section provides details about the fields you can configure for the external authorization extension.

Name

Specifies the name of the extension. Must be set to builtin/ext-authz.

Values

• Default: None
• This field is required.
• Data type: String value set to builtin/ext-authz.

Arguments

Contains the global configuration for the extension.

Values

• Default: None
• This field is required.
• Data type: Map

Arguments.ProxyType

Specifies the type of Envoy proxy that this extension applies to. The extension only applies to proxies that match this type and is ignored for all other proxy types. The only supported value is connect-proxy.

Values

• Default: connect-proxy
• This field is required.
• Data type: String

Arguments.InsertOptions

Specifies options for defining the insertion point for the external authorization filter in the Envoy filter chain. By default, the external authorization filter is inserted as the first filter in the filter chain per the default setting for the Location field.

Values

• Default: None
• Data type: Map

Arguments.InsertOptions.Location

Specifies the insertion point for the external authorization filter in the Envoy filter chain. You can specify one of the following string values:

• First: Inserts the filter as the first filter in the filter chain, regardless of the filter specified in the FilterName field.
• BeforeLast: Inserts the filter before the last filter in the chain, regardless of the filter specified in the FilterName field. This allows the filter to be inserted after all other filters and immediately before the terminal filter.
• AfterFirstMatch: Inserts the filter after the first filter in the chain that has a name matching the value of the FilterName field.
• AfterLastMatch: Inserts the filter after the last filter in the chain that has a name matching the value of the FilterName field.
• BeforeFirstMatch: Inserts the filter before the first filter in the chain that has a name matching the value of the FilterName field.
• BeforeLastMatch: Inserts the filter before the last filter in the chain that has a name matching the value of the FilterName field.

Values

• Default: BeforeFirstMatch
• Data type: String

Arguments.InsertOptions.FilterName

Specifies the name of an existing filter in the chain to match when inserting the external authorization filter. Specifying a filter name enables you to configure an insertion point relative to the position of another filter in the chain.

Values

• Default: envoy.filters.network.tcp_proxy for TCP services. envoy.filters.http.router for HTTP services.
• Data type: String

Arguments.Config

Contains the configuration settings for the extension.

Values

• Default: None
• This field is required.
• Data type: Map

Arguments.Config.BootstrapMetadataLabelsKey

Specifies a key from the Envoy bootstrap metadata. Envoy adds labels associated with the key to the authorization request context.

Values

• Default: None
• Data type: String

Arguments.Config.ClearRouteCache

Directs Envoy to clear the route cache so that the external authorization service correctly affects routing decisions. If set to true, the filter clears all cached routes.

Envoy also clears cached routes if the status returned from the authorization service is 200 for HTTP responses or 0 for gRPC responses. Envoy also clears cached routes if at least one authorization response header is added to the client request or is used for altering another client request header.

Values

• Default: false
• Data type: Boolean

Arguments.Config.GrpcService

Specifies the external authorization configuration for gRPC requests. Configure the GrpcService or the HttpService settings, but not both.

Values

• Default: None
• Either the GrpcService or the HttpService configuration is required.
• Data type: Map

Arguments.Config.GrpcService.Target

Configuration for specifying the service to send gRPC authorization requests to. The Target field may contain the following fields:

• Service or Uri
• Timeout

Values

• Default: None
• This field is required.
• Data type: Map

Arguments{}.Config{}.GrpcService{}.Target{}.Service{}

Specifies the upstream external authorization service. Configure this field when authorization requests are sent to an upstream service within the service mesh. The service must be configured as an upstream of the service that the filter is applied to.

Configure either the Service field or the Uri field, but not both.

Values

• Default: None
• This field or Uri is required.
• Data type: Map

The following table describes how to configure parameters for the Service field:

Parameter	Description	Data type	Default
Name	Specifies the name of the upstream service.	String	None
Namespace	EnterpriseEnterprise Specifies the Consul namespace that the upstream service belongs to.	String	default
Partition	EnterpriseEnterprise Specifies the Consul admin partition that the upstream service belongs to.	String	default

Arguments.Config.GrpcService.Target.Uri

Specifies the URI of the external authorization service. Configure this field when you must provide an explicit URI to the external authorization service, such as cases in which the authorization service is running on the same host or pod. If set, the value of this field must be one of localhost:<port>, 127.0.0.1:<port>, or ::1:<port>.

Configure either the Uri field or the Service field, but not both.

Values

• Default: None
• This field or Service is required.
• Data type: String

Arguments.Config.GrpcService.Target.Timeout

Specifies the maximum duration that a response can take to arrive upon request.

Values

• Default: 1s
• Data type: String

Arguments.Config.GrpcService.Authority

Specifies the authority header to send in the gRPC request. If this field is not set, the authority field is set to the cluster name. This field does not override the SNI that Envoy sends to the external authorization service.

Values

• Default: Cluster name
• Data type: String

Arguments.Config.GrpcService.InitialMetadata[]

Specifies additional metadata to include in streams initiated to the GrpcService. You can specify metadata for injecting additional ad-hoc authorization headers, for example, x-foo-bar: baz-key. For more information, including details on header value syntax, refer to the Envoy documentation on custom request headers.

Values

• Default: None

• Data type: List of one or more key-value pairs:

  • KEY: String
  • VALUE: String

Arguments{}.Config{}.HttpService{}

Contains the configuration for raw HTTP communication between the filter and the external authorization service. Configure the HttpService or the GrpcService settings, but not both.

Values

• Default: None
• Either the HttpService or the GrpcService configuration is required.
• Data type: Map

Arguments{}.Config{}.HttpService{}.Target{}

Configuration for specifying the service to send HTTP authorization requests to. The Target field may contain the following fields:

• Service or Uri
• Timeout

Values

• Default: None
• This field is required.
• Data type: Map

Arguments{}.Config{}.HttpService{}.Target{}.Service{}

Specifies the upstream external authorization service. Configure this field when HTTP authorization requests are sent to an upstream service within the service mesh. The service must be configured as an upstream of the service that the filter is applied to.

Configure either the Service field or the Uri field, but not both.

Values

• Default: None
• This field or Uri is required.
• Data type: Map

The following table describes how to configure parameters for the Service field:

Parameter	Description	Data type	Default
Name	Specifies the name of the upstream service.	String	None
Namespace	EnterpriseEnterprise Specifies the Consul namespace that the upstream service belongs to.	String	default
Partition	EnterpriseEnterprise Specifies the Consul admin partition that the upstream service belongs to.	String	default

Arguments{}.Config{}.HttpService{}.Target{}.Uri

Specifies the URI of the external authorization service. Configure this field when you must provide an explicit URI to the external authorization service, such as cases in which the authorization service is running on the same host or pod. If set, the value of this field must be one of localhost:<port>, 127.0.0.1:<port>, or ::1:<port>.

Configure either the Uri field or the Service field, but not both.

Values

• Default: None
• This field or Service is required.
• Data type: String

Arguments{}.Config{}.HttpService{}.Target{}.Timeout

Specifies the maximum duration that a response can take to arrive upon request.

Values

• Default: 1s
• Data type: String

Arguments{}.Config{}.HttpService{}.PathPrefix

Specifies a prefix for the value of the authorization request header Path. You must include the preceding forward slash (/).

Values

• Default: None
• Data type: String

Arguments{}.Config{}.HttpService{}.AuthorizationRequest{}

HTTP-only configuration that controls the HTTP authorization request metadata. The AuthorizationRequest field may contain the following parameters:

• AllowHeaders
• HeadersToAdd

Values

• Default: None
• Data type: Map

Arguments{}.Config{}.HttpService{}.AuthorizationRequest{}.AllowHeaders[]

Specifies a set of rules for matching client request headers. The request to the external authorization service includes any client request headers that satisfy any of the rules. Refer to the Envoy documentation for a detailed explanation.

Values

• Default: None
• Data type: List of key-value pairs

The following table describes the matching rules you can configure in the AllowHeaders field:

Arguments{}.Config{}.HttpService{}.AuthorizationRequest{}.HeadersToAdd[]

Specifies a list of headers to include in the request to the authorization service. Note that Envoy overwrites client request headers with the same key.

Values

• Default: None

• Data type: List of one or more key-value pairs:

  • KEY: String
  • VALUE: String

Arguments{}.Config{}.HttpService{}.AuthorizationResponse{}

HTTP-only configuration that controls HTTP authorization response metadata. The AuthorizationResponse field may contain the following parameters:

• AllowedUpstreamHeaders
• AllowedUpstreamHeadersToAppend
• AllowedClientHeaders
• AllowedClientHeadersOnSuccess
• DynamicMetadataFromHeaders

Values

• Default: None
• Data type: Map

Arguments{}.Config{}.HttpService{}.AuthorizationResponse{}.AllowedUpstreamHeaders[]

Specifies a set of rules for matching authorization response headers. Envoy adds any headers from the external authorization service to the client response that satisfy the rules. Envoy overwrites existing headers.

Values

• Default: None
• Data type: Map

The following table describes the matching rules you can configure in the AllowedUpstreamHeaders field:

Arguments{}.Config{}.HttpService{}.AuthorizationResponse{}.AllowedUpstreamHeadersToAppend[]

Specifies a set of rules for matching authorization response headers. Envoy appends any headers from the external authorization service to the client response that satisfy the rules. Envoy appends existing headers.

Values

• Default: None
• Data type: Map

The following table describes the matching rules you can configure in the AllowedUpstreamHeadersToAppend field:

Arguments{}.Config{}.HttpService{}.AuthorizationResponse{}.AllowedClientHeaders[]

Specifies a set of rules for matching client response headers. Envoy adds any headers from the external authorization service to the client response that satisfy the rules. When the list is not set, Envoy includes all authorization response headers except Authority (Host). When a header is included in this list, Envoy automatically adds the following headers:

• Path
• Status
• Content-Length
• WWWAuthenticate
• Location

Values

• Default: None
• Data type: Map

The following table describes the matching rules you can configure in the AllowedClientHeaders field:

Arguments{}.Config{}.HttpService{}.AuthorizationResponse{}.AllowedClientHeadersOnSuccess[]

Specifies a set of rules for matching client response headers. Envoy adds headers from the external authorization service to the client response when the headers satisfy the rules and the authorization is successful. If the headers match the rules but the authorization fails or is denied, the headers are not added. If this field is not set, Envoy does not add any additional headers to the client’s response on success.

Values

• Default: None
• Data type: Map

The following table describes the matching rules you can configure in the AllowedClientHeadersOnSuccess field:

Arguments{}.Config{}.HttpService{}.AuthorizationResponse{}.DynamicMetadataFromHeaders[]

Specifies a set of rules for matching authorization response headers. Envoy emits headers from the external authorization service as dynamic metadata that the next filter in the chain can consume.

Values

• Default: None
• Data type: Map

The following table describes the matching rules you can configure in the DynamicMetadataFromHeaders field:

Arguments{}.Config{}.IncludePeerCertificate

If set to true, Envoy includes the peer X.509 certificate in the authorization request if the certificate is available.

Values

• Default: false
• Data type: Boolean

Arguments{}.Config{}.MetadataContextNamespace[]

HTTP only field that specifies a list of metadata namespaces. The values of the namespaces are included in the authorization request context. The consul namespace is always included in addition to the namespaces you configure.

Values

• Default: ["consul"]
• Data type: List of string values

Arguments{}.Config{}.StatusOnError

HTTP only field that specifies a return code status to respond with on error. Refer to the Envoy documentation for additional information.

Values

• Default: 403
• Data type: Integer

Arguments{}.Config{}.StatPrefix

Specifies a prefix to add when writing statistics.

Values

• Default: response
• Data type: String

Arguments{}.Config{}.WithRequestBody{}

HTTP only field that configures Envoy to buffer the client request body and send it with the authorization request. If unset, the request body is not sent with the authorization request.

Values

• Default: None
• Data type: Map

The following table describes the parameters that you can include in the WithRequestBody field:

Examples

The following examples demonstrate common configuration patterns for specific use cases.

Authorize gRPC requests to a URI

In the following example, a service defaults configuration entry contains an ext-authz configuration. The configuration allows the api service to make gRPC authorization requests to a service at localhost:9191:

Kind = "service-defaults"
Name = "api"
EnvoyExtensions = [
  {
    Name = "builtin/ext-authz"
    Arguments = {
      ProxyType = "connect-proxy"
      Config = {
        GrpcService = {
          Target = {
            URI = "127.0.0.1:9191"
          }
        }
      }
    }
  }
]

Upstream authorization

In the following example, a service defaults configuration entry contains an ext-authz configuration. The configuration allows the api service to make gRPC authorization requests to a service named authz:

Kind = "service-defaults"
Name = "api"
EnvoyExtensions = [
  {
    Name = "builtin/ext-authz"
    Arguments = {
      ProxyType = "connect-proxy"
      Config = {
        GrpcService = {
          Target = {
            Service = {
              Name = "authz"
            }
          }
        }
      }
    }
  }
]

Authorization requests after service intentions for Consul Enterprise

In the following example for Consul Enterprise, the api service is configured to make an HTTP authorization requests to a service named authz in the foo namespace and bar partition. Envoy also inserts the external authorization filter after the envoy.filters.http.rbac filter:

Kind = "service-defaults"
Name = "api"
Protocol = "http"
EnvoyExtensions = [
  {
    Name = "builtin/ext-authz"
    Arguments = {
      ProxyType = "connect-proxy"
      InsertOptions = {
        Location   = "AfterLastMatch"
        FilterName = "envoy.filters.http.rbac"
      }
      Config = {
        HttpService = {
          Target = {
            Service = {
              Name      = "authz"
              Namespace = "foo"
              Partition = "bar"
            }
          }
        }
      }
    }
  }
]