外部认证

功能说明

ext-auth 插件实现了向外部授权服务发送鉴权请求，以检查客户端请求是否得到授权。该插件实现时参考了 Envoy 原生的 ext_authz filter，实现了原生 filter 中对接 HTTP 服务的部分能力。

配置字段

名称	数据类型	必填	默认值	描述
`http_service`	object	是	-	外部授权服务配置
`failure_mode_allow`	bool	否	false	当设置为 `true` 时，即使与授权服务的通信失败，或者授权服务返回了 HTTP 5xx 错误，仍会接受客户端请求
`failure_mode_allow_header_add`	bool	否	false	当 `failure_mode_allow` 和 `failure_mode_allow_header_add` 都设置为 `true` 时，若与授权服务的通信失败，或授权服务返回了 HTTP 5xx 错误，那么请求头中将会添加 `x-envoy-auth-failure-mode-allowed: true`
`status_on_error`	int	否	403	当授权服务无法访问或状态码为 5xx 时，设置返回给客户端的 HTTP 状态码。默认状态码是 `403`

http_service 中每一项的配置字段说明如下：

名称	数据类型	必填	默认值	描述
`endpoint_mode`	string	否	envoy	`envoy` 或 `forward_auth` 中选填一项
`endpoint`	object	是	-	发送鉴权请求的 HTTP 服务信息
`timeout`	int	否	1000	`ext-auth` 服务连接超时时间，单位毫秒
`authorization_request`	object	否	-	发送鉴权请求配置
`authorization_response`	object	否	-	处理鉴权响应配置

endpoint 中每一项的配置字段说明如下：

名称	数据类型	必填	默认值	描述
`service_name`	string	是	-	输入授权服务名称，带服务类型的完整 FQDN 名称，例如 `ext-auth.dns`、`ext-auth.my-ns.svc.cluster.local`
`service_port`	int	否	80	输入授权服务的服务端口
`path_prefix`	string	`endpoint_mode` 为 `envoy` 时必填	-	`endpoint_mode` 为 `envoy` 时，客户端向授权服务发送请求的请求路径前缀
`request_method`	string	否	GET	`endpoint_mode` 为 `forward_auth` 时，客户端向授权服务发送请求的 HTTP Method
`path`	string	`endpoint_mode` 为 `forward_auth` 时必填	-	`endpoint_mode` 为 `forward_auth` 时，客户端向授权服务发送请求的请求路径

authorization_request 中每一项的配置字段说明如下：

名称	数据类型	必填	默认值	描述
`allowed_headers`	array of StringMatcher	否	-	当设置后，具有相应匹配项的客户端请求头将添加到授权服务请求中的请求头中。除了用户自定义的头部匹配规则外，授权服务请求中会自动包含 `Authorization` 这个 HTTP 头（`endpoint_mode` 为 `forward_auth` 时，会把原始请求的信息设置到 `x-forwarded-*` 请求头中）
`headers_to_add`	`map[string]string`	否	-	设置将包含在授权服务请求中的请求头列表。请注意，同名的客户端请求头将被覆盖
`with_request_body`	bool	否	false	缓冲客户端请求体，并将其发送至鉴权请求中（HTTP Method 为 GET、OPTIONS、HEAD 请求时不生效）
`max_request_body_bytes`	int	否	10MB	设置在内存中保存客户端请求体的最大尺寸。当客户端请求体达到在此字段中设置的数值时，将会返回 HTTP 413 状态码，并且不会启动授权过程。注意，这个设置会优先于 `failure_mode_allow` 的配置

authorization_response 中每一项的配置字段说明如下：

名称	数据类型	必填	默认值	描述
`allowed_upstream_headers`	array of StringMatcher	否	-	当设置后，具有相应匹配项的鉴权请求的响应头将添加到原始的客户端请求头中。请注意，同名的请求头将被覆盖
`allowed_client_headers`	array of StringMatcher	否	-	如果不设置，在请求被拒绝时，所有的鉴权请求的响应头将添加到客户端的响应头中。当设置后，在请求被拒绝时，具有相应匹配项的鉴权请求的响应头将添加到客户端的响应头中

StringMatcher 类型每一项的配置字段说明如下：

在使用 array of StringMatcher 时会按照数组中定义的 StringMatcher 顺序依次进行配置。

名称	数据类型	必填	默认值	描述
`exact`	string	否，`exact`、`prefix`、`suffix`、`contains`、`regex` 中选填一项	-	精确匹配
`prefix`	string	否，`exact`、`prefix`、`suffix`、`contains`、`regex` 中选填一项	-	前缀匹配
`suffix`	string	否，`exact`、`prefix`、`suffix`、`contains`、`regex` 中选填一项	-	后缀匹配
`contains`	string	否，`exact`、`prefix`、`suffix`、`contains`、`regex` 中选填一项	-	是否包含
`regex`	string	否，`exact`、`prefix`、`suffix`、`contains`、`regex` 中选填一项	-	正则匹配

