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​

You can include additional claims in JWT-SVIDs using a customization template that is applied using the legacy configuration method. Custom claims are added alongside the standard JWT-SVID claims. Custom claims cannot override the registered JWT claims (iss, sub, aud, exp, nbf, iat, jti).

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.
info

SVIDIssuancePolicy does not currently express additional JWT claims. When you need custom claims alongside a policy-managed TTL, configure them using the legacy customization template below. The JWTCustomizationTemplate claims are applied alongside the policy's TTL.

Legacy configuration​

You can also set custom JWT claims using the spirlctl CLI. When both are configured, SVIDIssuancePolicy takes precedence.

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