OAuth2

Use OAuth2 middleware to secure HTTP endpoints

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.

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

Request path filtering

The pathFilter field allows you to selectively apply OAuth2 authentication based on the HTTP request path using a regex pattern. This enables scenarios such as configuring multiple OAuth2 middlewares with different scopes for different API endpoints, implementing the least privilege principle by ensuring users only receive the minimum permissions necessary for their intended operation.

Example: Separate read-only and admin user access

In the following configuration:

Requests to /api/users/* endpoints receive tokens with a read-only user scopes
Requests to /api/admin/* endpoints receive tokens with full admin scopes

This reduces security risk by preventing unnecessary privilege access and limiting the blast radius of compromised tokens.

# User with read-only access scope
apiVersion: dapr.io/v1alpha1
kind: Component
metadata:
  name: oauth2-users
spec:
  type: middleware.http.oauth2
  version: v1
  metadata:
  - name: clientId
    value: "<your client ID>"
  - name: clientSecret
    value: "<your client secret>"
  - name: scopes
    value: "user:read profile:read"
  - 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://myapp.com/callback"
  - name: pathFilter
    value: "^/api/users/.*"
---
# User with full admin access scope
apiVersion: dapr.io/v1alpha1
kind: Component
metadata:
  name: oauth2-admin
spec:
  type: middleware.http.oauth2
  version: v1
  metadata:
  - name: clientId
    value: "<your client ID>"
  - name: clientSecret
    value: "<your client secret>"
  - name: scopes
    value: "admin:read admin:write user:read user:write"
  - 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://myapp.com/callback"
  - name: pathFilter
    value: "^/api/admin/.*"

Last modified August 28, 2025: doc: oauth middleware pathFilter (#4745) (bcb939c7)