Function Description

The ext-auth plugin implements sending authentication requests to an external authorization service to check whether the client request is authorized. This plugin is implemented with reference to Envoy’s native ext_authz filter, which covers some capabilities for connecting to HTTP services.

Execution Properties

Plugin Execution Phase: Authentication Phase
Plugin Execution Priority: 360

Configuration Fields

NameData TypeRequiredDefault ValueDescription
http_serviceobjectYes-Configuration for the external authorization service
failure_mode_allowboolNofalseWhen set to true, client requests will still be accepted even if communication with the authorization service fails or the authorization service returns an HTTP 5xx error
failure_mode_allow_header_addboolNofalseWhen both failure_mode_allow and failure_mode_allow_header_add are set to true, if communication with the authorization service fails or returns an HTTP 5xx error, the request header will include x-envoy-auth-failure-mode-allowed: true
status_on_errorintNo403Sets the HTTP status code returned to the client when the authorization service is unreachable or returns a 5xx status code. The default status code is 403

Configuration Fields for Each Item in http_service

NameData TypeRequiredDefault ValueDescription
endpoint_modestringNoenvoySelect either envoy or forward_auth as an optional choice
endpointobjectYes-Information about the HTTP service for sending authentication requests
timeoutintNo1000Connection timeout for ext-auth service, in milliseconds
authorization_requestobjectNo-Configuration for sending authentication requests
authorization_responseobjectNo-Configuration for processing authentication responses

Configuration Fields for Each Item in endpoint

NameData TypeRequiredDefault ValueDescription
service_namestringRequired-Input the name of the authorization service, in complete FQDN format, e.g., ext-auth.dns or ext-auth.my-ns.svc.cluster.local
service_portintNo80Input the port of the authorization service
service_hoststringNo-The Host header set when requesting the authorization service; remains the same as FQDN if not filled
path_prefixstringRequired when endpoint_mode is envoyRequest path prefix for the client when sending requests to the authorization service
request_methodstringNoGETHTTP Method for client requests to the authorization service when endpoint_mode is forward_auth
pathstringRequired when endpoint_mode is forward_auth-Request path for the client when sending requests to the authorization service

Configuration Fields for Each Item in authorization_request

NameData TypeRequiredDefault ValueDescription
allowed_headersarray of StringMatcherNo-When set, client request headers with matching criteria will be added to the headers of the request to the authorization service. The Authorization HTTP header will be automatically included in the authorization service request, and if endpoint_mode is forward_auth, the original request path will be set to X-Original-Uri and the original request HTTP method will be set to X-Original-Method.
headers_to_addmap[string]stringNo-Sets the list of request headers to include in the authorization service request. Note that headers with the same name from the client will be overwritten.
with_request_bodyboolNofalseBuffer the client request body and send it in the authentication request (does not take effect for HTTP Methods GET, OPTIONS, and HEAD)
max_request_body_bytesintNo10MBSets the maximum size of the client request body to keep in memory. When the client request body reaches the value set in this field, an HTTP 413 status code will be returned, and the authorization process will not start. Note that this setting takes precedence over the failure_mode_allow configuration.

Configuration Fields for Each Item in authorization_response

NameData TypeRequiredDefault ValueDescription
allowed_upstream_headersarray of StringMatcherNo-When set, the response headers of the authorization request with matching criteria will be added to the original client request headers. Note that headers with the same name will be overwritten.
allowed_client_headersarray of StringMatcherNo-If not set, all response headers from authorization requests will be added to the client’s response when a request is denied. When set, response headers from authorization requests with matching criteria will be added to the client’s response when a request is denied.

Field Descriptions for StringMatcher Type

When using array of StringMatcher, the fields are configured according to the order defined in the array.

NameData TypeRequiredDefault ValueDescription
exactstringNo, must select one from exact, prefix, suffix, contains, regex-Exact match
prefixstringNo, must select one from exact, prefix, suffix, contains, regex-Prefix match
suffixstringNo, must select one from exact, prefix, suffix, contains, regex-Suffix match
containsstringNo, must select one from exact, prefix, suffix, contains, regex-Contains match
regexstringNo, must select one from exact, prefix, suffix, contains, regex-Regex match

Configuration Example

Assuming the ext-auth service has a serviceName of ext-auth, port 8090, path /auth, and namespace backend in Kubernetes.

Two types of endpoint_mode are supported:

  • When endpoint_mode is envoy, the authentication request will use the original request HTTP Method, and the configured path_prefix will be concatenated with the original request path.
  • When endpoint_mode is forward_auth, the authentication request will use the configured request_method as the HTTP Method and the configured path as the request path.

Example 1: endpoint_mode is envoy

Configuration of ext-auth Plugin:

  1. http_service:
  2.   endpoint_mode: envoy
  3.   endpoint:
  4.     service_name: ext-auth.backend.svc.cluster.local
  5.     service_port: 8090
  6.     path_prefix: /auth
  7.   timeout: 1000

Using the following request to the gateway, after enabling the ext-auth plugin:

  1. curl -X POST http://localhost:8082/users?apikey=9a342114-ba8a-11ec-b1bf-00163e1250b5 -X GET -H “foo: bar” -H “Authorization: xxx”

Successful request to the ext-auth service: The ext-auth service will receive the following authentication request:

  1. POST /auth/users?apikey=9a342114-ba8a-11ec-b1bf-00163e1250b5 HTTP/1.1
  2. Host: ext-auth.backend.svc.cluster.local
  3. Authorization: xxx
  4. Content-Length: 0

Failed request to the ext-auth service: When the ext-auth service responds with a 5xx error, the client will receive an HTTP response code of 403 along with all response headers returned by the ext-auth service.

