认证 - 外部认证 - 《Higress v2.0 中文文档》

功能说明
运行属性
配置字段
配置示例
- endpoint_mode为envoy时
  - 示例1
  - 示例2
- endpoint_mode为forward_auth时

功能说明

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

运行属性

插件执行阶段：认证阶段 插件执行优先级：360

配置字段

名称	数据类型	必填	默认值	描述
`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	输入授权服务的服务端口
`service_host`	string	否	-	请求授权服务时设置的Host头，不填时和FQDN保持一致
`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-Original-Uri` ，原始请求的HTTP Method设置到 `X-Original-Method` ）
`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` 中选填一项	-	正则匹配

配置示例

下面假设 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.backend.svc.cluster.local
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_host: my-domain.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: my-domain.local
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 “foo: bar” -H “Authorization: xxx”

请求 ext-auth 服务成功：

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

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

请求 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_host: my-domain.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 “foo: bar” -H “Authorization: xxx” -H “X-Auth-Version: 1.0”

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

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

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

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
x-forwarded-for	原始请求的客户端IP地址