Middleware component specs on Dapr Docs

Bearer

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

The bearer HTTP middleware verifies a Bearer Token using OpenID Connect on a Web API, without modifying the application. This design separates authentication/authorization concerns from the application, so that application operators can adopt and configure authentication/authorization providers without impacting the application code.

Component format

apiVersion: dapr.io/v1alpha1
kind: Component
metadata:
 name: bearer-token
spec:
 type: middleware.http.bearer
 version: v1
 metadata:
 - name: audience
 value: "<your token audience; i.e. the application's client ID>"
 - name: issuer
 value: "<your token issuer, e.g. 'https://accounts.google.com'>"

 # Optional values
 - name: jwksURL
 value: "<JWKS URL, e.g. 'https://accounts.google.com/.well-known/openid-configuration'>"

Spec metadata fields

Field	Required	Details	Example
`audience`	Y	The audience expected in the tokens. Usually, this corresponds to the client ID of your application that is created as part of a credential hosted by a OpenID Connect platform.
`issuer`	Y	The issuer authority, which is the value expected in the issuer claim in the tokens.	`"https://accounts.google.com"`
`jwksURL`	N	Address of the JWKS (JWK Set containing the public keys for verifying tokens). If empty, will try to fetch the URL set in the OpenID Configuration document `<issuer>/.well-known/openid-configuration`.	`"https://accounts.google.com/.well-known/openid-configuration"`

Common values for issuer include:

OAuth2

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

The OAuth2 HTTP middleware enables the OAuth2 Authorization Code flow on a Web API without modifying the application. This design separates authentication/authorization concerns from the application, so that application operators can adopt and configure authentication/authorization providers without impacting the application code.

Component format

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"
 - name: pathFilter
 value: ".*/users/.*"

Warning

The above example uses secrets as plain strings. It is recommended to use a secret store for the secrets as described here.

Spec metadata fields

Field	Details	Example
clientId	The client ID of your application that is created as part of a credential hosted by a OAuth-enabled platform
clientSecret	The client secret of your application that is created as part of a credential hosted by a OAuth-enabled platform
scopes	A list of space-delimited, case-sensitive strings of scopes which are typically used for authorization in the application	`"https://www.googleapis.com/auth/userinfo.email"`
authURL	The endpoint of the OAuth2 authorization server	`"https://accounts.google.com/o/oauth2/v2/auth"`
tokenURL	The endpoint is used by the client to obtain an access token by presenting its authorization grant or refresh token	`"https://accounts.google.com/o/oauth2/token"`
redirectURL	The URL of your web application that the authorization server should redirect to once the user has authenticated	`"https://myapp.com"`
authHeaderName	The authorization header name to forward to your application	`"authorization"`
forceHTTPS	If true, enforces the use of TLS/SSL	`"true"`,`"false"`
pathFilter	Applies the middleware only to requests matching the given path pattern	`"./users/."`

Dapr configuration

To be applied, the middleware must be referenced in configuration. See middleware pipelines.

OAuth2 client credentials

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

The OAuth2 client credentials HTTP middleware enables the OAuth2 Client Credentials flow on a Web API without modifying the application. This design separates authentication/authorization concerns from the application, so that application operators can adopt and configure authentication/authorization providers without impacting the application code.

Component format

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"
 - name: pathFilter
 value: ".*/users/.*"

Warning

The above example uses secrets as plain strings. It is recommended to use a secret store for the secrets as described here.

Spec metadata fields

Field	Details	Example
clientId	The client ID of your application that is created as part of a credential hosted by a OAuth-enabled platform
clientSecret	The client secret of your application that is created as part of a credential hosted by a OAuth-enabled platform
scopes	A list of space-delimited, case-sensitive strings of scopes which are typically used for authorization in the application	`"https://www.googleapis.com/auth/userinfo.email"`
tokenURL	The endpoint is used by the client to obtain an access token by presenting its authorization grant or refresh token	`"https://accounts.google.com/o/oauth2/token"`
headerName	The authorization header name to forward to your application	`"authorization"`
endpointParamsQuery	Specifies additional parameters for requests to the token endpoint	`true`
authStyle	Optionally specifies how the endpoint wants the client ID & client secret sent. See the table of possible values below	`0`
pathFilter	Applies the middleware only to requests matching the given path pattern	`"./users/."`

Possible values for `authStyle`

Value	Meaning
`1`	Sends the “client_id” and “client_secret” in the POST body as application/x-www-form-urlencoded parameters.
`2`	Sends the “client_id” and “client_secret” using HTTP Basic Authorization. This is an optional style described in the OAuth2 RFC 6749 section 2.3.1.
`0`	Means to auto-detect which authentication style the provider wants by trying both ways and caching the successful way for the future.

Dapr configuration

To be applied, the middleware must be referenced in a configuration. See middleware pipelines.

Apply Open Policy Agent (OPA) policies

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

The Open Policy Agent (OPA) HTTP middleware applies OPA Policies to incoming Dapr HTTP requests. This can be used to apply reusable authorization policies to app endpoints.

Component format

