Workload Identity: SPIFFE SVIDs for Workload Authentication

Teleport Workload Identity issues short-lived cryptographic identities to workloads — services, Kubernetes pods, and other processes — in a format compatible with the SPIFFE (Secure Production Identity Framework For Everyone) standard. These identities, called SVIDs (SPIFFE Verifiable Identity Documents), allow workloads to authenticate to each other and to external APIs without relying on static credentials. Unlike the Zero Trust Access feature of Machine Identity, which routes traffic through the Teleport Proxy, Workload Identity identities are used directly between workloads. Teleport acts as the certificate authority and policy engine, but the communication itself is workload-to-workload.

How it works

Teleport Workload Identity establishes a root certificate authority within your Teleport cluster. This CA issues short-lived X.509 certificates and JWT tokens that carry a SPIFFE ID — a URI that uniquely identifies the workload within your trust domain. A SPIFFE ID looks like:

spiffe://example.teleport.sh/region/us-east/svc/payments-processor

The tbot agent runs in proximity to your workloads. It authenticates to the Teleport cluster using a supported join method and then either:

Writes SVID files (certificate, private key, and trust bundle) to a directory or Kubernetes Secret for the workload to read, or
Exposes a SPIFFE Workload API — a standardized gRPC socket that workloads connect to in order to receive SVIDs and trust bundles automatically. This is the approach used by SPIFFE SDKs and service meshes like Envoy and Istio.

When using the Workload API, tbot can perform Workload Attestation — verifying properties of the process requesting an SVID (such as its Unix UID/GID or Kubernetes pod labels) before issuing credentials. This eliminates the need for a bootstrapping secret within the workload itself. Workload Identity overview diagram

SPIFFE concepts

SPIFFE IDs and trust domains

Every workload identity is encoded as a SPIFFE ID — a URI of the form:

spiffe://<trust-domain>/<workload-path>

The trust domain is the root of trust for your workload identities. In Teleport, the trust domain is your cluster name (e.g. example.teleport.sh). The workload path is a hierarchical string you define to identify the workload. Common structuring strategies:

Logical — based on service name and team: spiffe://example.teleport.sh/svc/payments/processor
Physical — based on location: spiffe://example.teleport.sh/eu/uk/london/vm-a3847f
Hybrid — using namespace prefixes: spiffe://example.teleport.sh/svc/payments and spiffe://example.teleport.sh/phy/london/vm-a3847f

Avoid encoding sensitive information in SPIFFE IDs. They are not secret — they are visible to any workload that connects to or receives connections from the workload that holds them.

SVIDs: X.509 and JWT

SPIFFE defines two SVID formats:

X.509-SVID — An X.509 certificate with the SPIFFE ID in the URI Subject Alternative Name (URI SAN) field. Used for mutual TLS (mTLS) between workloads.
JWT-SVID — A signed JSON Web Token with the SPIFFE ID in the sub claim. Used for authenticating to APIs, including cloud provider identity federation endpoints (AWS, GCP, Azure).

Both types are short-lived and automatically renewed by tbot.

Configuring Workload Identity

Step 1: Create a WorkloadIdentity resource

The workload_identity resource defines the SPIFFE ID and any attestation rules for a workload. Create a file called workload-identity.yaml:

kind: workload_identity
version: v1
metadata:
  name: payments-processor
  labels:
    team: payments
    env: production
spec:
  spiffe:
    id: /svc/payments/processor

Apply it:

tctl create -f workload-identity.yaml

To include a DNS SAN in the issued X.509 certificate (useful for non-SPIFFE-aware clients):

spec:
  spiffe:
    id: /svc/payments/processor
    x509:
      dns_sans:
        - payments-processor.internal.example.com

Step 2: Grant a bot access to issue SVIDs

Create a role that allows the bot to request SVIDs for the workload identity you created:

kind: role
version: v6
metadata:
  name: payments-svid-issuer
spec:
  allow:
    workload_identity_labels:
      team: [payments]
      env: [production]
    rules:
      - resources:
          - workload_identity
        verbs:
          - list
          - read

Apply the role and assign it to the bot:

tctl create -f role.yaml
tctl bots update my-bot --add-roles payments-svid-issuer

Step 3: Configure tbot to expose the Workload API

Add the workload-identity-api service to your tbot.yaml to expose a SPIFFE Workload API socket:

version: v2
proxy_server: example.teleport.sh:443
onboarding:
  join_method: kubernetes
  token: my-bot-token
storage:
  type: memory
services:
  - type: workload-identity-api
    listen: unix:///opt/machine-id/workload.sock
    selector:
      name: payments-processor

The socket at /opt/machine-id/workload.sock will serve SPIFFE SVIDs to any process that connects to it. Restrict the socket’s permissions so that only your workload process can read it. Reload tbot to apply the new configuration:

sudo systemctl reload tbot

Step 4: Connect your workload to the Workload API

Configure your workload to use the socket. If you are using a SPIFFE SDK, set the environment variable:

export SPIFFE_ENDPOINT_SOCKET=unix:///opt/machine-id/workload.sock

SPIFFE SDKs are available for Go, Java, Python, C/C++, and Rust. Alternatively, write SVIDs directly to disk using the workload-identity-x509 output service:

