中间件组件说明 on Dapr 文档库

Bearer

Mon, 01 Jan 0001 00:00:00 +0000

Bearer HTTP 中间件利用 OpenID Connect 在 Web API 上验证 Bearer Token，无需修改应用程序代码。此设计将身份验证和授权与应用程序逻辑分离，使应用程序管理员可以配置身份验证和授权提供者，而不影响应用程序的正常运行。

组件格式

apiVersion: dapr.io/v1alpha1
kind: Component
metadata:
 name: bearer-token
spec:
 type: middleware.http.bearer
 version: v1
 metadata:
 - name: audience
 value: "<您的令牌受众，例如应用程序的客户端 ID>"
 - name: issuer
 value: "<您的令牌发行者，例如 'https://accounts.google.com'>"

 # 可选项
 - name: jwksURL
 value: "<JWKS URL，例如 'https://accounts.google.com/.well-known/openid-configuration'>"

规格元数据字段

字段	必需	详情	示例
`audience`	Y	令牌中预期的受众，通常是您的应用程序的客户端 ID，由 OpenID Connect 平台提供。
`issuer`	Y	令牌发行者，即令牌中发行者声明的预期值。	`"https://accounts.google.com"`
`jwksURL`	N	JWKS（包含用于验证令牌的公钥的 JWK 集）的地址。如果未设置，将尝试从 OpenID 配置文档 `<issuer>/.well-known/openid-configuration` 中获取 URL。	`"https://accounts.google.com/.well-known/openid-configuration"`

issuer 的常见值包括：

OAuth2

Mon, 01 Jan 0001 00:00:00 +0000

OAuth2 HTTP中间件在Web API上启用OAuth2授权码流程，无需修改应用程序代码。这种设计将身份验证和授权问题与应用程序分离开来，使应用程序操作员可以独立采用和配置身份验证/授权提供者，而不影响应用程序的代码。

组件格式

apiVersion: dapr.io/v1alpha1
kind: Component
metadata:
 name: oauth2
spec:
 type: middleware.http.oauth2
 version: v1
 metadata:
 - name: clientId
 value: "<your client ID>"
 - name: clientSecret
 value: "<your client secret>"
 - name: scopes
 value: "https://www.googleapis.com/auth/userinfo.email"
 - name: authURL
 value: "https://accounts.google.com/o/oauth2/v2/auth"
 - name: tokenURL
 value: "https://accounts.google.com/o/oauth2/token"
 - name: redirectURL
 value: "http://dummy.com"
 - name: authHeaderName
 value: "authorization"
 - name: forceHTTPS
 value: "false"

警告

上述示例中使用了明文字符串来表示secret。建议使用secret存储来安全地存储这些secret，具体方法请参见此处。

规范元数据字段

字段	详情	示例
clientId	您的应用程序的客户端ID，是在启用OAuth的平台上创建的凭据的一部分	`"your-client-id"`
clientSecret	您的应用程序的客户端secret，是在启用OAuth的平台上创建的凭据的一部分	`"your-client-secret"`
scopes	空格分隔的、区分大小写的范围字符串列表，通常用于应用程序中的授权	`"https://www.googleapis.com/auth/userinfo.email"`
authURL	OAuth2授权服务器的端点	`"https://accounts.google.com/o/oauth2/v2/auth"`
tokenURL	客户端通过提供其授权授予或刷新令牌来获取访问令牌的端点	`"https://accounts.google.com/o/oauth2/token"`
redirectURL	用户认证后授权服务器应重定向到的Web应用程序的URL	`"https://myapp.com"`
authHeaderName	转发到应用程序的授权头名称	`"authorization"`
forceHTTPS	如果为true，则强制使用TLS/SSL	`"true"`,`"false"`

Dapr配置

要应用中间件，必须在配置中引用。请参阅中间件处理管道。

OAuth2 客户端凭证

Mon, 01 Jan 0001 00:00:00 +0000

OAuth2 客户端凭证的 HTTP 中间件可以在 Web API 上启用 OAuth2 客户端凭证流程，而无需对应用程序进行任何修改。这种设计将身份验证和授权与应用程序逻辑分离，使得应用程序的操作员可以独立于应用程序代码来选择和配置身份验证/授权提供者。

组件格式

apiVersion: dapr.io/v1alpha1
kind: Component
metadata:
 name: oauth2clientcredentials
spec:
 type: middleware.http.oauth2clientcredentials
 version: v1
 metadata:
 - name: clientId
 value: "<your client ID>"
 - name: clientSecret
 value: "<your client secret>"
 - name: scopes
 value: "https://www.googleapis.com/auth/userinfo.email"
 - name: tokenURL
 value: "https://accounts.google.com/o/oauth2/token"
 - name: headerName
 value: "authorization"

