authsec-llamaindex 0.1.0

AuthSec integration for LlamaIndex — secure AI delegation token retrieval

AuthSec AI — LlamaIndex Integration

Reader-based ingestion — a custom BaseReader authenticates with AuthSec, fetches restricted records from a protected API, and indexes them into a LlamaIndex VectorStoreIndex for RAG queries.

---

Architecture

LlamaIndex Reader (custom_reader.py)  — BaseReader subclass
  ↓
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
custom_reader.py	LlamaIndex BaseReader subclass — AuthSecSecureReader
main.py	Entry point; ingestion + VectorStoreIndex + query demo
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/llamaindex
pip install -r requirements.txt

requirements.txt pulls in llama-index-core, 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 queries

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 builds a real VectorStoreIndex and runs natural-language queries against the ingested documents. Without it, the demo runs a high-fidelity simulation that still exercises the real AuthSec token flow and document parsing.

---

Example Output (LIVE mode, verified against production)

[AuthSec SDK] -- Initializing AuthSec Client (LlamaIndex) ----------
[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. Custom Reader subclass — AuthSecSecureReader (in custom_reader.py) inherits from LlamaIndex's BaseReader, making it plug-and-play with any ingestion pipeline.

2. SDK initialization — when AuthSecSecureReader is constructed, its internal AuthSecClient reads AUTHSEC_BASE_URL and AUTHSEC_AGENT_CLIENT_ID and initializes an AuthsecClient from the official authsec-langchain-sdk.

3. load_data() call — the pipeline calls reader.load_data(endpoint=..., scope=...). Inside, the reader requests a delegation token:

   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").

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

5. Document construction — the returned JSON is parsed into LlamaIndex Document objects with security-stamped metadata (source_endpoint, ingestion_auth, clearance_required).

6. Vector indexing — main.py feeds the documents into a VectorStoreIndex. Chunks are embedded and stored for retrieval.

7. RAG query — natural-language questions are resolved against the secured, indexed data — producing authenticated, source-attributed answers.

---

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 real LLM embeddings and queries; 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