services:
  - type: workload-identity-x509
    destination:
      type: directory
      path: /opt/machine-id/svid
    selector:
      name: payments-processor

This writes svid.pem, svid_key.pem, and ca.pem (trust bundle) to the directory. Long-running workloads must watch these files and reload them on change to handle renewals.

Workload Attestation

Workload Attestation allows tbot to restrict which processes can receive an SVID based on characteristics of the requesting process. This eliminates the need for any bootstrapping secret inside the workload.

Unix attestation

When using a Unix domain socket listener, tbot can attest workloads based on:

Attribute	Description
`workload.unix.uid`	The UID of the user running the process
`workload.unix.gid`	The primary GID of the user running the process
`workload.unix.pid`	The PID of the process

Add attestation rules to your workload_identity resource:

kind: workload_identity
version: v1
metadata:
  name: payments-processor
  labels:
    team: payments
spec:
  rules:
    allow:
      - conditions:
          - attribute: workload.unix.uid
            eq:
              value: 1000
      - conditions:
          - attribute: workload.unix.gid
            eq:
              value: 2000
  spiffe:
    id: /svc/payments/processor

Each conditions block is a separate rule. At least one rule must pass for the SVID to be issued. Within a single conditions block, all conditions must pass.

Testing with tbot spiffe-inspect

Before connecting your actual workload, verify the Workload API is working correctly:

tbot spiffe-inspect --path unix:///opt/machine-id/workload.sock

Expected output:

INFO [TBOT]  Inspecting SPIFFE Workload API Endpoint unix:///opt/machine-id/workload.sock
INFO [TBOT]  Received X.509 SVID context from Workload API bundles_count:1 svids_count:1
SVIDS
- spiffe://example.teleport.sh/svc/payments/processor
  - Expiry: 2024-03-20 10:55:52 +0000 UTC
Trust Bundles
- example.teleport.sh

Integration with Envoy and service meshes

tbot’s Workload API is compatible with the Envoy Secret Discovery Service (SDS) protocol. Envoy can be configured to fetch mTLS certificates from the tbot socket, enabling transparent mTLS between services without modifying application code. Any service mesh or sidecar that supports the SPIFFE Workload API (including Linkerd and Istio integrations via the SPIFFE CSI driver) can use tbot as its SVID source.

Cloud provider federation

JWT SVIDs issued by Teleport Workload Identity can authenticate to AWS, GCP, and Azure through their respective identity federation mechanisms:

AWS OIDC Federation — Use JWT SVIDs with AWS’s OIDC identity provider
AWS Roles Anywhere — Use X.509 SVIDs with AWS Roles Anywhere
GCP Workload Identity Federation — Use JWT SVIDs with GCP’s identity federation
Azure Federated Credentials — Use JWT SVIDs with Azure AD federated identity credentials

In each case, the cloud provider is configured to trust Teleport’s CA, and the SVID’s SPIFFE ID is mapped to a cloud IAM role or service account. No cloud credentials are ever stored in Teleport or on the workload host.

Next steps

Getting Started

Issue your first bot certificate and access a server or Kubernetes cluster from CI/CD.

tbot Reference

Full tbot configuration reference including all service types and output destinations.

RBAC

Use roles and label matchers to control which workloads can receive which SVIDs.

tctl Reference

Manage bots, tokens, and workload identity resources from the command line.

Get Started

Enroll Resources

Access Controls

Machine & Workload Identity

Deployment & Operations

Workload Identity: SPIFFE SVIDs for Workload Authentication

How it works

SPIFFE concepts

SPIFFE IDs and trust domains

SVIDs: X.509 and JWT

Configuring Workload Identity

Step 1: Create a WorkloadIdentity resource

Step 2: Grant a bot access to issue SVIDs

Step 3: Configure tbot to expose the Workload API

Step 4: Connect your workload to the Workload API

Workload Attestation

Unix attestation

Testing with tbot spiffe-inspect

Integration with Envoy and service meshes

Cloud provider federation

Next steps

Getting Started

tbot Reference

RBAC

tctl Reference

Build docs developers (and LLMs) love

Get Started

Enroll Resources

Access Controls

Machine & Workload Identity

Deployment & Operations

Documentation Index

​How it works

​SPIFFE concepts

​SPIFFE IDs and trust domains

​SVIDs: X.509 and JWT

​Configuring Workload Identity

​Step 1: Create a WorkloadIdentity resource

​Step 2: Grant a bot access to issue SVIDs

​Step 3: Configure tbot to expose the Workload API

​Step 4: Connect your workload to the Workload API

​Workload Attestation

​Unix attestation

​Testing with tbot spiffe-inspect

​Integration with Envoy and service meshes

​Cloud provider federation

​Next steps

Getting Started

tbot Reference

RBAC

tctl Reference

Build docs developers (and LLMs) love

How it works

SPIFFE concepts

SPIFFE IDs and trust domains

SVIDs: X.509 and JWT

Configuring Workload Identity

Step 1: Create a WorkloadIdentity resource

Step 2: Grant a bot access to issue SVIDs

Step 3: Configure tbot to expose the Workload API

Step 4: Connect your workload to the Workload API

Workload Attestation

Unix attestation

Testing with tbot spiffe-inspect

Integration with Envoy and service meshes

Cloud provider federation

Next steps