Skip to main content

JWT SVID Custom Claims

SPIRL allows customization of JWT SVID claims on a per-cluster basis. This feature enables you to include additional claims in JWT SVIDs beyond the standard SPIFFE claims, allowing for more granular authorization and policy decisions in your applications.

Similar to X.509 customization, you can set a JWT customization template that will be applied when a JWT SVID is minted. The custom claims are added to the standard JWT SVID claims such as sub (subject, which is the SPIFFE ID), aud (audience), and exp (expiration). Custom claims cannot override public claims.

Template Format​

The customization template is a comma-separated string that defines custom claims to be added to JWT SVIDs. Each claim follows the format claim_name={{attribute}}:

claim_name={{discovered.attribute}},another_claim={{another.attribute}}

Claim Names and Values​

  • Claim names: Custom names that you choose.
  • Claim values: Must reference discovered attributes available in the cluster platform.

Example​

Include claims based on attributes, similar to how they are used in path templates:

namespace={{kubernetes.pod.namespace}},pod_service_account={{kubernetes.pod.service_account}}

Restrictions​

  • Static values are not allowed: Claim values must reference dynamic attributes discovered from the cluster platform. This ensures claims remain current and reflect the actual workload context.
  • Attribute validation: All referenced attributes must exist and be discoverable in the target cluster.

Setting the Template​

For a New Cluster​

By default, clusters have an empty JWT customization template. You can set a template when adding a cluster to the trust domain:

spirlctl cluster add production --trust-domain spirl.example.com \
    --platform k8s \
    --jwt-customization-template "namespace={{kubernetes.pod.namespace}},pod_service_account={{kubernetes.pod.service_account}}"

For an Existing Cluster​

To set or update the JWT customization template for an existing cluster, use the change-jwt-template subcommand:

spirlctl cluster config --trust-domain spirl.example.com \
    change-jwt-template ClusterName "namespace={{kubernetes.pod.namespace}},pod_service_account={{kubernetes.pod.service_account}}"

Removing the Template​

To remove the customization template from a cluster, set it to an empty string:

spirlctl cluster config --trust-domain spirl.example.com \
    change-jwt-template ClusterName ""