If the ext-auth service returns x-auth-version: 1.0 and x-auth-failed: true headers, these will be conveyed to the client:

  1. HTTP/1.1 403 Forbidden
  2. x-auth-version: 1.0
  3. x-auth-failed: true
  4. date: Tue, 16 Jul 2024 00:19:41 GMT
  5. server: istio-envoy
  6. content-length: 0

When the ext-auth service is inaccessible or returns a status code of 5xx, the client request will be denied with the status code configured in status_on_error. When the ext-auth service returns other HTTP status codes, the client request will be denied with the returned status code. If allowed_client_headers is configured, the matching response headers will be added to the client’s response.

Example 2: ext-auth Plugin Configuration:

  1. http_service:
  2.   authorization_request:
  3.     allowed_headers:
  4.     - exact: x-auth-version
  5.     headers_to_add:
  6.       x-envoy-header: true
  7.   authorization_response:
  8.     allowed_upstream_headers:
  9.     - exact: x-user-id
  10.     - exact: x-auth-version
  11.   endpoint_mode: envoy
  12.   endpoint:
  13.     service_name: ext-auth.backend.svc.cluster.local
  14.     service_host: my-domain.local
  15.     service_port: 8090
  16.     path_prefix: /auth
  17.   timeout: 1000

Using the following request to the gateway after enabling the ext-auth plugin:

  1. curl -X POST http://localhost:8082/users?apikey=9a342114-ba8a-11ec-b1bf-00163e1250b5 -X GET -H “foo: bar” -H “Authorization: xxx”

The ext-auth service will receive the following authentication request:

  1. POST /auth/users?apikey=9a342114-ba8a-11ec-b1bf-00163e1250b5 HTTP/1.1
  2. Host: my-domain.local
  3. Authorization: xxx
  4. X-Auth-Version: 1.0
  5. x-envoy-header: true
  6. Content-Length: 0

If the ext-auth service returns headers containing x-user-id and x-auth-version, these two request headers will be included in requests to the upstream when the gateway calls it.

Example 1: endpoint_mode is forward_auth

ext-auth Plugin Configuration:

  1. http_service:
  2.   endpoint_mode: forward_auth
  3.   endpoint:
  4.     service_name: ext-auth.backend.svc.cluster.local
  5.     service_port: 8090
  6.     path: /auth
  7.     request_method: POST
  8.   timeout: 1000

Using the following request to the gateway after enabling the ext-auth plugin:

  1. curl -i http://localhost:8082/users?apikey=9a342114-ba8a-11ec-b1bf-00163e1250b5 -X GET -H “foo: bar” -H “Authorization: xxx”

Successful request to the ext-auth service: The ext-auth service will receive the following authentication request:

  1. POST /auth HTTP/1.1
  2. Host: ext-auth.backend.svc.cluster.local
  3. Authorization: xxx
  4. X-Original-Uri: /users?apikey=9a342114-ba8a-11ec-b1bf-00163e1250b5
  5. X-Original-Method: GET
  6. Content-Length: 0

Failed request to the ext-auth service: When the ext-auth service responds with a 5xx error, the client will receive an HTTP response code of 403 along with all response headers returned by the ext-auth service.

If the ext-auth service returns x-auth-version: 1.0 and x-auth-failed: true headers, these will be conveyed to the client:

  1. HTTP/1.1 403 Forbidden
  2. x-auth-version: 1.0
  3. x-auth-failed: true
  4. date: Tue, 16 Jul 2024 00:19:41 GMT
  5. server: istio-envoy
  6. content-length: 0

When the ext-auth service is inaccessible or returns a status code of 5xx, the client request will be denied with the status code configured in status_on_error. When the ext-auth service returns other HTTP status codes, the client request will be denied with the returned status code. If allowed_client_headers is configured, the matching response headers will be added to the client’s response.

Example 2: ext-auth Plugin Configuration:

  1. http_service:
  2.   authorization_request:
  3.     allowed_headers:
  4.     - exact: x-auth-version
  5.     headers_to_add:
  6.       x-envoy-header: true
  7.   authorization_response:
  8.     allowed_upstream_headers:
  9.     - exact: x-user-id
  10.     - exact: x-auth-version
  11.   endpoint_mode: forward_auth
  12.   endpoint:
  13.     service_name: ext-auth.backend.svc.cluster.local
  14.     service_host: my-domain.local
  15.     service_port: 8090
  16.     path: /auth
  17.     request_method: POST
  18.   timeout: 1000

Using the following request to the gateway after enabling the ext-auth plugin:

  1. curl -i http://localhost:8082/users?apikey=9a342114-ba8a-11ec-b1bf-00163e1250b5 -X GET -H “foo: bar” -H “Authorization: xxx” -H “X-Auth-Version: 1.0”

The ext-auth service will receive the following authentication request:

  1. POST /auth HTTP/1.1
  2. Host: my-domain.local
  3. Authorization: xxx
  4. X-Original-Uri: /users?apikey=9a342114-ba8a-11ec-b1bf-00163e1250b5
  5. X-Original-Method: GET
  6. X-Auth-Version: 1.0
  7. x-envoy-header: true
  8. Content-Length: 0

If the ext-auth service returns headers containing x-user-id and x-auth-version, these two request headers will be included in requests to the upstream when the gateway calls it.

x-forwarded-* Header

When endpoint_mode is forward_auth, Higress will automatically generate and send the following headers to the authorization service.

HeaderDescription
x-forwarded-protoThe scheme of the original request, e.g., http/https
x-forwarded-methodThe method of the original request, e.g., get/post/delete/patch
x-forwarded-hostThe host of the original request
x-forwarded-uriThe path of the original request, including path parameters, e.g., /v1/app?test=true
x-forwarded-forThe client IP address of the original request