Skip to main content

Kubernetes Service Account Token

The Kubernetes Service Account Token method authenticates agents running in a Kubernetes cluster by verifying the agent's service account token. The agent sends its token to the Trust Domain Server; the server verifies it against the cluster's OIDC issuer.

This is the simplest agent attestation method for Kubernetes-hosted agents.

Attributes available for SVID issuance​

The k8s_token agent attestor does not emit any attributes. Agent identity is established by verifying the service account token, but no token claims are exposed for use in path templates or other SVID customization.

To reference Kubernetes attributes of the workload requesting an SVID (pod name, namespace, service account, labels, annotations, etc.), see the Kubernetes workload attestor. Agent-side attributes such as cluster or node identity can be added by combining k8s_token with another attestor — for example, aws_iid on EKS.

How to Deploy​

Step 1 — Update cluster configuration​

Create an AgentAttestation policy for the cluster, specifying the OIDC issuer URL for the Kubernetes cluster where agents will run. The issuer URL must be reachable from the Trust Domain Server.

section: AgentAttestation
schema: v1
spec:
  policies:
    - name: k8s_policy
      requiredAttestors:
        - type: k8s_token
          config:
            issuerURL: https://oidc.eks.us-east-1.amazonaws.com/id/ABCDEF123456

Apply it:

spirlctl config set cluster --id <cluster-id> attestation-policy.yaml

Configuration Reference​

FieldRequiredDescription
issuerURLYesOIDC issuer URL for the Kubernetes cluster. The Trust Domain Server fetches signing keys from this endpoint.

Step 2 — Configure the Agent​

No additional agent configuration is needed. When k8s_token is listed as an attestation method, the agent automatically requests a service account token from Kubernetes and sends it to the server at login.

In Helm values:

agent:
  auth:
    clusterId: c-xxxxxx
    attestors:
      - type: k8s_token

Security Considerations​

  • The OIDC issuer endpoint must be accessible from the Trust Domain Server's network. Ensure any firewall or network policy allows outbound HTTPS from the Trust Domain Server to the issuer URL.
  • Service account tokens expire. Kubernetes automatically rotates them; agents re-authenticate as needed.
  • Service account tokens alone do not constrain which node or namespace an agent runs in. For finer-grained control — for example, limiting agents to a specific namespace or service account — add a second attestation method (such as aws_iid) that enforces additional constraints.

Troubleshooting​

failed to fetch signing key — The Trust Domain Server cannot reach the OIDC issuer URL. Verify network connectivity from the server to the configured issuerURL.

JWT verification failed — The token the agent presented was not verifiable. Check the error detail: common causes are an expired token, a mismatched issuer URL, or a token issued by a different cluster than the one configured.