`x-forwarded-*` header

在 endpoint_mode 为 forward_auth 时，Higress 会自动生成并发送以下 header 至鉴权服务：

Header	说明
`x-forwarded-proto`	原始请求的 scheme，比如 http/https
`x-forwarded-method`	原始请求的方法，比如 get/post/delete/patch
`x-forwarded-host`	原始请求的 host
`x-forwarded-uri`	原始请求的 path，包含路径参数，比如 `/v1/app?test=true`

配置示例

下面假设 ext-auth 服务在 Kubernetes 中 serviceName 为 ext-auth，端口 8090，路径为 /auth，命名空间为 backend。

支持两种 endpoint_mode：

endpoint_mode 为 envoy 时，鉴权请求会使用原始请求的 HTTP Method 和配置的 path_prefix 作为请求路径前缀拼接上原始的请求路径。
endpoint_mode 为 forward_auth 时，鉴权请求会使用配置的 request_method 作为 HTTP Method 和配置的 path 作为请求路径。

`endpoint_mode` 为 `envoy` 时

示例1

ext-auth 插件的配置：

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

使用如下请求网关，当开启 ext-auth 插件后：

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

请求 ext-auth 服务成功：

ext-auth 服务将接收到如下的鉴权请求：

POST /auth/users?apikey=9a342114-ba8a-11ec-b1bf-00163e1250b5 HTTP/1.1
Host: ext-auth
Authorization: xxx
Content-Length: 0

请求 ext-auth 服务失败：

当调用 ext-auth 服务响应为 5xx 时，客户端将接收到 HTTP 响应码 403 和 ext-auth 服务返回的全量响应头。

假如 ext-auth 服务返回了 x-auth-version: 1.0 和 x-auth-failed: true 的响应头，会传递给客户端：

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

当 ext-auth 无法访问或状态码为 5xx 时，将以 status_on_error 配置的状态码拒绝客户端请求。

当 ext-auth 服务返回其他 HTTP 状态码时，将以返回的状态码拒绝客户端请求。如果配置了 allowed_client_headers，具有相应匹配项的响应头将添加到客户端的响应中。

示例2

ext-auth 插件的配置：

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_port: 8090
    path_prefix: /auth
  timeout: 1000

使用如下请求网关，当开启 ext-auth 插件后：

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

ext-auth 服务将接收到如下的鉴权请求：

POST /auth/users?apikey=9a342114-ba8a-11ec-b1bf-00163e1250b5 HTTP/1.1
Host: ext-auth
Authorization: xxx
X-Auth-Version: 1.0
x-envoy-header: true
Content-Length: 0

ext-auth 服务返回响应头中如果包含 x-user-id 和 x-auth-version，网关调用 upstream 时的请求中会带上这两个请求头。

`endpoint_mode` 为 `forward_auth` 时

示例1

ext-auth 插件的配置：

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

使用如下请求网关，当开启 ext-auth 插件后：

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

请求 ext-auth 服务成功：

ext-auth 服务将接收到如下的鉴权请求：

POST /auth HTTP/1.1
Host: ext-auth
Authorization: xxx
X-Forwarded-Uri: /users?apikey=9a342114-ba8a-11ec-b1bf-00163e1250b5
X-Forwarded-Host: foo.bar.com
X-Forwarded-Method: GET
X-Forwarded-Proto: http
Content-Length: 0

请求 ext-auth 服务失败：

当调用 ext-auth 服务响应为 5xx 时，客户端将接收到 HTTP 响应码 403 和 ext-auth 服务返回的全量响应头。

假如 ext-auth 服务返回了 x-auth-version: 1.0 和 x-auth-failed: true 的响应头，会传递给客户端：

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

当 ext-auth 无法访问或状态码为 5xx 时，将以 status_on_error 配置的状态码拒绝客户端请求。

示例2

ext-auth 插件的配置：

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_port: 8090
    path: /auth
    request_method: POST
  timeout: 1000

使用如下请求网关，当开启 ext-auth 插件后：

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

ext-auth 服务将接收到如下的鉴权请求：

POST /auth HTTP/1.1
Host: ext-auth
Authorization: xxx
X-Forwarded-Uri: /users?apikey=9a342114-ba8a-11ec-b1bf-00163e1250b5
X-Forwarded-Host: foo.bar.com
X-Forwarded-Method: GET
X-Forwarded-Proto: http
X-Auth-Version: 1.0
x-envoy-header: true
Content-Length: 0

ext-auth 服务返回响应头中如果包含 x-user-id 和 x-auth-version，网关调用 upstream 时的请求中会带上这两个请求头。

外部认证

功能说明

配置字段

x-forwarded-* header

配置示例

endpoint_mode 为 envoy 时

示例1

示例2

endpoint_mode 为 forward_auth 时

示例1

示例2

`x-forwarded-*` header

`endpoint_mode` 为 `envoy` 时

`endpoint_mode` 为 `forward_auth` 时