draco-toolkit

Authentication and authorization for AI agents: SPIFFE identity, per-tool OAuth tokens via RFC 8693 exchange, per-call authorization against OpenFGA or local policy bundles, posture management, and behavioral telemetry.

Install

pip install draco-toolkit

The distribution is draco-toolkit; the import name is draco:

from draco.core.bootstrap import bootstrap

Optional extras: pip install "draco-toolkit[metrics]" for OpenTelemetry instrumentation.

Full documentation, concepts, and guides: github.com/Draco-Tech-ai/draco-toolkit. Website: draco-tech.ai.

Developing from source

uv pip install -e ".[dev]"

Test

pytest

Lint

ruff check .
ruff format --check .
mypy src/

Configuration

The SDK reads a JSON config file via bootstrap(Mode.DIRECT, path). All IdP-specific behavior is controlled by config fields; the code has no IdP-specific branches.

Token flow

The SDK uses a two-phase token model:

1. Base token: SVID assertion at the IdP's token endpoint. The grant type and parameter names vary by IdP.
2. Per-target tokens: RFC 8693 token exchange of the base token, scoped by audience.

DCR (RFC 7591) is optional. When configured, the agent self-registers with the IdP at startup and deregisters on shutdown. When not configured, the agent uses a pre-registered client identified by the SVID's subject claim.

Keycloak

Keycloak uses client_credentials grant with the SVID as a client_assertion (federated-jwt client authentication). DCR is not supported directly with SVIDs; agents use pre-registered clients.

{
  "agent_spiffe_id": "spiffe://example.draco.local/agents/hello-agent/default",
  "spiffe_endpoint_socket": "unix:///spiffe-workload-api/spire-agent.sock",
  "idp_token_endpoint": "https://keycloak.example.draco.local/realms/draco/protocol/openid-connect/token",
  "idp_grant_type": "client_credentials",
  "ca_bundle_path": "/etc/ssl/step-ca/root_ca.crt",

  "authz_backend": "openfga",
  "openfga_url": "https://openfga.example.draco.local",
  "openfga_store_id": "01ARZ3NDEKTSV4RRFFQ69G5FAV",
  "openfga_audience": "openfga",

  "posture_source": "/etc/draco/bundles",
  "trust_store_backend": "file",
  "trust_store_path": "/var/draco/trust-state.json",

  "tools": [...]
}

Keycloak prerequisites:

• A Keycloak client (e.g. draco-hello-agent) with clientAuthenticatorType=federated-jwt, serviceAccountsEnabled=true, and standard.token.exchange.enabled=true.
• jwt.credential.sub set to the agent's SPIFFE ID.
• jwt.credential.issuer set to the SPIFFE IdP alias (e.g. spire).
• A SPIFFE identity provider at the realm level with the SPIRE trust domain and bundle endpoint.
• For each target service (e.g. OpenFGA), a Keycloak client registered with that service name as the clientId, and the requesting client's service account assigned a role on that target client (Keycloak resolves available exchange audiences via role mappings).
• A self-audience mapper on the agent's client so the base token's aud includes the client itself (required by Keycloak's standard token exchange).

Other RFC 8693-capable IdPs are supported through the same configuration surface (idp_grant_type, idp_client_audience, and the optional dcr block); Keycloak is the documented reference.

Config field reference