External Authentication

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

Name	Data Type	Required	Default Value	Description
`http_service`	object	Yes	-	Configuration for the external authorization service
`failure_mode_allow`	bool	No	false	When 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_add`	bool	No	false	When 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_error`	int	No	403	Sets 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`

Name	Data Type	Required	Default Value	Description
`endpoint_mode`	string	No	envoy	Select either `envoy` or `forward_auth` as an optional choice
`endpoint`	object	Yes	-	Information about the HTTP service for sending authentication requests
`timeout`	int	No	1000	Connection timeout for `ext-auth` service, in milliseconds
`authorization_request`	object	No	-	Configuration for sending authentication requests
`authorization_response`	object	No	-	Configuration for processing authentication responses

Configuration Fields for Each Item in `endpoint`

Name	Data Type	Required	Default Value	Description
`service_name`	string	Required	-	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_port`	int	No	80	Input the port of the authorization service
`service_host`	string	No	-	The Host header set when requesting the authorization service; remains the same as FQDN if not filled
`path_prefix`	string	Required when `endpoint_mode` is `envoy`		Request path prefix for the client when sending requests to the authorization service
`request_method`	string	No	GET	HTTP Method for client requests to the authorization service when `endpoint_mode` is `forward_auth`
`path`	string	Required 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`

Name	Data Type	Required	Default Value	Description
`allowed_headers`	array of StringMatcher	No	-	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_add`	`map[string]string`	No	-	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_body`	bool	No	false	Buffer 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_bytes`	int	No	10MB	Sets 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`

Name	Data Type	Required	Default Value	Description
`allowed_upstream_headers`	array of StringMatcher	No	-	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_headers`	array of StringMatcher	No	-	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.

Name	Data Type	Required	Default Value	Description
`exact`	string	No, must select one from `exact`, `prefix`, `suffix`, `contains`, `regex`	-	Exact match
`prefix`	string	No, must select one from `exact`, `prefix`, `suffix`, `contains`, `regex`	-	Prefix match
`suffix`	string	No, must select one from `exact`, `prefix`, `suffix`, `contains`, `regex`	-	Suffix match
`contains`	string	No, must select one from `exact`, `prefix`, `suffix`, `contains`, `regex`	-	Contains match
`regex`	string	No, 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:

http_service:
  endpoint_mode: envoy
  endpoint:
    service_name: ext-auth.backend.svc.cluster.local
    service_port: 8090
    path_prefix: /auth
  timeout: 1000

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

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:

POST /auth/users?apikey=9a342114-ba8a-11ec-b1bf-00163e1250b5 HTTP/1.1
Host: ext-auth.backend.svc.cluster.local
Authorization: xxx
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:

HTTP/1.1 403 Forbidden
x-auth-version: 1.0
x-auth-failed: true
date: Tue, 16 Jul 2024 00:19:41 GMT
server: istio-envoy
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:

http_service:
  authorization_request:
    allowed_headers:
    - exact: x-auth-version
    headers_to_add:
      x-envoy-header: true
  authorization_response:
    allowed_upstream_headers:
    - exact: x-user-id
    - exact: x-auth-version
  endpoint_mode: envoy
  endpoint:
    service_name: ext-auth.backend.svc.cluster.local
    service_host: my-domain.local
    service_port: 8090
    path_prefix: /auth
  timeout: 1000

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

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:

POST /auth/users?apikey=9a342114-ba8a-11ec-b1bf-00163e1250b5 HTTP/1.1
Host: my-domain.local
Authorization: xxx
X-Auth-Version: 1.0
x-envoy-header: true
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:

http_service:
  endpoint_mode: forward_auth
  endpoint:
    service_name: ext-auth.backend.svc.cluster.local
    service_port: 8090
    path: /auth
    request_method: POST
  timeout: 1000

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

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:

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

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

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

Example 2: `ext-auth` Plugin Configuration:

http_service:
  authorization_request:
    allowed_headers:
    - exact: x-auth-version
    headers_to_add:
      x-envoy-header: true
  authorization_response:
    allowed_upstream_headers:
    - exact: x-user-id
    - exact: x-auth-version
  endpoint_mode: forward_auth
  endpoint:
    service_name: ext-auth.backend.svc.cluster.local
    service_host: my-domain.local
    service_port: 8090
    path: /auth
    request_method: POST
  timeout: 1000

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

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:

POST /auth HTTP/1.1
Host: my-domain.local
Authorization: xxx
X-Original-Uri: /users?apikey=9a342114-ba8a-11ec-b1bf-00163e1250b5
X-Original-Method: GET
X-Auth-Version: 1.0
x-envoy-header: true
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.

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

Header	Description
x-forwarded-proto	The scheme of the original request, e.g., http/https
x-forwarded-method	The method of the original request, e.g., get/post/delete/patch
x-forwarded-host	The host of the original request
x-forwarded-uri	The path of the original request, including path parameters, e.g., /v1/app?test=true
x-forwarded-for	The client IP address of the original request

External Authentication

Function Description

Execution Properties

Configuration Fields

Configuration Fields for Each Item in http_service

Configuration Fields for Each Item in endpoint

Configuration Fields for Each Item in authorization_request

Configuration Fields for Each Item in authorization_response

Field Descriptions for StringMatcher Type

Configuration Example

Example 1: endpoint_mode is envoy

Configuration of ext-auth Plugin:

Example 2: ext-auth Plugin Configuration:

Example 1: endpoint_mode is forward_auth

Example 2: ext-auth Plugin Configuration:

x-forwarded-* Header

Configuration Fields for Each Item in `http_service`

Configuration Fields for Each Item in `endpoint`

Configuration Fields for Each Item in `authorization_request`

Configuration Fields for Each Item in `authorization_response`

Field Descriptions for `StringMatcher` Type

Example 1: `endpoint_mode` is `envoy`

Configuration of `ext-auth` Plugin:

Example 2: `ext-auth` Plugin Configuration:

Example 1: `endpoint_mode` is `forward_auth`

Example 2: `ext-auth` Plugin Configuration: