Envoy HTTP过滤器中的外部授权

概述

外部授权过滤器调用授权服务检查收到的请求是否被授权。授权过滤器可以是网络过滤器也可以是HTTP过滤器。如果网络过滤器判定请求未授权，则会关闭链接；如果HTTP过滤器判定请求未授权，则会返回403状态码。
外部授权过滤器最好放在过滤器链的最前面，在其他过滤器处理请求前先鉴权。
如果外部服务不可访问，那么将通过可用过滤器中的failure_mode_allow配置项来决定请求是否被授权。如果该项设置为true，那么请求会被允许。默认值是false。

服务的定义

流量上下文通过下面列出的服务传递给外部授权服务。发给授权服务器的请求内容通过CheckRequest定义。

• Attribute Context
  • service.auth.v3.AttributeContext
  • service.auth.v3.AttributeContext.Peer
  • service.auth.v3.AttributeContext.Request
  • service.auth.v3.AttributeContext.HttpRequest
• Authorization Service
  • service.auth.v3.CheckRequest
  • service.auth.v3.DeniedHttpResponse
  • service.auth.v3.OkHttpResponse
  • service.auth.v3.CheckResponse

Attribute Context

service.auth.v3.AttributeContext

attribute是描述网络中活动的元数据。比如HTTP请求的大小，响应的状态码。
每个属性都有一个类型和名称，在逻辑上定义为属性上下文的原始信息（proto message）字段。属性上下文是一组独立属性，这些独立属性由Envoy授权系统支持。

{
  "source": "{...}",
  "destination": "{...}",
  "request": "{...}",
  "context_extensions": "{...}",
  "metadata_context": "{...}"
}

• source：service.auth.v3.AttributeContext.Peer类型。网络活动的源头，比如TCP链接的起点。如果一个网络活动有多个跃点，则表示最后一个跃点的发送者。
• destination：service.auth.v3.AttributeContext.Peer类型。网络活动的终点，比如TCP连接的接受端。如果一个网络活动有多个跃点，则表示最后一个跃点的接受者。
• request：service.auth.v3.AttributeContext.Request类型。网络连接，比如HTTP连接。
• context_extensions：map<string, string>类型。类似与http的header，但是不会发给上游服务器。提供一种机制，用于给授权服务发送额外的信息，但又不会改变请求的原始信息。会映射到内部不透明过滤器链条中。
• metadata_context：config.core.v3.Metadata类型。和请求相关的动态元数据。

service.auth.v3.AttributeContext.Peer

Peer中的信息描述了处理网络请求的节点的属性。节点可以是发送、转发或接收请求的服务或应用程序。服务peer应根据需要填写服务、主体和标签。

{
  "address": "{...}",
  "service": "...",
  "labels": "{...}",
  "principal": "...",
  "certificate": "..."
}

• address：config.core.v3.Address类型。peer的地址，通常是IP地址，也可以是UDS路径。
• service：字符串类型。peer的规范服务名称。
• labels：map<string, string>类型。和peer相关连。K8S中pod的标签或者虚拟机的标签。
• principal：字符串。peer的认证身份。比如和工作负载相关的服务账户身份。如果使用X.509证书声明身份，则此字段应按URI使用者备用名称、DNS使用者备用名称或使用者的顺序确定。第一身份应该是主体。主体格式是根据颁发者确定。
• certificate：字符串。X.509凭证，用于认证peer的身份。

service.auth.v3.AttributeContext.Request

代表网络请求，比如http请求。

{
  "time": "{...}",
  "http": "{...}"
}

• time：Timestamp。代理服务收到请求的地一个字节的时间戳。
• http：service.auth.v3.AttributeContext.HttpRequest 格式。代表HTTP请求或类似HTTP的请求。

service.auth.v3.AttributeContext.HttpRequest

描述http请求的属性。HTTP/1.x，HTTP/2，gRPC 都视为HTTP请求。

{
  "id": "...",
  "method": "...",
  "headers": "{...}",
  "path": "...",
  "host": "...",
  "scheme": "...",
  "query": "...",
  "fragment": "...",
  "size": "...",
  "protocol": "...",
  "body": "...",
  "raw_body": "..."
}

• id：字符串。代表请求的唯一id，可以返回给下游客户端。对于特定服务，ID在一天内发生冲突的概率应该很低。对于HTTP请求，它应该是X-Request-ID或类似的属性。
• method：字符串。请求方法，GET\POST等。
• headers：map<string, string>类型。HTTP请求头。所有请求头的键都必须是小写的。
• path：字符串。请求的目标，HTTP请求的第一行。包括URL路径和查询字符串。不需要解码。
• host：字符串。HTTP请求的HOST字段或Authority头字段的值。
• schema：字符串。HTTP请求使用的协议，比如http或https。
• query：字符串。通常是空的，查询字段通常包含在path字段中。
• fragment：字符串。通常是空的，URL片段不是作为HTTP请求的一部分提交的；它是未知的。
• size：int64类型。HTTP请求的bytes大小，未知时必须设为-1。
• protocol：字符串。请求使用的网络协议，比如“HTTP/1.0”，“HTTP/1.1”或“HTTP/2”。
• body：字符串。HTTP请求体。
• raw_body：bytes。二进制格式的HTTP请求体。

Authorization Service

外部授权网络过滤器和HTTP过滤器会使用授权服务请求信息。

service.auth.v3.CheckRequest

{
  "attributes": "{...}"
}

• attributes：service.auth.v3.AttributeContext格式。请求的属性。

service.auth.v3.DeniedHttpResponse

拒绝请求时的HTTP响应属性。

{
  "status": "{...}",
  "headers": [],
  "body": "..."
}

• status：type.v3.HttpStatus类型。必需。允许授权服务向下游客户端发送403之外的状态码。
• headers：多个config.core.v3.HeaderValueOption类型。允许授权服务器向下游客户端发送响应头。
• body：字符串。允许授权服务器向下游客户端发送响应体。

service.auth.v3.OkHttpResponse

允许请求时的HTTP响应属性。

{
  "headers": [],
  "headers_to_remove": [],
  "dynamic_metadata": "{...}",
  "response_headers_to_add": []
}

• headers：多个config.core.v3.HeaderValueOption类型。原始请求头之外的HTTP头信息。用于授权服务在把请求发给上游服务器之前添加或覆盖某些请求头。请注意，当在该消息中使用时，HeaderValueOption中的append字段默认为false。通过将append字段设置为true，过滤器将相应的头值附加到匹配的请求头。通过将append保留为false，过滤器将添加新的头，或者在存在匹配项时覆盖现有头。
• headers_to_remove：多个字符串。在把流量分发给上游服务器之前需要一处的请求头。这样授权服务器可以处理相关的认证信息头字段，比如（Authorization），上游服务器要么收到通过认证的请求，要么收不到请求，但是不会看到包含授权凭证的请求头信息。伪头部字段，比如authority、method、path等，不能被删除，因为删除可能导致格式不正确，如果包含在headers_to_remove中，会被忽略。使用HTTP服务时，必须由HTTP授权服务将其设置为逗号分隔的列表，如下所示：x-envoy-auth-headers-to-remove: one-auth-header, another-auth-header。
• response_headers_to_add：多条config.core.v3.HeaderValueOption类型。如果鉴权通过的话，授权服务可以通过这个字段向下游客户端返回响应头。请注意，当使用这个字段时，HeaderValueOption中的append字段默认为false。

service.auth.v3.CheckResponse

仅用于gRPC和网络授权服务。

{
  "status": "{...}",
  "denied_response": "{...}",
  "ok_response": "{...}",
  "dynamic_metadata": "{...}"
}

