authsec-autogen 0.1.0

AuthSec integration for AutoGen — secure AI delegation token retrieval

AuthSec AI — AutoGen Integration

Function-calling delegation — an AutoGen AssistantAgent directs a UserProxyAgent to invoke an AuthSec-secured Python function that retrieves confidential data from a protected backend.

---

Architecture

AutoGen Function (registered in main.py)
  ↓
authsec_helper.py       — thin wrapper, MOCK fallback, debug logging
  ↓
authsec-langchain-sdk   — official SDK (PyPI)
  ↓
AuthSec Delegation Backend
  ↓
Short-lived JWT (RS256, scoped, SPIFFE-identified)
  ↓
Protected API (with Authorization: Bearer header)

The official SDK owns the entire delegation-token lifecycle. authsec_helper.py is a thin, framework-agnostic wrapper that adds MOCK fallback and structured console logging — it never reimplements the token exchange itself.

---

File Structure

File	Role
authsec_helper.py	Thin wrapper around authsec-langchain-sdk; MOCK fallback, debug logging
main.py	Entry point; SecurityAssistant + UserProxy agent demo, fetch_secure_data() function
requirements.txt	Dependencies including authsec-langchain-sdk

---

Prerequisites

Requirement	Details
Python	3.10 or later
AuthSec account	Registered AI agent client on the AuthSec dashboard
Trust delegation	Created with target type "Langchain AI agent"
authsec-langchain-sdk	pip install authsec-langchain-sdk

---

Installation & Setup

cd integrations/autogen
pip install -r requirements.txt

requirements.txt pulls in pyautogen, requests, authsec-langchain-sdk, and supporting packages.

---

Running the Demo

MOCK Mode — zero setup

python main.py

No environment variables required. When AUTHSEC_BASE_URL and AUTHSEC_AGENT_CLIENT_ID are absent, the wrapper falls back to an offline mock mode with demo data. Useful for exploring the integration pattern without an AuthSec account.

LIVE Mode — against production

# Windows PowerShell
$env:AUTHSEC_BASE_URL      = "https://prod.api.authsec.ai"
$env:AUTHSEC_AGENT_CLIENT_ID = "your-agent-client-uuid"
$env:OPENAI_API_KEY        = "sk-..."   # optional — enables real LLM agent

python main.py

# bash / zsh
export AUTHSEC_BASE_URL="https://prod.api.authsec.ai"
export AUTHSEC_AGENT_CLIENT_ID="your-agent-client-uuid"
export OPENAI_API_KEY="sk-..."

python main.py

When OPENAI_API_KEY is set, main.py launches a full AutoGen conversational loop between SecurityAssistant and UserProxy. Without it, the demo runs a high-fidelity simulation that still exercises the real AuthSec token flow.

---

Example Output (LIVE mode, verified against production)

[AuthSec SDK] -- Initializing AuthSec Client (AutoGen) ------------
[AuthSec SDK] [Mode] LIVE — using official authsec-langchain-sdk
  |- Base URL  : https://prod.api.authsec.ai
  |- Client ID : fe6d5a81-58ac-4c4b-85fa-f84b6c9cb73d
[AuthSec SDK] [Init] Official authsec-langchain-sdk client initialized.
[AuthSec SDK] [Delegation] Requesting delegation token via official authsec-langchain-sdk...
[AuthSec SDK] [Success] LIVE delegation token acquired via official SDK.
  |- Token  : eyJhbGciOiJSUzI1NiIsInR5...

---

How the Integration Works

1. Agent setup — SecurityAssistant (cognitive layer, GPT-4) and UserProxy (execution layer, human_input_mode="NEVER") are created using standard AutoGen configuration.

2. Function registration — fetch_secure_data() is registered via autogen.register_function() so the assistant can propose calls and the proxy can execute them.

3. SDK initialization — at module load, AuthSecClient() reads AUTHSEC_BASE_URL and AUTHSEC_AGENT_CLIENT_ID and initializes an AuthsecClient from the official authsec-langchain-sdk.

4. Conversational trigger — during the chat loop, SecurityAssistant generates a function call. AutoGen routes execution to UserProxy, which invokes fetch_secure_data().

5. Delegation token retrieval — inside the function, client.get_delegation_token() delegates to:

   GET /authsec/uflow/sdk/delegation-token?client_id=<uuid>
   

   The SDK handles the exact request contract required by the AuthSec backend (Trust Delegation target type: "Langchain AI agent").

6. Downstream API call — the JWT is passed as Authorization: Bearer <token> to the protected endpoint via client.request_secure_api().

7. Agent analysis — SecurityAssistant receives the JSON payload, summarizes it, and terminates the session with TERMINATE.

---

Environment Variables Reference

Variable	Required	Description
AUTHSEC_BASE_URL	Yes (LIVE)	AuthSec server root, e.g. https://prod.api.authsec.ai
AUTHSEC_AGENT_CLIENT_ID	Yes (LIVE)	Agent's client UUID from the AuthSec dashboard
OPENAI_API_KEY	Optional	Enables a real LLM-powered AutoGen agent; simulation runs without it

---

Security Model

AuthSec replaces static, long-lived API keys with short-lived delegation tokens. Each token is a signed RS256 JWT scoped to the specific permissions granted through the trust delegation. Tokens expire automatically — the SDK refreshes them transparently — so there is no secret to rotate or leak into version control.

Every delegation token carries a SPIFFE identity (spiffe://authsec.dev/ns/default/sa/ai-agent) that cryptographically binds the token to a specific agent workload. Downstream APIs verify both the JWT signature and the SPIFFE subject, establishing a chain of trust from the AuthSec backend through the SDK to the protected resource.

This model means the AI agent never handles raw credentials for the target API. The AuthSec backend acts as a trust broker: it evaluates the delegation policy, mints a scoped token, and the agent simply presents that token. Revoking access is a single dashboard action — no credential rotation required.

---

Debug Logging

The wrapper emits structured, colour-coded console output under the [AuthSec SDK] prefix:

Prefix	Meaning
[Mode] LIVE	SDK initialized, env vars detected
[Mode] MOCK	No env vars — running offline
[Init]	SDK client construction result
[Delegation]	Token request in progress
[Success]	Token acquired or API call succeeded
[Error]	SDK call failed — fallback triggered
[Token] … [MOCK FALLBACK]	Using locally generated mock JWT

---

Troubleshooting

Symptom	Cause	Fix
404 Client not found	client_id not registered, or trust delegation not created	Verify the UUID on the AuthSec dashboard; ensure a trust delegation exists with target type "Langchain AI agent"
ImportError: authsec_langchain	SDK not installed	pip install authsec-langchain-sdk
SSL / connection errors	Wrong URL scheme or unreachable host	Confirm AUTHSEC_BASE_URL uses https:// for production
400 Invalid client_id format	Trailing whitespace or characters in UUID	Check for copy-paste artefacts in the env var

---

A Note on secure-vault/… Endpoints

The secure-vault/metrics, secure-vault/records, etc. endpoints used in this demo are illustrative mock resources. They are intentionally not hosted on prod.api.authsec.ai. The delegation token flow succeeds against production — you will see a valid JWT returned — but the subsequent call to secure-vault/* will return a 404. This is expected behaviour, not a bug. In a real deployment you would replace these paths with your own protected API endpoints.

---

Further Reading

• AuthSec LangChain SDK docs
• Blog — Securing AI Agent API Calls with AuthSec + LangChain
• Root integration README