警告

上述示例中使用了明文字符串来表示 secret。建议使用 secret 存储来安全地存储这些敏感信息，具体方法请参见这里。

规范元数据字段

字段	详情	示例
clientId	您的应用程序的客户端 ID，是由支持 OAuth 的平台生成的凭证的一部分
clientSecret	您的应用程序的客户端 secret，是由支持 OAuth 的平台生成的凭证的一部分
scopes	空格分隔的、区分大小写的 scopes 字符串列表，通常用于定义应用程序的授权范围	`"https://www.googleapis.com/auth/userinfo.email"`
tokenURL	客户端通过提供授权授予或刷新令牌来获取访问令牌的端点	`"https://accounts.google.com/o/oauth2/token"`
headerName	转发到您的应用程序的授权头名称	`"authorization"`
endpointParamsQuery	指定请求令牌端点的附加参数	`true`
authStyle	可选地指定端点希望客户端 ID 和客户端 secret 发送的方式。请参阅下表中的可能值	`0`

`authStyle` 的可能值

值	含义
`1`	在 POST 请求体中以 application/x-www-form-urlencoded 参数的形式发送 “client_id” 和 “client_secret”。
`2`	使用 HTTP 基本授权方式发送 “client_id” 和 “client_secret”。这是 OAuth2 RFC 6749 第 2.3.1 节中描述的可选方式。
`0`	自动检测提供者期望的身份验证方式，通过尝试两种方式并缓存成功的方式以备将来使用。

Dapr 配置

要应用中间件，必须在配置中引用。请参阅中间件管道。

应用 Open Policy Agent (OPA) 策略

Mon, 01 Jan 0001 00:00:00 +0000

Open Policy Agent (OPA) HTTP 中间件用于对传入的 Dapr HTTP 请求应用 OPA 策略。这可以用于在应用程序端点上实施可重用的授权策略。

组件格式

apiVersion: dapr.io/v1alpha1
kind: Component
metadata:
 name: my-policy
spec:
 type: middleware.http.opa
 version: v1
 metadata:
 # `includedHeaders` 是一个不区分大小写的逗号分隔的头集合，包含在请求输入中。
 # 默认情况下，请求头不会传递给策略。需要明确指定以接收传入请求头。
 - name: includedHeaders
 value: "x-my-custom-header, x-jwt-header"

 # `defaultStatus` 是拒绝响应时返回的状态码
 - name: defaultStatus
 value: 403

 # `readBody` 控制中间件是否在内存中读取整个请求体并使其可用于策略决策。
 - name: readBody
 value: "false"

 # `rego` 是要评估的 open policy agent 策略。必需
 # 策略包必须命名为 http，策略必须设置 data.http.allow
 - name: rego
 value: |
 package http

 default allow = true

 # Allow 也可以是一个对象并包含其他属性

 # 例如，如果您想在策略失败时重定向，可以将状态码设置为 301 并在响应中设置位置头：
 allow = {
 "status_code": 301,
 "additional_headers": {
 "location": "https://my.site/authorize"
 }
 } {
 not jwt.payload["my-claim"]
 }

 # 您还可以允许请求并向其添加其他头：
 allow = {
 "allow": true,
 "additional_headers": {
 "x-my-claim": my_claim
 }
 } {
 my_claim := jwt.payload["my-claim"]
 }
 jwt = { "payload": payload } {
 auth_header := input.request.headers["Authorization"]
 [_, jwt] := split(auth_header, " ")
 [_, payload, _] := io.jwt.decode(jwt)
 }

您可以使用官方 OPA playground 来原型和实验策略。例如，您可以在此处找到上面的示例策略。

RouterChecker HTTP 请求路由检查

Mon, 01 Jan 0001 00:00:00 +0000

RouterChecker HTTP 中间件组件通过正则表达式来验证 HTTP 请求路由的有效性，防止无效路由进入 Dapr 集群。RouterChecker 组件能够过滤掉不良请求，从而减少遥测和日志数据中的噪音。

组件格式

RouterChecker 对传入的 HTTP 请求应用一组规则。您可以在组件的元数据中使用正则表达式来定义这些规则。在以下示例中，HTTP 请求 RouterChecker 被设置为验证所有请求路径是否符合 ^[A-Za-z0-9/._-]+$ 这个正则表达式。

apiVersion: dapr.io/v1alpha1
kind: Component
metadata:
 name: routerchecker 
spec:
 type: middleware.http.routerchecker
 version: v1
 metadata:
 - name: rule
 value: "^[A-Za-z0-9/._-]+$"

在此示例中，上述定义将导致以下请求被通过或拒绝：

