From bcb939c78ee1eee27651abab97c5397cc621e25c Mon Sep 17 00:00:00 2001 From: Nelson Parente Date: Thu, 28 Aug 2025 17:58:11 +0100 Subject: [PATCH] doc: oauth middleware pathFilter (#4745) * doc: oauth middleware pathFilter Signed-off-by: nelson.parente * doc: add section for path filter with examples Signed-off-by: nelson.parente * Update daprdocs/content/en/reference/components-reference/supported-middleware/middleware-oauth2.md Co-authored-by: Alice Gibbons Signed-off-by: Mark Fussell * Update daprdocs/content/en/reference/components-reference/supported-middleware/middleware-oauth2.md Co-authored-by: Alice Gibbons Signed-off-by: Mark Fussell * Update daprdocs/content/en/reference/components-reference/supported-middleware/middleware-oauth2.md Co-authored-by: Alice Gibbons Signed-off-by: Mark Fussell * Update daprdocs/content/en/reference/components-reference/supported-middleware/middleware-oauth2.md Co-authored-by: Alice Gibbons Signed-off-by: Mark Fussell * Update daprdocs/content/en/reference/components-reference/supported-middleware/middleware-oauth2.md Co-authored-by: Alice Gibbons Signed-off-by: Mark Fussell * Update daprdocs/content/en/reference/components-reference/supported-middleware/middleware-oauth2.md Co-authored-by: Alice Gibbons Signed-off-by: Mark Fussell * Update daprdocs/content/en/reference/components-reference/supported-middleware/middleware-oauth2clientcredentials.md Co-authored-by: Alice Gibbons Signed-off-by: Mark Fussell * Update daprdocs/content/en/reference/components-reference/supported-middleware/middleware-oauth2clientcredentials.md Co-authored-by: Alice Gibbons Signed-off-by: Mark Fussell * Update daprdocs/content/en/reference/components-reference/supported-middleware/middleware-oauth2clientcredentials.md Co-authored-by: Alice Gibbons Signed-off-by: Mark Fussell * Update daprdocs/content/en/reference/components-reference/supported-middleware/middleware-oauth2clientcredentials.md Co-authored-by: Alice Gibbons Signed-off-by: Mark Fussell * Update daprdocs/content/en/reference/components-reference/supported-middleware/middleware-oauth2clientcredentials.md Co-authored-by: Alice Gibbons Signed-off-by: Mark Fussell * Update daprdocs/content/en/reference/components-reference/supported-middleware/middleware-oauth2clientcredentials.md Co-authored-by: Alice Gibbons Signed-off-by: Mark Fussell * Update daprdocs/content/en/reference/components-reference/supported-middleware/middleware-oauth2clientcredentials.md Co-authored-by: Alice Gibbons Signed-off-by: Mark Fussell * Update daprdocs/content/en/reference/components-reference/supported-middleware/middleware-oauth2clientcredentials.md Co-authored-by: Alice Gibbons Signed-off-by: Mark Fussell * Update daprdocs/content/en/reference/components-reference/supported-middleware/middleware-oauth2clientcredentials.md Co-authored-by: Alice Gibbons Signed-off-by: Mark Fussell * Update daprdocs/content/en/reference/components-reference/supported-middleware/middleware-oauth2clientcredentials.md Co-authored-by: Alice Gibbons Signed-off-by: Mark Fussell * Update daprdocs/content/en/reference/components-reference/supported-middleware/middleware-oauth2.md Co-authored-by: Alice Gibbons Signed-off-by: Mark Fussell * Update daprdocs/content/en/reference/components-reference/supported-middleware/middleware-oauth2.md Co-authored-by: Alice Gibbons Signed-off-by: Mark Fussell * Update daprdocs/content/en/reference/components-reference/supported-middleware/middleware-oauth2.md Co-authored-by: Alice Gibbons Signed-off-by: Mark Fussell * Update daprdocs/content/en/reference/components-reference/supported-middleware/middleware-oauth2.md Co-authored-by: Alice Gibbons Signed-off-by: Mark Fussell --------- Signed-off-by: nelson.parente Signed-off-by: Mark Fussell Co-authored-by: Marc Duiker Co-authored-by: Mark Fussell Co-authored-by: Alice Gibbons --- .../supported-middleware/middleware-oauth2.md | 64 +++++++++++++++++++ .../middleware-oauth2clientcredentials.md | 60 +++++++++++++++++ 2 files changed, 124 insertions(+) diff --git a/daprdocs/content/en/reference/components-reference/supported-middleware/middleware-oauth2.md b/daprdocs/content/en/reference/components-reference/supported-middleware/middleware-oauth2.md index 3ce811359..63e0801b9 100644 --- a/daprdocs/content/en/reference/components-reference/supported-middleware/middleware-oauth2.md +++ b/daprdocs/content/en/reference/components-reference/supported-middleware/middleware-oauth2.md @@ -36,6 +36,8 @@ spec: value: "authorization" - name: forceHTTPS value: "false" + - name: pathFilter + value: ".*/users/.*" ``` {{% alert title="Warning" color="warning" %}} @@ -54,6 +56,7 @@ The above example uses secrets as plain strings. It is recommended to use a secr | 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 @@ -71,6 +74,67 @@ spec: 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. +```yaml +# 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: "" + - name: clientSecret + value: "" + - 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: "" + - name: clientSecret + value: "" + - 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/.*" +``` + + ## Related links - [Configure API authorization with OAuth]({{% ref oauth %}}) diff --git a/daprdocs/content/en/reference/components-reference/supported-middleware/middleware-oauth2clientcredentials.md b/daprdocs/content/en/reference/components-reference/supported-middleware/middleware-oauth2clientcredentials.md index 1ea9d1246..a361db3b7 100644 --- a/daprdocs/content/en/reference/components-reference/supported-middleware/middleware-oauth2clientcredentials.md +++ b/daprdocs/content/en/reference/components-reference/supported-middleware/middleware-oauth2clientcredentials.md @@ -30,6 +30,8 @@ spec: value: "https://accounts.google.com/o/oauth2/token" - name: headerName value: "authorization" + - name: pathFilter + value: ".*/users/.*" ``` {{% alert title="Warning" color="warning" %}} @@ -47,6 +49,7 @@ The above example uses secrets as plain strings. It is recommended to use a secr | 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` @@ -72,6 +75,63 @@ spec: type: middleware.http.oauth2clientcredentials ``` +## 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. +```yaml +# User with read-only access scope +apiVersion: dapr.io/v1alpha1 +kind: Component +metadata: + name: oauth2clientcredentials-users +spec: + type: middleware.http.oauth2clientcredentials + version: v1 + metadata: + - name: clientId + value: "" + - name: clientSecret + value: "" + - name: scopes + value: "user:read profile:read" + - name: tokenURL + value: "https://accounts.google.com/o/oauth2/token" + - name: headerName + value: "authorization" + - name: pathFilter + value: "^/api/users/.*" +--- +# User with full admin access scope +apiVersion: dapr.io/v1alpha1 +kind: Component +metadata: + name: oauth2clientcredentials-admin +spec: + type: middleware.http.oauth2clientcredentials + version: v1 + metadata: + - name: clientId + value: "" + - name: clientSecret + value: "" + - name: scopes + value: "admin:read admin:write user:read user:write" + - name: tokenURL + value: "https://accounts.google.com/o/oauth2/token" + - name: headerName + value: "authorization" + - name: pathFilter + value: "^/api/admin/.*" +``` + + ## Related links - [Middleware]({{% ref middleware.md %}}) - [Configuration concept]({{% ref configuration-concept.md %}})