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:

apiVersion: dapr.io/v1alpha1
kind: Component
metadata:
  name: jwks
spec:
  type: crypto.dapr.jwks
  version: v1
  metadata:
    # Example 1: load JWKS from file
    - name: "jwks"
      value: "fixtures/crypto/jwks/jwks.json"
    # Example 2: load JWKS from a HTTP(S) URL
    # Only "jwks" is required
    - name: "jwks"
      value: "https://example.com/.well-known/jwks.json"
    - name: "requestTimeout"
      value: "30s"
    - name: "minRefreshInterval"
      value: "10m"
    # Option 3: include the actual JWKS
    - name: "jwks"
      value: |
        {
          "keys": [
            {
              "kty": "RSA",
              "use": "sig",
              "kid": "…",
              "n": "…",
              "e": "…",
              "issuer": "https://example.com"
            }
          ]
        }        
    # Option 3b: include the JWKS base64-encoded
    - name: "jwks"
      value: |
                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

Field	Required	Details	Example
`jwks`	Y	Path to the JWKS document	Local file: `"fixtures/crypto/jwks/jwks.json"` HTTP(S) URL: `"https://example.com/.well-known/jwks.json"` Embedded JWKS: `{"keys": […]}` (can be base64-encoded)
`requestTimeout`	N	Timeout for network requests when fetching the JWKS document from a HTTP(S) URL, as a Go duration. Default: “30s”	`"5s"`
`minRefreshInterval`	N	Minimum 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

Feedback

Was this page helpful?

Glad to hear it! Please tell us how we can improve.

Sorry to hear that. Please tell us how we can improve.

Last modified November 19, 2024: Merge pull request #4407 from hhunter-ms/issue_3321 (1d418a4)