# How to Configure SPIFFE/SVID Workload Identity for Containerized Agents in Agent Governance Toolkit

> Configure SPIFFE SVID workload identity for containerized agents with the Agent Governance Toolkit. Learn how to secure your agents using short-lived X.509 certificates for mutual TLS verification.

- Repository: [Microsoft/agent-governance-toolkit](https://github.com/microsoft/agent-governance-toolkit)
- Tags: how-to-guide
- Published: 2026-05-29

---

**Agent Governance Toolkit uses the SPIFFE/SVID framework to issue short-lived X.509 certificates to containerized agents, enabling cryptographic identity verification via mutual TLS.**

The Agent Governance Toolkit (AGT) implements cryptographic identity for containerized workloads through the SPIFFE/SVID standard. This approach allows each agent to present a verifiable identity during mutual TLS handshakes, establishing zero-trust communication across the Agent Mesh. Configuring SPIFFE/SVID workload identity requires setting up the SPIRE infrastructure, enabling the Helm chart integration, and initializing the `SPIFFEClient` within your agent code.

## Architectural Overview

### SPIRE Agent Node Service

The SPIRE Agent runs on each host as a node-level service and issues short-lived X.509 SVIDs to workloads via a Unix domain socket. The default socket path is `/tmp/spire-agent/public/api.sock`.

When deploying AGT via Helm, enable SPIFFE support by setting `global.spiffe.enabled=true` and provide your trust domain via `global.spiffe.trustDomain`. The trust domain ensures all issued identities belong to the same cryptographic boundary (e.g., `agentmesh.local`).

### SPIFFE Integration Layer

The Python wrapper at [`agent-governance-python/agent-mesh/src/agentmesh/identity/spiffe.py`](https://github.com/microsoft/agent-governance-toolkit/blob/main/agent-governance-python/agent-mesh/src/agentmesh/identity/spiffe.py) implements the `SPIFFEClient` class. This client communicates with the local SPIRE socket to fetch X.509 SVIDs and associated SPIFFE IDs.

The client handles the protocol for requesting and receiving certificates, then exposes them to the Agent Mesh runtime for use in TLS handshakes.

### Agent Mesh Runtime Identity Store

The runtime receives SVIDs from `SPIFFEClient` and stores them in the agent's identity store. According to the **AGENTMESH‑IDENTITY‑TRUST‑1.0** specification, the runtime uses these certificates for all inbound and outbound mutual TLS connections when communicating with the governance gate, policy engine, or peer agents.

The SPIFFE ID follows the format `spiffe://{trust_domain}/agent/<agent_name>`, allowing precise identity-based authorization policies.

### Trust Store and Federation

All services share the root CA that SPIRE uses to sign SVIDs. The CA bundle mounts into containers from the SPIRE Agent volume, ensuring every verified identity belongs to the same trust domain.

This shared trust store enables **cross-cluster federation**, allowing SPIFFE IDs to be verified across organizational boundaries when properly federated.

## Configuration Steps

Follow these five steps to enable SPIFFE/SVID workload identity for your containerized agents:

1. **Enable SPIFFE in the Helm chart** – Set `global.spiffe.enabled=true` in your [`values.yaml`](https://github.com/microsoft/agent-governance-toolkit/blob/main/values.yaml) file.

2. **Define the trust domain** – Specify `global.spiffe.trustDomain=your-domain.example.com` to match your SPIRE deployment's configured domain.

3. **Deploy SPIRE** – Ensure each node runs a `spire-agent` exposing the Unix socket at `/tmp/spire-agent/public/api.sock`.

4. **Start the Agent Mesh container** – The container automatically mounts the SPIRE socket and root CA bundle when SPIFFE is enabled in the chart.

5. **Initialize SPIFFEClient** – Your agent code must instantiate `SPIFFEClient` and call `fetch_x509_svid()` to retrieve the workload identity.

## Implementation Example

The following Python example demonstrates how to obtain an X.509 SVID inside a containerized agent:

```python
from agentmesh.spiffe import SPIFFEClient

# The SPIRE socket is injected by the Helm chart at this path

spiffe = SPIFFEClient(socket_path="/tmp/spire-agent/public/api.sock")

# Fetch an X.509 SVID (async in the actual library)

svid = await spiffe.fetch_x509_svid()

print("SPIFFE ID:", svid.spiffe_id)   # e.g. spiffe://example.com/agent/my-agent

print("Certificate PEM:", svid.cert_pem)
print("Private key PEM:", svid.key_pem)

```

Configure your Helm deployment to enable automatic socket mounting:

```yaml
global:
  spiffe:
    enabled: true                 # turn on SPIFFE integration

    trustDomain: your-domain.example.com

```

When `enabled` is `true`, the chart automatically mounts the SPIRE socket and CA bundle into Agent Mesh pods, allowing the Python code to reach the local SPIRE agent without additional configuration.

## Key Implementation Files

Understanding the source structure helps when debugging or extending SPIFFE functionality:

- [`agent-governance-python/agent-mesh/src/agentmesh/identity/spiffe.py`](https://github.com/microsoft/agent-governance-toolkit/blob/main/agent-governance-python/agent-mesh/src/agentmesh/identity/spiffe.py) – Contains the `SPIFFEClient` class that communicates with the SPIRE socket and fetches X.509 and JWT SVIDs.

- [`agent-governance-python/agent-mesh/charts/agentmesh/README.md`](https://github.com/microsoft/agent-governance-toolkit/blob/main/agent-governance-python/agent-mesh/charts/agentmesh/README.md) – Documents Helm chart options including `global.spiffe.enabled` and `global.spiffe.trustDomain`.

- [`docs/specs/AGENTMESH-IDENTITY-TRUST-1.0.md`](https://github.com/microsoft/agent-governance-toolkit/blob/main/docs/specs/AGENTMESH-IDENTITY-TRUST-1.0.md) – Formal specification of the SPIFFE ID format and identity fields used by Agent Mesh.

- [`docs/specs/AGENTMESH-WIRE-1.0.md`](https://github.com/microsoft/agent-governance-toolkit/blob/main/docs/specs/AGENTMESH-WIRE-1.0.md) – References the SPIFFE/SVID specification for the underlying security model.

## Why SPIFFE/SVID for Containerized Agents?

**Zero-trust security** – Every request is cryptographically bound to an identity via mutual TLS, eliminating implicit trust based on network location.

**Automatic rotation** – SVIDs carry a short TTL (default one hour) and refresh before expiry. This automatic rotation minimizes the risk associated with credential leaks.

**Cross-cluster federation** – SPIFFE IDs are globally unique and can be trusted across trust domains when federated, enabling multi-cluster or multi-organizational agent deployments.

## Summary

- Enable SPIFFE support by setting `global.spiffe.enabled=true` and `global.spiffe.trustDomain` in the AGT Helm chart to activate the integration.
- The `SPIFFEClient` class in [`agentmesh/identity/spiffe.py`](https://github.com/microsoft/agent-governance-toolkit/blob/main/agentmesh/identity/spiffe.py) fetches X.509 SVIDs from the local SPIRE Agent socket at `/tmp/spire-agent/public/api.sock`.
- Short-lived SVIDs provide cryptographic identities that the Agent Mesh runtime uses for mutual TLS authentication with the governance gate and peer agents.
- Automatic certificate rotation and standardized SPIFFE IDs enable secure, scalable zero-trust architectures for containerized workloads.

## Frequently Asked Questions

### What is the default socket path for the SPIRE Agent in AGT?

The default Unix domain socket path is `/tmp/spire-agent/public/api.sock`. The AGT Helm chart automatically mounts this socket into containers when `global.spiffe.enabled` is set to `true`, allowing the `SPIFFEClient` to communicate with the local SPIRE Agent.

### How long are SVIDs valid before automatic rotation?

By default, SVIDs have a Time-To-Live (TTL) of one hour. The `SPIFFEClient` implementation handles automatic refresh of certificates before they expire, ensuring continuous availability without manual intervention or service interruption.

### Can agents use JWT-SVIDs instead of X.509 certificates?

Yes. While the standard implementation uses X.509 SVIDs for mutual TLS authentication, the `SPIFFEClient` can also retrieve JWT-SVIDs if your workload requires token-based authentication instead of certificate-based mTLS.

### Where is the trust domain configured in Agent Governance Toolkit?

You define the trust domain in the Helm values file using the `global.spiffe.trustDomain` key, such as `global.spiffe.trustDomain: agentmesh.local`. This value must match your SPIRE deployment's configured trust domain to ensure valid identity issuance.