apiVersion: dapr.io/v1alpha1
kind: Component
metadata:
 name: my-policy
spec:
 type: middleware.http.opa
 version: v1
 metadata:
 # `includedHeaders` is a comma-separated set of case-insensitive headers to include in the request input.
 # Request headers are not passed to the policy by default. Include to receive incoming request headers in
 # the input
 - name: includedHeaders
 value: "x-my-custom-header, x-jwt-header"

 # `defaultStatus` is the status code to return for denied responses
 - name: defaultStatus
 value: 403

 # `readBody` controls whether the middleware reads the entire request body in-memory and make it
 # available for policy decisions.
 - name: readBody
 value: "false"

 # `rego` is the open policy agent policy to evaluate. required
 # The policy package must be http and the policy must set data.http.allow
 - name: rego
 value: |
 package http

 default allow = true

 # Allow may also be an object and include other properties

 # For example, if you wanted to redirect on a policy failure, you could set the status code to 301 and set the location header on the response:
 allow = {
 "status_code": 301,
 "additional_headers": {
 "location": "https://my.site/authorize"
 }
 } {
 not jwt.payload["my-claim"]
 }

 # You can also allow the request and add additional headers to it:
 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)
 }

You can prototype and experiment with policies using the official OPA playground. For example, you can find the example policy above here.

Rate limiting

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

The rate limit HTTP middleware allows restricting the maximum number of allowed HTTP requests per second. Rate limiting can protect your application from Denial of Service (DoS) attacks. DoS attacks can be initiated by malicious 3rd parties but also by bugs in your software (a.k.a. a “friendly fire” DoS attack).

Component format

In the following definition, the maximum requests per second are set to 10:

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

Spec metadata fields

Field	Details	Example
`maxRequestsPerSecond`	The maximum requests per second by remote IP. The component looks at the `X-Forwarded-For` and `X-Real-IP` headers to determine the caller’s IP.	`10`

Once the limit is reached, the requests will fail with HTTP Status code 429: Too Many Requests.

Router alias http request routing

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

The router alias HTTP middleware component allows you to convert arbitrary HTTP routes arriving into Dapr to valid Dapr API endpoints.

Component format

apiVersion: dapr.io/v1alpha1
kind: Component
metadata:
 name: routeralias 
spec:
 type: middleware.http.routeralias
 version: v1
 metadata:
 # String containing a JSON-encoded or YAML-encoded dictionary
 # Each key in the dictionary is the incoming path, and the value is the path it's converted to
 - 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"
 }

In the example above, an incoming HTTP request for /mall/activity/info?id=123 is transformed into /v1.0/invoke/srv.default/method/mall/activity/info?id=123.

RouterChecker http request routing

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

The RouterChecker HTTP middleware component leverages regexp to check the validity of HTTP request routing to prevent invalid routers from entering the Dapr cluster. In turn, the RouterChecker component filters out bad requests and reduces noise in the telemetry and log data.

Component format

The RouterChecker applies a set of rules to the incoming HTTP request. You define these rules in the component metadata using regular expressions. In the following example, the HTTP request RouterChecker is set to validate all requests message against the ^[A-Za-z0-9/._-]+$: regex.

Sentinel fault-tolerance middleware component

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

Sentinel is a powerful fault-tolerance component that takes “flow” as the breakthrough point and covers multiple fields including flow control, traffic shaping, concurrency limiting, circuit breaking, and adaptive system protection to guarantee the reliability and resiliency of microservices.

The Sentinel HTTP middleware enables Dapr to facilitate Sentinel’s powerful abilities to protect your application. You can refer to Sentinel Wiki for more details on Sentinel.

Component format

In the following definition, the maximum requests per second are set to 10:

Uppercase request body

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

The uppercase HTTP middleware converts the body of the request to uppercase letters and is used for testing that the pipeline is functioning. It should only be used for local development.

Component format

In the following definition, it make content of request body into uppercase:

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

This component has no metadata to configure.

Dapr configuration

To be applied, the middleware must be referenced in configuration. See middleware pipelines.

Wasm

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

WebAssembly is a way to safely run code compiled in other languages. Runtimes execute WebAssembly Modules (Wasm), which are most often binaries with a .wasm extension.

The Wasm HTTP middleware allows you to manipulate an incoming request or serve a response with custom logic compiled to a Wasm binary. In other words, you can extend Dapr using external files that are not pre-compiled into the daprd binary. Dapr embeds wazero to accomplish this without CGO.

Middleware component specs on Dapr Docs

Bearer

Component format

Spec metadata fields

OAuth2

Component format

Warning

Spec metadata fields

Dapr configuration

OAuth2 client credentials

Component format

Warning

Spec metadata fields

Possible values for authStyle

Dapr configuration

Apply Open Policy Agent (OPA) policies

Component format

Rate limiting

Component format

Spec metadata fields

Router alias http request routing

Component format

RouterChecker http request routing

Component format

Sentinel fault-tolerance middleware component

Component format

Uppercase request body

Component format

Dapr configuration

Wasm

Possible values for `authStyle`