JSON Web Key Sets (JWKS)

Detailed information on the JWKS cryptography component

Component format

The purpose of this component is to load keys from a JSON Web Key Set (RFC 7517). These are JSON documents that contain 1 or more keys as JWK (JSON Web Key); they can be public, private, or shared keys.

This component supports loading a JWKS:

  • From a local file; in this case, Dapr watches for changes to the file on disk and reloads it automatically.
  • From a HTTP(S) URL, which is periodically refreshed.
  • By passing the actual JWKS in the jwks metadata property, as a string (optionally, base64-encoded).

Note

This component uses the cryptographic engine in Dapr to perform operations. Although keys are never exposed to your application, Dapr has access to the raw key material.

A Dapr crypto.yaml component file has the following structure:

  1. apiVersion: dapr.io/v1alpha1
  2. kind: Component
  3. metadata:
  4. name: jwks
  5. spec:
  6. type: crypto.dapr.jwks
  7. version: v1
  8. metadata:
  9. # Example 1: load JWKS from file
  10. - name: "jwks"
  11. value: "fixtures/crypto/jwks/jwks.json"
  12. # Example 2: load JWKS from a HTTP(S) URL
  13. # Only "jwks" is required
  14. - name: "jwks"
  15. value: "https://example.com/.well-known/jwks.json"
  16. - name: "requestTimeout"
  17. value: "30s"
  18. - name: "minRefreshInterval"
  19. value: "10m"
  20. # Option 3: include the actual JWKS
  21. - name: "jwks"
  22. value: |
  23. {
  24. "keys": [
  25. {
  26. "kty": "RSA",
  27. "use": "sig",
  28. "kid": "…",
  29. "n": "…",
  30. "e": "…",
  31. "issuer": "https://example.com"
  32. }
  33. ]
  34. }
  35. # Option 3b: include the JWKS base64-encoded
  36. - name: "jwks"
  37. value: |
  38. eyJrZXlzIjpbeyJ

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

FieldRequiredDetailsExample
jwksYPath to the JWKS documentLocal file: “fixtures/crypto/jwks/jwks.json”
HTTP(S) URL: https://example.com/.well-known/jwks.json
Embedded JWKS: {“keys”: […]} (can be base64-encoded)
requestTimeoutNTimeout for network requests when fetching the JWKS document from a HTTP(S) URL, as a Go duration. Default: “30s”“5s”
minRefreshIntervalNMinimum interval to wait before subsequent refreshes of the JWKS document from a HTTP(S) source, as a Go duration. Default: “10m”“1h”

Cryptography building block

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