• status：Status类型。OK表示允许请求，其他状态都表示否定。
• denied_response：service.auth.v3.DeniedHttpResponse类型。拒绝请求时提供的响应属性。
• ok_response：service.auth.v3.OkHttpResponse类型。允许请求时提供的响应属性。
• dynamic_metadata：struct类型。可选的响应元数据，将作为动态元数据发出，供下一个过滤器使用。

示例

gRPC授权服务过滤器配置示例：

http_filters:
  - name: envoy.filters.http.ext_authz
    typed_config:
      "@type": type.googleapis.com/envoy.extensions.filters.http.ext_authz.v3.ExtAuthz
      grpc_service:
        envoy_grpc:
          cluster_name: ext-authz

        # Default is 200ms; override if your server needs e.g. warmup time.
        timeout: 0.5s
      include_peer_certificate: true

clusters:
  - name: ext-authz
    type: static
    typed_extension_protocol_options:
      envoy.extensions.upstreams.http.v3.HttpProtocolOptions:
        "@type": type.googleapis.com/envoy.extensions.upstreams.http.v3.HttpProtocolOptions
        explicit_http_config:
          http2_protocol_options: {}
    load_assignment:
      cluster_name: ext-authz
      endpoints:
      - lb_endpoints:
        - endpoint:
            address:
              socket_address:
                address: 127.0.0.1
                port_value: 10003

    # This timeout controls the initial TCP handshake timeout - not the timeout for the
    # entire request.
    connect_timeout: 0.25s

此过滤器的一个功能是将HTTP请求正文作为检查请求的一部分发送到已配置的gRPC授权服务器。
下面是一个实例配置:

http_filters:
 - name: envoy.filters.http.ext_authz
   typed_config:
     "@type": type.googleapis.com/envoy.extensions.filters.http.ext_authz.v3.ExtAuthz
     grpc_service:
       envoy_grpc:
         cluster_name: ext-authz
     with_request_body:
       max_request_bytes: 1024
       allow_partial_message: true
       pack_as_bytes: true

请注意，默认情况下，check request将HTTP请求体作为UTF-8字符串携带，并填充body字段。要将请求体打包为字节，需要将pack_as_bytes字段设置为true。实际上，raw_body字段将被设置，body字段将为空。

HTTP授权服务过滤器配置示例：

http_filters:
  - name: envoy.filters.http.ext_authz
    typed_config:
      "@type": type.googleapis.com/envoy.extensions.filters.http.ext_authz.v3.ExtAuthz
      http_service:
          server_uri:
            uri: 127.0.0.1:10003
            cluster: ext-authz
            timeout: 0.25s
            failure_mode_allow: false
      include_peer_certificate: true

clusters:
  - name: ext-authz
    connect_timeout: 0.25s
    type: logical_dns
    lb_policy: round_robin
    load_assignment:
      cluster_name: ext-authz
      endpoints:
      - lb_endpoints:
        - endpoint:
            address:
              socket_address:
                address: 127.0.0.1
                port_value: 10003

虚拟主机和路由筛选器配置示例。在本例中，我们在虚拟主机上添加了其他上下文，并禁用了/static前缀路由的筛选器。

route_config:
  name: local_route
  virtual_hosts:
  - name: local_service
    domains: ["*"]
    typed_per_filter_config:
      envoy.filters.http.ext_authz:
        "@type": type.googleapis.com/envoy.extensions.filters.http.ext_authz.v3.ExtAuthzPerRoute
        check_settings:
          context_extensions:
            virtual_host: local_service
    routes:
    - match: { prefix: "/static" }
      route: { cluster: some_service }
      typed_per_filter_config:
        envoy.filters.http.ext_authz:
          "@type": type.googleapis.com/envoy.extensions.filters.http.ext_authz.v3.ExtAuthzPerRoute
          disabled: true
    - match: { prefix: "/" }
      route: { cluster: some_service }