Configure endpoint authorization with OAuth

Enable OAuth authorization on application endpoints for your web APIs

Dapr OAuth 2.0 middleware allows you to enable OAuth authorization on Dapr endpoints for your web APIs using the Authorization Code Grant flow. You can also inject authorization tokens into your endpoint APIs which can be used for authorization towards external APIs called by your APIs using the Client Credentials Grant flow. When the middleware is enabled any method invocation through Dapr needs to be authorized before getting passed to the user code.

The main difference between the two flows is that the Authorization Code Grant flow needs user interaction and authorizes a user where the Client Credentials Grant flow doesn’t need a user interaction and authorizes a service/application.

Register your application with an authorization server

Different authorization servers provide different application registration experiences. Here are some samples:

To configure the Dapr OAuth middleware, you’ll need to collect the following information:

  • Client ID (see here)
  • Client secret (see here)
  • Scopes (see here)
  • Authorization URL
  • Token URL

Authorization/Token URLs of some of the popular authorization servers:

ServerAuthorization URLToken URL
Microsoft Entra IDhttps://login.microsoftonline.com/{tenant}/oauth2/authorizehttps://login.microsoftonline.com/{tenant}/oauth2/token
GitHubhttps://github.com/login/oauth/authorizehttps://github.com/login/oauth/access_token
Googlehttps://accounts.google.com/o/oauth2/v2/authhttps://accounts.google.com/o/oauth2/token https://www.googleapis.com/oauth2/v4/token
Twitterhttps://api.twitter.com/oauth/authorizehttps://api.twitter.com/oauth2/token

Define the middleware component definition

Define an Authorization Code Grant component

An OAuth middleware (Authorization Code) is defined by a component:

  1. apiVersion: dapr.io/v1alpha1
  2. kind: Component
  3. metadata:
  4. name: oauth2
  5. namespace: default
  6. spec:
  7. type: middleware.http.oauth2
  8. version: v1
  9. metadata:
  10. - name: clientId
  11. value: "<your client ID>"
  12. - name: clientSecret
  13. value: "<your client secret>"
  14. - name: scopes
  15. value: "<comma-separated scope names>"
  16. - name: authURL
  17. value: "<authorization URL>"
  18. - name: tokenURL
  19. value: "<token exchange URL>"
  20. - name: redirectURL
  21. value: "<redirect URL>"
  22. - name: authHeaderName
  23. value: "<header name under which the secret token is saved>"
  24. # forceHTTPS:
  25. # This key is used to set HTTPS schema on redirect to your API method
  26. # after Dapr successfully received Access Token from Identity Provider.
  27. # By default, Dapr will use HTTP on this redirect.
  28. - name: forceHTTPS
  29. value: "<set to true if you invoke an API method through Dapr from https origin>"

Define a custom pipeline for an Authorization Code Grant

To use the OAuth middleware (Authorization Code), you should create a custom pipeline using Dapr configuration, as shown in the following sample:

  1. apiVersion: dapr.io/v1alpha1
  2. kind: Configuration
  3. metadata:
  4. name: pipeline
  5. namespace: default
  6. spec:
  7. httpPipeline:
  8. handlers:
  9. - name: oauth2
  10. type: middleware.http.oauth2

Define a Client Credentials Grant component

An OAuth (Client Credentials) middleware is defined by a component:

  1. apiVersion: dapr.io/v1alpha1
  2. kind: Component
  3. metadata:
  4. name: myComponent
  5. spec:
  6. type: middleware.http.oauth2clientcredentials
  7. version: v1
  8. metadata:
  9. - name: clientId
  10. value: "<your client ID>"
  11. - name: clientSecret
  12. value: "<your client secret>"
  13. - name: scopes
  14. value: "<comma-separated scope names>"
  15. - name: tokenURL
  16. value: "<token issuing URL>"
  17. - name: headerName
  18. value: "<header name under which the secret token is saved>"
  19. - name: endpointParamsQuery
  20. value: "<list of additional key=value settings separated by ampersands or semicolons forwarded to the token issuing service>"
  21. # authStyle:
  22. # "0" means to auto-detect which authentication
  23. # style the provider wants by trying both ways and caching
  24. # the successful way for the future.
  25. # "1" sends the "client_id" and "client_secret"
  26. # in the POST body as application/x-www-form-urlencoded parameters.
  27. # "2" sends the client_id and client_password
  28. # using HTTP Basic Authorization. This is an optional style
  29. # described in the OAuth2 RFC 6749 section 2.3.1.
  30. - name: authStyle
  31. value: "<see comment>"

Define a custom pipeline for a Client Credentials Grant

To use the OAuth middleware (Client Credentials), you should create a custom pipeline using Dapr configuration, as shown in the following sample:

  1. apiVersion: dapr.io/v1alpha1
  2. kind: Configuration
  3. metadata:
  4. name: pipeline
  5. namespace: default
  6. spec:
  7. httpPipeline:
  8. handlers:
  9. - name: myComponent
  10. type: middleware.http.oauth2clientcredentials

Apply the configuration

To apply the above configuration (regardless of grant type) to your Dapr sidecar, add a dapr.io/config annotation to your pod spec:

  1. apiVersion: apps/v1
  2. kind: Deployment
  3. ...
  4. spec:
  5. ...
  6. template:
  7. metadata:
  8. ...
  9. annotations:
  10. dapr.io/enabled: "true"
  11. ...
  12. dapr.io/config: "pipeline"
  13. ...

Accessing the access token

Authorization Code Grant

Once everything is in place, whenever a client tries to invoke an API method through Dapr sidecar (such as calling the v1.0/invoke/ endpoint), it will be redirected to the authorization’s consent page if an access token is not found. Otherwise, the access token is written to the authHeaderName header and made available to the app code.

Client Credentials Grant

Once everything is in place, whenever a client tries to invoke an API method through Dapr sidecar (such as calling the v1.0/invoke/ endpoint), it will retrieve a new access token if an existing valid one is not found. The access token is written to the headerName header and made available to the app code. In that way the app can forward the token in the authorization header in calls towards the external API requesting that token.

Last modified October 11, 2024: Fixed typo (#4389) (fe17926)