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)