PASS /v1.0/invoke/demo/method/method
PASS /v1.0/invoke/demo.default/method/method
PASS /v1.0/invoke/demo.default/method/01
PASS /v1.0/invoke/demo.default/method/METHOD
PASS /v1.0/invoke/demo.default/method/user/info
PASS /v1.0/invoke/demo.default/method/user_info
PASS /v1.0/invoke/demo.default/method/user-info

FAIL /v1.0/invoke/demo.default/method/cat password
FAIL /v1.0/invoke/demo.default/method/" AND 4210=4210 limit 1
FAIL /v1.0/invoke/demo.default/method/"$(curl

规格元数据字段

字段	详情	示例
rule	HTTP 请求 RouterChecker 使用的正则表达式	`^[A-Za-z0-9/._-]+$`

Dapr 配置

要应用中间件，必须在配置中引用。请参阅中间件管道。

Sentinel 容错中间件组件

Mon, 01 Jan 0001 00:00:00 +0000

Sentinel 是一个强大的容错组件，专注于流量管理，涵盖流量控制、流量整形、并发限制、熔断降级和自适应系统保护等多个领域，以确保微服务的可靠性和弹性。

Sentinel HTTP 中间件使 Dapr 可以利用 Sentinel 的强大功能来保护您的应用程序。您可以参考 Sentinel Wiki 以获取有关 Sentinel 的更多详细信息。

组件格式

在以下定义中，最大请求数被设定为每秒 10 个：

apiVersion: dapr.io/v1alpha1
kind: Component
metadata:
 name: sentinel
spec:
 type: middleware.http.sentinel
 version: v1
 metadata:
 - name: appName
 value: "nodeapp"
 - name: logDir
 value: "/var/tmp"
 - name: flowRules
 value: >-
 [
 {
 "resource": "POST:/v1.0/invoke/nodeapp/method/neworder",
 "threshold": 10,
 "tokenCalculateStrategy": 0,
 "controlBehavior": 0
 }
 ]

规格元数据字段

字段	详情	示例
appName	当前运行服务的名称	`nodeapp`
logDir	日志目录路径	`/var/tmp/sentinel`
flowRules	Sentinel 流量控制规则的 JSON 数组	流量控制规则
circuitBreakerRules	Sentinel 熔断器规则的 JSON 数组	熔断器规则
hotSpotParamRules	Sentinel 热点参数流量控制规则的 JSON 数组	热点规则
isolationRules	Sentinel 隔离规则的 JSON 数组	隔离规则
systemRules	Sentinel 系统规则的 JSON 数组	系统规则

一旦达到限制，请求将返回 HTTP 状态码 429: 请求过多。

Wasm

Mon, 01 Jan 0001 00:00:00 +0000

WebAssembly是一种安全执行由其他语言编译的代码的方法。运行时会执行WebAssembly模块（Wasm），这些模块通常是带有.wasm扩展名的二进制文件。

Wasm HTTP中间件允许您使用编译为Wasm二进制文件的自定义逻辑来处理传入请求或提供响应。换句话说，您可以使用未预编译到daprd二进制文件中的外部文件来扩展Dapr。Dapr嵌入了wazero以在不使用CGO的情况下实现这一点。

Wasm二进制文件可以从URL加载。例如，使用URL file://rewrite.wasm可以从进程的当前目录加载rewrite.wasm文件。在Kubernetes环境中，您可以参考如何：将Pod卷挂载到Dapr sidecar来配置可以包含Wasm模块的文件系统挂载。也可以从远程URL获取Wasm二进制文件。在这种情况下，URL必须精确指向一个Wasm二进制文件。例如：

http://example.com/rewrite.wasm，或
https://example.com/rewrite.wasm。

组件格式

apiVersion: dapr.io/v1alpha1
kind: Component
metadata:
 name: wasm
spec:
 type: middleware.http.wasm
 version: v1
 metadata:
 - name: url
 value: "file://router.wasm"
 - guestConfig
 value: {"environment":"production"}

规范元数据字段

用户至少需要指定一个实现http-handler的Wasm二进制文件。如何编译将在后面描述。

字段	详情	必需	示例
url	包含要实例化的Wasm二进制文件的资源URL。支持的方案包括`file://`、`http://`和`https://`。`file://` URL的路径相对于Dapr进程，除非它以`/`开头。	true	`file://hello.wasm`，`https://example.com/hello.wasm`
guestConfig	传递给Wasm来宾的可选配置。用户可以传递由Wasm代码解析的任意字符串。	false	`environment=production`，`{"environment":"production"}`

Dapr配置

要应用中间件，必须在configuration中引用它。请参阅中间件管道。

apiVersion: dapr.io/v1alpha1
kind: Configuration
metadata:
 name: appconfig
