Authorization Service

This documentation is for the Envoy v3 API.

As of Envoy v1.18 the v2 API has been removed and is no longer supported.

If you are upgrading from v2 API config you may wish to view the v2 API documentation:

service/auth/v2/external_auth.proto

The authorization service request messages used by external authorization network filter and HTTP filter.

service.auth.v3.CheckRequest

[service.auth.v3.CheckRequest proto]

  1. {
  2.   "attributes": "{...}"
  3. }

attributes

(service.auth.v3.AttributeContext) The request attributes.

service.auth.v3.DeniedHttpResponse

[service.auth.v3.DeniedHttpResponse proto]

HTTP attributes for a denied response.

  1. {
  2.   "status": "{...}",
  3.   "headers": [],
  4.   "body": "..."
  5. }

status

(type.v3.HttpStatus) This field allows the authorization service to send an HTTP response status code to the downstream client. If not set, Envoy sends 403 Forbidden HTTP status code by default.

headers

(repeated config.core.v3.HeaderValueOption) This field allows the authorization service to send HTTP response headers to the downstream client. Note that the append field in HeaderValueOption defaults to false when used in this message.

body

(string) This field allows the authorization service to send a response body data to the downstream client.

service.auth.v3.OkHttpResponse

[service.auth.v3.OkHttpResponse proto]

HTTP attributes for an OK response.

  1. {
  2.   "headers": [],
  3.   "headers_to_remove": [],
  4.   "dynamic_metadata": "{...}",
  5.   "response_headers_to_add": []
  6. }

headers

(repeated config.core.v3.HeaderValueOption) HTTP entity headers in addition to the original request headers. This allows the authorization service to append, to add or to override headers from the original request before dispatching it to the upstream. Note that the append field in HeaderValueOption defaults to false when used in this message. By setting the append field to true, the filter will append the correspondent header value to the matched request header. By leaving append as false, the filter will either add a new header, or override an existing one if there is a match.

headers_to_remove

(repeated string) HTTP entity headers to remove from the original request before dispatching it to the upstream. This allows the authorization service to act on auth related headers (like Authorization), process them, and consume them. Under this model, the upstream will either receive the request (if it’s authorized) or not receive it (if it’s not), but will not see headers containing authorization credentials.

Pseudo headers (such as :authority, :method, :path etc), as well as the header Host, may not be removed as that would make the request malformed. If mentioned in headers_to_remove these special headers will be ignored.

When using the HTTP service this must instead be set by the HTTP authorization service as a comma separated list like so: x-envoy-auth-headers-to-remove: one-auth-header, another-auth-header.

dynamic_metadata

(Struct) This field has been deprecated in favor of CheckResponse.dynamic_metadata. Until it is removed, setting this field overrides CheckResponse.dynamic_metadata.

response_headers_to_add

(repeated config.core.v3.HeaderValueOption) This field allows the authorization service to send HTTP response headers to the downstream client on success. Note that the append field in HeaderValueOption defaults to false when used in this message.

service.auth.v3.CheckResponse

[service.auth.v3.CheckResponse proto]

Intended for gRPC and Network Authorization servers only.

  1. {
  2.   "status": "{...}",
  3.   "denied_response": "{...}",
  4.   "ok_response": "{...}",
  5.   "dynamic_metadata": "{...}"
  6. }

status

(Status) Status OK allows the request. Any other status indicates the request should be denied, and for HTTP filter, if not overridden by denied HTTP response status Envoy sends 403 Forbidden HTTP status code by default.

denied_response

(service.auth.v3.DeniedHttpResponse) Supplies http attributes for a denied response.

An message that contains HTTP response attributes. This message is used when the authorization service needs to send custom responses to the downstream client or, to modify/add request headers being dispatched to the upstream.

Only one of denied_response, ok_response may be set.

ok_response

(service.auth.v3.OkHttpResponse) Supplies http attributes for an ok response.

An message that contains HTTP response attributes. This message is used when the authorization service needs to send custom responses to the downstream client or, to modify/add request headers being dispatched to the upstream.

Only one of denied_response, ok_response may be set.

dynamic_metadata

(Struct) Optional response metadata that will be emitted as dynamic metadata to be consumed by the next filter. This metadata lives in a namespace specified by the canonical name of extension filter that requires it: