Skip to main content

JWT-SVID Customization

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 ""