spec:
 httpPipeline:
 handlers:
 - name: wasm
 type: middleware.http.wasm

注意：WebAssembly中间件使用的资源比本地中间件多。这可能导致资源限制比在本地代码中更快达到。生产环境中应控制最大并发。

将请求体转换为大写

Mon, 01 Jan 0001 00:00:00 +0000

大写HTTP中间件用于将请求体的内容转换为大写字母。它主要用于测试管道的正常运行，仅在本地开发环境中使用。

组件格式

在以下定义中，该中间件将请求体的内容转换为大写：

apiVersion: dapr.io/v1alpha1
kind: Component
metadata:
 name: uppercase
spec:
 type: middleware.http.uppercase
 version: v1

此组件没有可配置的metadata选项。

Dapr配置

要使用此中间件，必须在配置中进行设置。请参阅中间件管道以获取更多信息。

apiVersion: dapr.io/v1alpha1
kind: Configuration
metadata:
 name: appconfig
spec:
 httpPipeline:
 handlers:
 - name: uppercase
 type: middleware.http.uppercase

HTTP 路由别名

Mon, 01 Jan 0001 00:00:00 +0000

HTTP 路由别名中间件组件允许您将进入 Dapr 的任意 HTTP 路由映射为有效的 Dapr API 端点。

组件格式

apiVersion: dapr.io/v1alpha1
kind: Component
metadata:
 name: routeralias 
spec:
 type: middleware.http.routeralias
 version: v1
 metadata:
 # 包含 JSON 或 YAML 格式的字典字符串
 # 字典中的每个键是传入路径，值是映射后的路径
 - name: "routes"
 value: |
 {
 "/mall/activity/info": "/v1.0/invoke/srv.default/method/mall/activity/info",
 "/hello/activity/{id}/info": "/v1.0/invoke/srv.default/method/hello/activity/info",
 "/hello/activity/{id}/user": "/v1.0/invoke/srv.default/method/hello/activity/user"
 }

在上面的示例中，传入的 HTTP 请求 /mall/activity/info?id=123 会被映射为 /v1.0/invoke/srv.default/method/mall/activity/info?id=123。

规格元数据字段

字段	详情	示例
`routes`	包含 JSON 或 YAML 格式的字典字符串。字典中的每个键是传入路径，值是映射后的路径。	见上例

Dapr 配置

要使用中间件，必须在配置中进行引用。参见中间件管道。

速率限制

Mon, 01 Jan 0001 00:00:00 +0000

HTTP中间件速率限制HTTP中间件允许您限制每秒HTTP请求的最大数量。通过速率限制，您可以保护应用程序免受拒绝服务（DoS）攻击的影响。DoS攻击可能由恶意第三方发起，也可能由于软件错误（即所谓的“友军火力”DoS攻击）而发生。

组件格式

在以下定义中，每秒最大请求数被设置为10：

apiVersion: dapr.io/v1alpha1
kind: Component
metadata:
 name: ratelimit
spec:
 type: middleware.http.ratelimit
 version: v1
 metadata:
 - name: maxRequestsPerSecond
 value: 10

规格元数据字段

字段	详情	示例
`maxRequestsPerSecond`	每秒允许的最大请求数，基于远程IP。组件通过`X-Forwarded-For`和`X-Real-IP`头来识别请求者的IP。	`10`

一旦达到限制，请求将返回HTTP状态码429: Too Many Requests。

重要

速率限制是在每个Dapr sidecar中独立执行的，而不是在整个集群范围内统一执行。

此外，您还可以使用最大并发设置来限制应用程序的请求处理能力，这种方法适用于所有流量，不论远程IP、协议或路径。

Dapr配置

要应用中间件，必须在配置中进行引用。请参阅中间件管道。

apiVersion: dapr.io/v1alpha1
kind: Configuration
metadata:
 name: appconfig
spec:
 httpPipeline:
 handlers:
 - name: ratelimit
 type: middleware.http.ratelimit

中间件组件说明 on Dapr 文档库

Bearer

组件格式

规格元数据字段

OAuth2

组件格式

警告

规范元数据字段

Dapr配置

OAuth2 客户端凭证

组件格式

警告

规范元数据字段

authStyle 的可能值

Dapr 配置

应用 Open Policy Agent (OPA) 策略

组件格式

RouterChecker HTTP 请求路由检查

组件格式

规格元数据字段

Dapr 配置

Sentinel 容错中间件组件

组件格式

规格元数据字段

Wasm

组件格式

规范元数据字段

Dapr配置

将请求体转换为大写

组件格式

Dapr配置

相关链接

HTTP 路由别名

组件格式

规格元数据字段

Dapr 配置

速率限制

组件格式

规格元数据字段

重要

Dapr配置

相关链接

`authStyle` 的可能值