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 defaultsEnvoyExtensions
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 tobuiltin/ext-authz
Arguments
: map | requiredProxyType
: string | required |connect-proxy
ListenerType
: string | required |inbound
InsertOptions
: mapLocation
: string- FilterName: string
Config
: map | requiredBootstrapMetadataLabelsKey
: stringClearRouteCache
: boolean |false
| HTTP onlyGrpcService
: mapHttpService
: mapTarget
: map | requiredPathPrefix
: stringAuthorizationRequest
: mapAllowedHeaders
: listContains
: stringExact
: stringIgnoreCase
: booleanPrefix
: stringSafeRegex
: string
HeadersToAdd
: list
AuthorizationResponse
: map
IncludePeerCertificate
: boolean |false
MetadataContextNamespaces
: list of strings | HTTP onlyStatusOnError
: number |403
| HTTP onlyStatPrefix
: string |response
WithRequestBody
: map | HTTP onlyMaxRequestBytes
: numberAllowPartialMessage
: boolean |false
PackAsBytes
: boolean |false
Complete configuration
When each field is defined, an ext-authz
configuration has the following form:
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.ListenerType
Specifies the type of listener the extension applies to. The listener type is either inbound
or outbound
. If the listener type is set to inbound
, Consul applies the extension so the external authorization is enabled when other services in the mesh send messages to the service attached to the proxy. If the listener type is set to outbound
, Consul applies the extension so the external authorization is enabled when the attached proxy sends messages to other services in the mesh.
Values
- Default:
inbound
- This field is required.
- Data type is one of the following string values:
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 theFilterName
field.BeforeLast
: Inserts the filter before the last filter in the chain, regardless of the filter specified in theFilterName
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 theFilterName
field.AfterLastMatch
: Inserts the filter after the last filter in the chain that has a name matching the value of theFilterName
field.BeforeFirstMatch
: Inserts the filter before the first filter in the chain that has a name matching the value of theFilterName
field.BeforeLastMatch
: Inserts the filter before the last filter in the chain that has a name matching the value of theFilterName
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 theHttpService
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:
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 | Enterprise Specifies the Consul namespace that the upstream service belongs to. | String | default |
Partition | Enterprise 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 theGrpcService
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:
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 | Enterprise Specifies the Consul namespace that the upstream service belongs to. | String | default |
Partition | Enterprise 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:
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:
Rule | Description | Data type | Default |
---|---|---|---|
Contains | Specifies a string that the input string must contain. | String | N/A |
Exact | Specifies a string that the input string must match exactly. | String | N/A |
IgnoreCase | Directs Envoy to ignore capitalization. If set to true , the other matching rules in the configuration are not case sensitive. This rule does not affect SafeRegex . | Boolean | false |
Prefix | Specifies a string that the input string must begin with. | String | N/A |
SafeRegex | Specifies a regular expression for matching the input string programmatically. Envoy supports Google's RE2 regex engine. | String | N/A |
Suffix | Specifies a string that the input string must end with. | String | N/A |
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:
Rule | Description | Data type | Default |
---|---|---|---|
Contains | Specifies a string that the input string must contain. | String | N/A |
Exact | Specifies a string that the input string must match exactly. | String | N/A |
IgnoreCase | Directs Envoy to ignore capitalization. If set to true , the other matching rules in the configuration are not case sensitive. This rule does not affect SafeRegex . | Boolean | false |
Prefix | Specifies a string that the input string must begin with. | String | N/A |
SafeRegex | Specifies a regular expression for matching the input string programmatically. Envoy supports Google's RE2 regex engine. | String | N/A |
Suffix | Specifies a string that the input string must end with. | String | N/A |
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:
Rule | Description | Data type | Default |
---|---|---|---|
Contains | Specifies a string that the input string must contain. | String | N/A |
Exact | Specifies a string that the input string must match exactly. | String | N/A |
IgnoreCase | Directs Envoy to ignore capitalization. If set to true , the other matching rules in the configuration are not case sensitive. This rule does not affect SafeRegex . | Boolean | false |
Prefix | Specifies a string that the input string must begin with. | String | N/A |
SafeRegex | Specifies a regular expression for matching the input string programmatically. Envoy supports Google's RE2 regex engine. | String | N/A |
Suffix | Specifies a string that the input string must end with. | String | N/A |
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:
Values
- Default: None
- Data type: Map
The following table describes the matching rules you can configure in the AllowedClientHeaders
field:
Rule | Description | Data type | Default |
---|---|---|---|
Contains | Specifies a string that the input string must contain. | String | N/A |
Exact | Specifies a string that the input string must match exactly. | String | N/A |
IgnoreCase | Directs Envoy to ignore capitalization. If set to true , the other matching rules in the configuration are not case sensitive. This rule does not affect SafeRegex . | Boolean | false |
Prefix | Specifies a string that the input string must begin with. | String | N/A |
SafeRegex | Specifies a regular expression for matching the input string programmatically. Envoy supports Google's RE2 regex engine. | String | N/A |
Suffix | Specifies a string that the input string must end with. | String | N/A |
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:
Rule | Description | Data type | Default |
---|---|---|---|
Contains | Specifies a string that the input string must contain. | String | N/A |
Exact | Specifies a string that the input string must match exactly. | String | N/A |
IgnoreCase | Directs Envoy to ignore capitalization. If set to true , the other matching rules in the configuration are not case sensitive. This rule does not affect SafeRegex . | Boolean | false |
Prefix | Specifies a string that the input string must begin with. | String | N/A |
SafeRegex | Specifies a regular expression for matching the input string programmatically. Envoy supports Google's RE2 regex engine. | String | N/A |
Suffix | Specifies a string that the input string must end with. | String | N/A |
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:
Rule | Description | Data type | Default |
---|---|---|---|
Contains | Specifies a string that the input string must contain. | String | N/A |
Exact | Specifies a string that the input string must match exactly. | String | N/A |
IgnoreCase | Directs Envoy to ignore capitalization. If set to true , the other matching rules in the configuration are not case sensitive. This rule does not affect SafeRegex . | Boolean | false |
Prefix | Specifies a string that the input string must begin with. | String | N/A |
SafeRegex | Specifies a regular expression for matching the input string programmatically. Envoy supports Google's RE2 regex engine. | String | N/A |
Suffix | Specifies a string that the input string must end with. | String | N/A |
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:
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
:
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
:
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: