consul/website/content/docs/connect/proxies/envoy-extensions/configuration/ext-authz.mdx

---
layout: docs
page_title: External authorization extension configuration reference
description: Learn how to configure the ext-authz Envoy extension, which is a builtin Consul extension that configures Envoy proxies to request authorization from an external service.
---

# 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](/consul/docs/connect/proxies/envoy-extensions/usage/ext-authz) 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](/consul/docs/connect/config-entries/proxy-defaults#envoyextensions)
- [`EnvoyExtensions` in service defaults](/consul/docs/connect/config-entries/service-defaults#envoyextensions)
 - [Envoy External Authorization documentation](https://www.envoyproxy.io/docs/envoy/latest/api-v3/extensions/filters/http/ext_authz/v3/ext_authz.proto)

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

- [`Name`](#name): string | required | must be set to `builtin/ext-authz` 
- [`Arguments`](#arguments): map | required
   - [`ProxyType`](#arguments-proxytype): string | required | `connect-proxy`
   - [`InsertOptions`](#arguments-insertoptions): map
      - [`Location`](#arguments-insertoptions-location): string
      - [FilterName](#arguments-insertoptions-filtername): string
   - [`Config`](#arguments-config): map | required
      - [`BootstrapMetadataLabelsKey`](#arguments-config-bootstrapmetadatalabelskey): string
      - [`ClearRouteCache`](#arguments-config-grpcservice): boolean | `false` | HTTP only
      - [`GrpcService`](#arguments-config-grpcservice): map
        - [`Target`](#arguments-config-grpcservice-target): map | required
           - [`Service`](#arguments-config-grpcservice-target-service): map
              - [`Name`](#arguments-config-grpcservice-target-service): string
              - [`Namespace`](#arguments-config-grpcservice-target-service): string | <EnterpriseAlert inline/>
              - [`Partition`](#arguments-config-grpcservice-target-service): string | <EnterpriseAlert inline/>
           - [`URI`](#arguments-config-grpcservice-target-uri): string   
           - [`Timeout`](#arguments-config-grpcservice-target-uri): string | `1s`
        - [`Authority`](#arguments-config-grpcservice-authority): string    
        - [`InitialMetadata`](#arguments-config-grpcservice-initialmetadata): list
           - [`Key`](#arguments-config-grpcservice-initialmetadata): string  
           - [`Value`](#arguments-config-grpcservice-initialmetadata): string  
      - [`HttpService`](#arguments-config-httpservice): map
        - [`Target`](#arguments-config-httpservice-target): map | required
           - [`Service`](#arguments-config-httpservice): string
              - [`Name`](#arguments-config-httpservice-target-service): string
              - [`Namespace`](#arguments-config-httpservice-target-service): string | <EnterpriseAlert inline/>
              - [`Partition`](#arguments-config-httpservice-target-service): string | <EnterpriseAlert inline/>     
           - [`URI`](#arguments-config-httpservice): string   
           - [`Timeout`](#arguments-config-httpservice): string | `1s`   
        - [`PathPrefix`](#arguments-config-httpservice-pathprefix): string    
        - [`AuthorizationRequest`](#arguments-config-httpservice-authorizationrequest): map    
           - [`AllowedHeaders`](#arguments-config-httpservice-authorizationrequest-allowedheaders): list
              - [`Contains`](#arguments-config-httpservice-authorizationrequest-allowedheaders): string   
              - [`Exact`](#arguments-config-httpservice-authorizationrequest-allowedheaders): string   
              - [`IgnoreCase`](#arguments-config-httpservice-authorizationrequest-allowedheaders): boolean  
              - [`Prefix`](#arguments-config-httpservice-authorizationrequest-allowedheaders): string   
              - [`SafeRegex`](#arguments-config-httpservice-authorizationrequest-allowedheaders): string   
           - [`HeadersToAdd`](#arguments-config-httpservice-authorizationrequest-headerstoadd): list
              - [`Key`](#arguments-config-httpservice-authorizationrequest-headerstoadd): string  
              - [`Value`](#arguments-config-httpservice-authorizationrequest-headerstoadd): string  
        - [`AuthorizationResponse`](#arguments-config-httpservice-authorizationresponse): map
           - [`AllowedUpstreamHeaders`](#arguments-config-httpservice-authorizationresponse-allowedupstreamheaders): list
              - [`Contains`](#arguments-config-httpservice-authorizationresponse-allowedupstreamheaders): string   
              - [`Exact`](#arguments-config-httpservice-authorizationresponse-allowedheaders): string   
              - [`IgnoreCase`](#arguments-config-httpservice-authorizationresponse-allowedheaders): boolean  
              - [`Prefix`](#arguments-config-httpservice-authorizationresponse-allowedheaders): string   
              - [`SafeRegex`](#arguments-config-httpservice-authorizationresponse-allowedheaders): string   
              - [`Suffix`](#arguments-config-httpservice-authorizationresponse-allowedheaders): string   
           - [`AllowedUpstreamHeadersToAppend`](#arguments-config-httpservice-authorizationresponse-allowedupstreamheaderstoappend): list
              - [`Contains`](#arguments-config-httpservice-authorizationresponse-allowedupstreamheaderstoappend): string   
              - [`Exact`](#arguments-config-httpservice-authorizationresponse-allowedupstreamheaderstoappend): string   
              - [`IgnoreCase`](#arguments-config-httpservice-authorizationresponse-allowedupstreamheaderstoappend): boolean  
              - [`Prefix`](#arguments-config-httpservice-authorizationresponse-allowedupstreamheaderstoappend): string   
              - [`SafeRegex`](#arguments-config-httpservice-authorizationresponse-allowedupstreamheaderstoappend): string   
              - [`Suffix`](#arguments-config-httpservice-authorizationresponse-allowedupstreamheaderstoappend): string   
           - [`AllowedClientHeaders`](#arguments-config-httpservice-authorizationresponse-allowedclientheaders): list
              - [`Contains`](#arguments-config-httpservice-authorizationresponse-allowedclientheaders): string   
              - [`Exact`](#arguments-config-httpservice-authorizationresponse-allowedclientheaders): string   
              - [`IgnoreCase`](#arguments-config-httpservice-authorizationresponse-allowedclientheaders): boolean  
              - [`Prefix`](#arguments-config-httpservice-authorizationresponse-allowedclientheaders): string   
              - [`SafeRegex`](#arguments-config-httpservice-authorizationresponse-allowedclientheaders): string   
              - [`Suffix`](#arguments-config-httpservice-authorizationresponse-allowedclientheaders): string   
           - [`AllowedClientHeadersOnSuccess`](#arguments-config-httpservice-authorizationresponse-allowedclientheadersonsuccess): list
              - [`Contains`](#arguments-config-httpservice-authorizationresponse-allowedclientheadersonsuccess): string   
              - [`Exact`](#arguments-config-httpservice-authorizationresponse-allowedclientheadersonsuccess): string   
              - [`IgnoreCase`](#arguments-config-httpservice-authorizationresponse-allowedclientheadersonsuccess): boolean  
              - [`Prefix`](#arguments-config-httpservice-authorizationresponse-allowedclientheadersonsuccess): string   
              - [`SafeRegex`](#arguments-config-httpservice-authorizationresponse-allowedclientheadersonsuccess): string   
              - [`Suffix`](#arguments-config-httpservice-authorizationresponse-allowedclientheadersonsuccess): string   
           - [`DynamicMetadataFromHeaders`](#arguments-config-httpservice-authorizationresponse-dynamicmetadatafromheaders): list
              - [`Contains`](#arguments-config-httpservice-authorizationresponse-dynamicmetadatafromheaders): string   
              - [`Exact`](#arguments-config-httpservice-authorizationresponse-dynamicmetadatafromheaders): string   
              - [`IgnoreCase`](#arguments-config-httpservice-authorizationresponse-dynamicmetadatafromheaders): boolean  
              - [`Prefix`](#arguments-config-httpservice-authorizationresponse-dynamicmetadatafromheaders): string   
              - [`SafeRegex`](#arguments-config-httpservice-authorizationresponse-dynamicmetadatafromheaders): string   
              - [`Suffix`](#arguments-config-httpservice-authorizationresponse-dynamicmetadatafromheaders): string   
      - [`IncludePeerCertificate`](#arguments-config-includepeercertificate): boolean | `false`
      - [`MetadataContextNamespaces`](#arguments-config-metadatacontextnamespaces): list of strings | HTTP only
      - [`StatusOnError`](#arguments-config-statusonerror): number | `403` | HTTP only
      - [`StatPrefix`](#arguments-config-statprefix): string | `response`
      - [`WithRequestBody`](#arguments-config-withrequestbody): map | HTTP only
         - [`MaxRequestBytes`](#arguments-config-withrequestbody-maxrequestbytes): number 
         - [`AllowPartialMessage`](#arguments-config-withrequestbody-allowpartialmessage): boolean | `false`
         - [`PackAsBytes`](#arguments-config-withrequestbody-packasbytes): boolean | `false`

## Complete configuration

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

```hcl
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`](#arguments-insertoptions-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`](#arguments-config-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`](#arguments-config-grpcservice-target-service) or [`Uri`](#arguments-config-grpcservice-target-uri)
- [`Timeout`](#arguments-config-grpcservice-target-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`](#arguments-config-grpcservice-target-uri) field, but not both. 
 
#### Values

- Default: None
- This field or [`Uri`](#arguments-config-grpcservice-target-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` | <EnterpriseAlert inline/> Specifies the Consul namespace that the upstream service belongs to. | String | `default` |
| `Partition` | <EnterpriseAlert inline/> 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 either `localhost:<port>` or `127.0.0.1:<port>`

Configure either the `Uri` field or the [`Service`](#arguments-config-grpcservice-target-service) field, but not both. 
 
#### Values

- Default: None
- This field or [`Service`](#arguments-config-grpcservice-target-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](https://www.envoyproxy.io/docs/envoy/latest/configuration/http/http_conn_man/headers#config-http-conn-man-headers-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`](#arguments-config-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`](#arguments-config-httpservice-target-service) or [`Uri`](#arguments-config-httpservice-target-uri)
- [`Timeout`](#arguments-config-httpservice-target-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`](#arguments-config-httpservice-target-uri) field, but not both. 
 
#### Values

- Default: None
- This field or [`Uri`](#arguments-config-httpservice-target-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` | <EnterpriseAlert inline/> Specifies the Consul namespace that the upstream service belongs to. | String | `default` |
| `Partition` | <EnterpriseAlert inline/> 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. 

Configure either the `Uri` field or the [`Service`](#arguments-config-httpservice-target-service) field, but not both. 
 
#### Values

- Default: None
- This field or [`Service`](#arguments-config-httpservice-target-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`](#arguments-config-httpservice-authorizationrequest-allowheaders)
- [`HeadersToAdd`](#arguments-config-httpservice-authorizationrequest-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](https://www.envoyproxy.io/docs/envoy/latest/api-v3/extensions/filters/http/ext_authz/v3/ext_authz.proto#extensions-filters-http-ext-authz-v3-extauthz) 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:

@include 'envoy_ext_rule_matcher.mdx'

### `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`](#arguments-config-httpservice-authorizationresponse-allowedupstreamheaders)
- [`AllowedUpstreamHeadersToAppend`](#arguments-config-httpservice-authorizationresponse-allowedupstreamheaderstoappend)
- [`AllowedClientHeaders`](#arguments-config-httpservice-authorizationresponse-allowedclientheaders)
- [`AllowedClientHeadersOnSuccess`](#arguments-config-httpservice-authorizationresponse-allowedclientheadersonsuccess)
- [`DynamicMetadataFromHeaders`](#arguments-config-httpservice-authorizationresponse-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:

@include 'envoy_ext_rule_matcher.mdx'

### `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:

@include 'envoy_ext_rule_matcher.mdx'

### `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:

@include 'envoy_ext_rule_matcher.mdx'

### `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:

@include 'envoy_ext_rule_matcher.mdx'

### `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:

@include 'envoy_ext_rule_matcher.mdx'

### `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](https://www.envoyproxy.io/docs/envoy/latest/api-v3/type/v3/http_status.proto#enum-type-v3-statuscode) 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:

| Parameter | Description | Data type | Default |
| ---       | ---         | ---       | ---     |
| `MaxRequestBytes` | Specifies the maximum size of the message body that the filter holds in memory. Envoy returns HTTP `403` and does not initiate the authorization process when the buffer reaches the number set in this field unless `AllowPartialMessage` is set to `true`. | uint32 | None |
| `AllowPartialMessage` | If set to `true`, Envoy buffers the request body until the value of `MaxRequestBytes` is reached. The authorization request is dispatched with a partial body and no `413` HTTP error returns by the filter. | Boolean | `false` |
| `PackAsBytes` | If set to `true`, Envoy sends the request body to the external authorization as raw bytes. Otherwise, Envoy sends the request body as a UTF-8 encoded string. | Boolean | `false` |

## 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`:

```hcl
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`:

```hcl
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:

```hcl
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"
            }
          }
        }
      }
    }
  }
]
```