Skip to main content

JWT-SVID Customization

Defakto allows customization of JWT-SVIDs on a per-cluster basis, including TTL and additional claims beyond the standard SPIFFE claims (sub, aud, exp).

JWT-SVID TTL​

Set a custom JWT-SVID TTL using the SVIDIssuancePolicy managed configuration:

section: SVIDIssuancePolicy
schema: v1
spec:
  policy:
    pathTemplate: "/{{cluster.name}}/ns/{{kubernetes.pod.namespace}}/sa/{{kubernetes.pod.service_account}}"
    jwt:
      ttl: "12h"

Apply it with spirlctl:

spirlctl config set cluster --id <cluster-id> svid-issuance-policy.yaml

Or with Terraform:

resource "spirl_cluster_config" "example" {
  cluster_id = spirl_cluster.my_cluster.id
  sections = {
    SVIDIssuancePolicy = <<-YAML
      section: SVIDIssuancePolicy
      schema: v1
      spec:
        policy:
          pathTemplate: "/{{cluster.name}}/ns/{{kubernetes.pod.namespace}}/sa/{{kubernetes.pod.service_account}}"
          jwt:
            ttl: "12h"
    YAML
  }
}

The jwt.ttl field accepts a duration between 1h and 168h. When an SVIDIssuancePolicy sets jwt.ttl, it is authoritative — the per-deployment CLI defaults are no longer consulted as fallbacks.

To apply different JWT TTLs to specific workloads within the same cluster, use per-workload overrides.

Custom Claims​

tip

This feature is only available with spirl-server version 0.36.0 and beyond

Add additional claims to JWT-SVIDs using a customization template in the SVIDIssuancePolicy managed configuration. Custom claims appear alongside the standard JWT-SVID claims. Custom claims cannot override the registered JWT claims (iss, sub, aud, exp, nbf, iat, jti).

section: SVIDIssuancePolicy
schema: v1
spec:
  policy:
    pathTemplate: "/{{cluster.name}}/ns/{{kubernetes.pod.namespace}}/sa/{{kubernetes.pod.service_account}}"
    jwt:
      additionalClaims: 
        namespace: "{{kubernetes.pod.namespace}}"
        pod_service_account: "{{kubernetes.pod.service_account}}"

Apply it with spirlctl:

spirlctl config set cluster --id <cluster-id> svid-issuance-policy.yaml

Or with Terraform:

resource "spirl_cluster_config" "example" {
  cluster_id = spirl_cluster.my_cluster.id
  sections = {
    SVIDIssuancePolicy = <<-YAML
      section: SVIDIssuancePolicy
      schema: v1
      spec:
        policy:
          pathTemplate: "/{{cluster.name}}/ns/{{kubernetes.pod.namespace}}/sa/{{kubernetes.pod.service_account}}"
          jwt:
            additionalClaims: 
              namespace: {{kubernetes.pod.namespace}}
              pod_service_account: {{kubernetes.pod.service_account}}
    YAML
  }
}

When an SVIDIssuancePolicy is configured for a cluster, the policy's jwt.additionalClaims is authoritative. The per-cluster legacy template is no longer consulted as a fallback, even if the policy omits additionalClaims. See Legacy configuration for migration guidance.

To apply different claims to specific workloads within the same cluster, use per-workload overrides.

Template Format​

The customization template is a list of templated strings that define additional custom claims to be added to JWT-SVIDs. Each claim follows the format claim_name: {{attribute}}:

additionalClaims:
  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:

additionalClaims:
  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.

Legacy configuration​

Custom JWT claims can also be set using the spirlctl CLI. If jwt.additionalClaims is configured for an SVIDIssuancePolicy that matches the JWT-SVID being created, the legacy template is suppressed. To migrate, add jwt.additionalClaims to the policy with the same claims as the template. For example, for a template like namespace={{kubernetes.pod.namespace}},service_account={{kubernetes.pod.service_account}}, the equivalent configuration would be:

additionalClaims:
  namespace: {{kubernetes.pod.namespace}}
  service_account: {{kubernetes.pod.service_account}}

Setting the Claims 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}}"

Setting the Claims Template 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 Claims 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 ""