# strongdm/agentic-auth architecture

> Architecture diagram of the GitHub repository strongdm/agentic-auth, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-06-16). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/strongdm/agentic-auth
- Repository: https://github.com/strongdm/agentic-auth

## Overview

1. This repository is a collection of self-contained StrongDM ID examples, not a single product application. The common architectural theme is identity: clients obtain StrongDM-issued credentials, and services enforce authentication, delegated authorization, and token-bound trust.

2. The central external dependency is StrongDM ID itself. The repo documents and exercises its main surfaces: agent/client registration, token issuance, token introspection, JWKS/discovery, revocation, userinfo, DPoP, and SPIFFE/JWT-SVID support. Realm-qualified endpoints are a first-class boundary, so most examples are built to work against a tenant-specific issuer.

3. The dominant request flow is: register or enroll a client/agent, activate it, obtain an access token, then call a protected API. On the server side, middleware validates JWTs against StrongDM ID’s keys or introspection and checks scopes; on the client side, some examples also attach proof-of-possession material such as DPoP.

4. `examples/flask-middleware` is a minimal Python web boundary around Flask. `app.py` defines protected routes, while `strongdm_auth.py` encapsulates the StrongDM-specific verification and scope checks. This example is about inserting auth policy in front of ordinary Flask handlers.

5. `examples/go-middleware` is the Go equivalent for `net/http`. `main.go` hosts protected endpoints, `strongdmauth.go` provides the auth middleware and scope enforcement, and `client/main.go` demonstrates the full enrollment-to-API-call lifecycle from the command line. This example shows both server enforcement and client bootstrap in one package.

6. `examples/nextjs-middleware` applies the same boundary at the framework edge. `middleware.ts` is the interception layer, `lib/strongdm-auth.ts` holds the validation logic, and the `app/api/*/route.ts` files are the protected handlers. The architecture is route-driven: middleware decides access before the route code runs.

7. `examples/agentkey` is a fuller web application built with Swift/Vapor. It has a classic layered structure: auth models and middleware under `Sources/App/Auth`, request handlers under `Controllers/Web` and `Controllers/API`, persistence models and migrations under `Models` and `Migrations`, and Leaf templates plus static assets under `Resources` and `Public`. It looks like the most complete end-user-facing demo, with dashboards for agents, keys, proofs, profiles, search, and verification.

8. Within `agentkey`, the data boundary is persistent state plus web presentation. The migrations create the backing tables for agents, public keys, proofs, activity logs, and sponsorship metadata; controllers read/write those models; templates render the dashboard and public pages; and the API controllers expose machine-readable endpoints, including the OpenAPI spec in `Public/openapi.yaml`.

9. `examples/dpop-client` is purely client-side and focuses on sender-constrained tokens. The Go, Python, and TypeScript variants all generate a key pair, create a DPoP proof, and use it when requesting or calling token-bound endpoints. There is no server component here; the architectural point is how the client proves possession of its private key.

10. `examples/spiffe-client` is another client-only identity example, but for workload identity. Its Go, Python, and TypeScript implementations fetch the SPIFFE trust bundle and request JWT-SVIDs, showing how StrongDM ID can participate in service-to-service trust rather than end-user web auth.

11. `examples/secure-rag-pipeline` is the most distributed example. A Python `orchestrator` coordinates the workflow, while separate containerized MCP servers handle document access, vector retrieval, ranking, and LLM generation. Shared auth code under `mcp-servers/shared` suggests each service is individually protected, and `docker-compose.yml` wires the whole pipeline together. The data flow is ingest/query orchestration rather than a standard HTTP app.

12. Supporting material in the repo matters architecturally because it documents intended flows rather than adding runtime logic: `DIALTONE-DEMO.md` and `USE-CASES.md` explain the auth lifecycle and integration patterns, while `scripts/forum-post.py` appears to be a standalone helper script outside the main examples.

13. If you draw this repo, the best top-level diagram is a hub-and-spoke model: StrongDM ID in the center, with independent example applications around it. Some spokes are API protectors, some are token-issuing clients, one is a full Swift web app, and one is a multi-service RAG pipeline with an orchestrator plus specialized backends.

Main entry points: [`examples/secure-rag-pipeline/orchestrator/graph.py`](https://github.com/strongdm/agentic-auth/blob/master/examples/secure-rag-pipeline/orchestrator/graph.py) (Orchestrator), [`examples/secure-rag-pipeline/docker-compose.yml`](https://github.com/strongdm/agentic-auth/blob/master/examples/secure-rag-pipeline/docker-compose.yml) (Compose file), [`examples/secure-rag-pipeline/mcp-servers/shared/auth.py`](https://github.com/strongdm/agentic-auth/blob/master/examples/secure-rag-pipeline/mcp-servers/shared/auth.py) (Shared auth), [`examples/agentkey/Sources/App/Auth/StrongDMAuth.swift`](https://github.com/strongdm/agentic-auth/blob/master/examples/agentkey/Sources/App/Auth/StrongDMAuth.swift) (Auth stack)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_docs["Docs"]
  node_repo_docs["Guides<br/>repo docs<br/>[README.md]"]
  node_demo_doc["Demo flow<br/>usage guide<br/>[DIALTONE-DEMO.md]"]
  node_use_cases["Use cases<br/>integration guide<br/>[USE-CASES.md]"]
  node_forum_script["Forum script<br/>helper script<br/>[forum-post.py]"]
end

subgraph group_flask["Flask example"]
  node_flask_app["Flask app<br/>python web example<br/>[app.py]"]
  node_flask_auth["Auth layer<br/>python auth middleware<br/>[strongdm_auth.py]"]
end

subgraph group_go_next["Go and Next.js examples"]
  node_go_server["Go server<br/>http server example<br/>[main.go]"]
  node_go_auth["Auth middleware<br/>[strongdmauth.go]"]
  node_go_client["Bootstrap client<br/>go enrollment client<br/>[main.go]"]
  node_next_mw["Edge middleware<br/>nextjs middleware<br/>[middleware.ts]"]
  node_next_auth["Validation lib<br/>typescript auth lib<br/>[strongdm-auth.ts]"]
  node_next_routes["API routes<br/>nextjs routes<br/>[route.ts]"]
end

subgraph group_swift["Swift app"]
  node_agentkey_auth["Auth stack<br/>swift auth layer<br/>[StrongDMAuth.swift]"]
  node_agentkey_web["Web controllers"]
  node_agentkey_api["API controllers"]
  node_agentkey_models[("Data models<br/>swift persistence models<br/>[Agent.swift]")]
  node_agentkey_views["Views and assets<br/>swift presentation<br/>[home.leaf]"]
end

subgraph group_clients["Client identity examples"]
  node_dpop_client["DPoP client<br/>sender-constrained clients<br/>[README.md]"]
  node_spiffe_client["SPIFFE client<br/>workload identity clients<br/>[README.md]"]
end

subgraph group_rag["RAG pipeline"]
  node_rag_orch["Orchestrator<br/>python pipeline coordinator<br/>[graph.py]"]
  node_rag_mcp_shared["Shared auth<br/>python mcp auth<br/>[auth.py]"]
  node_rag_docs["Docs MCP<br/>mcp service<br/>[main.py]"]
  node_rag_vector["Vector MCP<br/>mcp service<br/>[main.py]"]
  node_rag_ranker["Ranker MCP<br/>mcp service<br/>[main.py]"]
  node_rag_llm["LLM MCP<br/>mcp service<br/>[main.py]"]
  node_rag_compose["Compose file<br/>deployment wiring<br/>[docker-compose.yml]"]
end

node_strongdm_id(("StrongDM ID<br/>external identity platform"))

node_strongdm_id -->|"issues tokens"| node_flask_auth
node_strongdm_id -->|"issues tokens"| node_go_auth
node_strongdm_id -->|"issues tokens"| node_next_auth
node_strongdm_id -->|"issues tokens"| node_agentkey_auth
node_strongdm_id -->|"binds tokens"| node_dpop_client
node_strongdm_id -->|"trust bundle"| node_spiffe_client
node_strongdm_id -->|"protects services"| node_rag_orch
node_repo_docs -->|"documents"| node_demo_doc
node_repo_docs -->|"documents"| node_use_cases
node_flask_app -->|"uses"| node_flask_auth
node_go_server -->|"uses"| node_go_auth
node_go_client -->|"calls"| node_go_server
node_next_mw -->|"delegates"| node_next_auth
node_next_mw -->|"gates"| node_next_routes
node_agentkey_auth -->|"protects"| node_agentkey_web
node_agentkey_auth -->|"protects"| node_agentkey_api
node_agentkey_models -->|"serves"| node_agentkey_api
node_agentkey_views -->|"renders"| node_agentkey_web
node_rag_orch -->|"queries"| node_rag_docs
node_rag_orch -->|"retrieves"| node_rag_vector
node_rag_orch -->|"ranks"| node_rag_ranker
node_rag_orch -->|"generates"| node_rag_llm
node_rag_mcp_shared -->|"secures"| node_rag_docs
node_rag_mcp_shared -->|"secures"| node_rag_vector
node_rag_mcp_shared -->|"secures"| node_rag_ranker
node_rag_mcp_shared -->|"secures"| node_rag_llm
node_rag_compose -->|"wires"| node_rag_orch
node_rag_compose -->|"wires"| node_rag_docs
node_rag_compose -->|"wires"| node_rag_vector
node_rag_compose -->|"wires"| node_rag_ranker
node_rag_compose -->|"wires"| node_rag_llm

click node_repo_docs "https://github.com/strongdm/agentic-auth/blob/master/README.md"
click node_demo_doc "https://github.com/strongdm/agentic-auth/blob/master/DIALTONE-DEMO.md"
click node_use_cases "https://github.com/strongdm/agentic-auth/blob/master/USE-CASES.md"
click node_forum_script "https://github.com/strongdm/agentic-auth/blob/master/scripts/forum-post.py"
click node_flask_app "https://github.com/strongdm/agentic-auth/blob/master/examples/flask-middleware/app.py"
click node_flask_auth "https://github.com/strongdm/agentic-auth/blob/master/examples/flask-middleware/strongdm_auth.py"
click node_go_server "https://github.com/strongdm/agentic-auth/blob/master/examples/go-middleware/main.go"
click node_go_auth "https://github.com/strongdm/agentic-auth/blob/master/examples/go-middleware/strongdmauth.go"
click node_go_client "https://github.com/strongdm/agentic-auth/blob/master/examples/go-middleware/client/main.go"
click node_next_mw "https://github.com/strongdm/agentic-auth/blob/master/examples/nextjs-middleware/middleware.ts"
click node_next_auth "https://github.com/strongdm/agentic-auth/blob/master/examples/nextjs-middleware/lib/strongdm-auth.ts"
click node_next_routes "https://github.com/strongdm/agentic-auth/blob/master/examples/nextjs-middleware/app/api/protected/route.ts"
click node_agentkey_auth "https://github.com/strongdm/agentic-auth/blob/master/examples/agentkey/Sources/App/Auth/StrongDMAuth.swift"
click node_agentkey_web "https://github.com/strongdm/agentic-auth/blob/master/examples/agentkey/Sources/App/Controllers/Web/DashboardController.swift"
click node_agentkey_api "https://github.com/strongdm/agentic-auth/blob/master/examples/agentkey/Sources/App/Controllers/API/AgentAPIController.swift"
click node_agentkey_models "https://github.com/strongdm/agentic-auth/blob/master/examples/agentkey/Sources/App/Models/Agent.swift"
click node_agentkey_views "https://github.com/strongdm/agentic-auth/blob/master/examples/agentkey/Resources/Views/home.leaf"
click node_dpop_client "https://github.com/strongdm/agentic-auth/blob/master/examples/dpop-client/README.md"
click node_spiffe_client "https://github.com/strongdm/agentic-auth/blob/master/examples/spiffe-client/README.md"
click node_rag_orch "https://github.com/strongdm/agentic-auth/blob/master/examples/secure-rag-pipeline/orchestrator/graph.py"
click node_rag_mcp_shared "https://github.com/strongdm/agentic-auth/blob/master/examples/secure-rag-pipeline/mcp-servers/shared/auth.py"
click node_rag_docs "https://github.com/strongdm/agentic-auth/blob/master/examples/secure-rag-pipeline/mcp-servers/docs-mcp/main.py"
click node_rag_vector "https://github.com/strongdm/agentic-auth/blob/master/examples/secure-rag-pipeline/mcp-servers/vectordb-mcp/main.py"
click node_rag_ranker "https://github.com/strongdm/agentic-auth/blob/master/examples/secure-rag-pipeline/mcp-servers/ranker-mcp/main.py"
click node_rag_llm "https://github.com/strongdm/agentic-auth/blob/master/examples/secure-rag-pipeline/mcp-servers/llm-mcp/main.py"
click node_rag_compose "https://github.com/strongdm/agentic-auth/blob/master/examples/secure-rag-pipeline/docker-compose.yml"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_repo_docs,node_demo_doc,node_use_cases,node_forum_script toneBlue
class node_flask_app,node_flask_auth toneAmber
class node_go_server,node_go_auth,node_go_client,node_next_mw,node_next_auth,node_next_routes toneMint
class node_agentkey_auth,node_agentkey_web,node_agentkey_api,node_agentkey_models,node_agentkey_views toneRose
class node_dpop_client,node_spiffe_client toneIndigo
class node_rag_orch,node_rag_mcp_shared,node_rag_docs,node_rag_vector,node_rag_ranker,node_rag_llm,node_rag_compose toneTeal
class node_strongdm_id toneNeutral
```

## Components

### Docs

Repository-level documentation and usage guides.

- [Guides](https://github.com/strongdm/agentic-auth/blob/master/README.md): repo docs · Overview and lifecycle documentation for the examples. · `README.md`
- [Demo flow](https://github.com/strongdm/agentic-auth/blob/master/DIALTONE-DEMO.md): usage guide · Explains the authentication lifecycle and demo scenarios. · `DIALTONE-DEMO.md`
- [Use cases](https://github.com/strongdm/agentic-auth/blob/master/USE-CASES.md): integration guide · Collects example integration patterns and intended flows. · `USE-CASES.md`
- [Forum script](https://github.com/strongdm/agentic-auth/blob/master/scripts/forum-post.py): helper script · Standalone script outside the main example architectures. · `scripts/forum-post.py`

### Flask example

Python middleware example around a protected web boundary.

- [Flask app](https://github.com/strongdm/agentic-auth/blob/master/examples/flask-middleware/app.py): python web example · Minimal web boundary with protected routes. · `examples/flask-middleware/app.py`
- [Auth layer](https://github.com/strongdm/agentic-auth/blob/master/examples/flask-middleware/strongdm_auth.py): python auth middleware · Encapsulates StrongDM token verification and scope checks. · `examples/flask-middleware/strongdm_auth.py`

### Go and Next.js examples

Middleware and client bootstrap examples in Go and TypeScript.

- [Go server](https://github.com/strongdm/agentic-auth/blob/master/examples/go-middleware/main.go): http server example · net/http handlers behind StrongDM-aware middleware. · `examples/go-middleware/main.go`
- [Auth middleware](https://github.com/strongdm/agentic-auth/blob/master/examples/go-middleware/strongdmauth.go): go auth middleware · Validates tokens and enforces scopes for Go handlers. · `examples/go-middleware/strongdmauth.go`
- [Bootstrap client](https://github.com/strongdm/agentic-auth/blob/master/examples/go-middleware/client/main.go): go enrollment client · Command-line client that demonstrates enroll, activate, and call. · `examples/go-middleware/client/main.go`
- [Edge middleware](https://github.com/strongdm/agentic-auth/blob/master/examples/nextjs-middleware/middleware.ts): nextjs middleware · Interception layer that gates access before routes run. · `examples/nextjs-middleware/middleware.ts`
- [Validation lib](https://github.com/strongdm/agentic-auth/blob/master/examples/nextjs-middleware/lib/strongdm-auth.ts): typescript auth lib · Shared StrongDM validation logic for the Next.js app. · `examples/nextjs-middleware/lib/strongdm-auth.ts`
- [API routes](https://github.com/strongdm/agentic-auth/blob/master/examples/nextjs-middleware/app/api/protected/route.ts): nextjs routes · Protected route handlers for the app API surface. · `examples/nextjs-middleware/app/api/protected/route.ts`

### Swift app

Full Vapor web application example.

- [Auth stack](https://github.com/strongdm/agentic-auth/blob/master/examples/agentkey/Sources/App/Auth/StrongDMAuth.swift): swift auth layer · Models and middleware for StrongDM authentication and web security. · `examples/agentkey/Sources/App/Auth/StrongDMAuth.swift`
- [Web controllers](https://github.com/strongdm/agentic-auth/blob/master/examples/agentkey/Sources/App/Controllers/Web/DashboardController.swift): swift web controllers · HTML-facing controllers for home, dashboard, profile, and static pages. · `examples/agentkey/Sources/App/Controllers/Web/DashboardController.swift`
- [API controllers](https://github.com/strongdm/agentic-auth/blob/master/examples/agentkey/Sources/App/Controllers/API/AgentAPIController.swift): swift api controllers · Machine-readable endpoints for agents, keys, and verification. · `examples/agentkey/Sources/App/Controllers/API/AgentAPIController.swift`
- [Data models](https://github.com/strongdm/agentic-auth/blob/master/examples/agentkey/Sources/App/Models/Agent.swift): swift persistence models · Agents, keys, proofs, and activity log entities. · `examples/agentkey/Sources/App/Models/Agent.swift`
- [Views and assets](https://github.com/strongdm/agentic-auth/blob/master/examples/agentkey/Resources/Views/home.leaf): swift presentation · Leaf templates, static assets, and OpenAPI contract. · `examples/agentkey/Resources/Views/home.leaf`

### Client identity examples

Client-only proof-of-possession and workload identity examples.

- [DPoP client](https://github.com/strongdm/agentic-auth/blob/master/examples/dpop-client/README.md): sender-constrained clients · Go, Python, and TypeScript clients that generate proofs of possession. · `examples/dpop-client/README.md`
- [SPIFFE client](https://github.com/strongdm/agentic-auth/blob/master/examples/spiffe-client/README.md): workload identity clients · Go, Python, and TypeScript clients that fetch trust bundles and JWT-SVIDs. · `examples/spiffe-client/README.md`

### RAG pipeline

Distributed retrieval-augmented generation example with orchestrator and MCP services.

- [Orchestrator](https://github.com/strongdm/agentic-auth/blob/master/examples/secure-rag-pipeline/orchestrator/graph.py): python pipeline coordinator · Coordinates ingest and query flows across the pipeline. · `examples/secure-rag-pipeline/orchestrator/graph.py`
- [Shared auth](https://github.com/strongdm/agentic-auth/blob/master/examples/secure-rag-pipeline/mcp-servers/shared/auth.py): python mcp auth · Common authentication logic reused by MCP services. · `examples/secure-rag-pipeline/mcp-servers/shared/auth.py`
- [Docs MCP](https://github.com/strongdm/agentic-auth/blob/master/examples/secure-rag-pipeline/mcp-servers/docs-mcp/main.py): mcp service · Document access service in the secure RAG workflow. · `examples/secure-rag-pipeline/mcp-servers/docs-mcp/main.py`
- [Vector MCP](https://github.com/strongdm/agentic-auth/blob/master/examples/secure-rag-pipeline/mcp-servers/vectordb-mcp/main.py): mcp service · Retrieval service for vector-backed search. · `examples/secure-rag-pipeline/mcp-servers/vectordb-mcp/main.py`
- [Ranker MCP](https://github.com/strongdm/agentic-auth/blob/master/examples/secure-rag-pipeline/mcp-servers/ranker-mcp/main.py): mcp service · Ranking service used during query refinement. · `examples/secure-rag-pipeline/mcp-servers/ranker-mcp/main.py`
- [LLM MCP](https://github.com/strongdm/agentic-auth/blob/master/examples/secure-rag-pipeline/mcp-servers/llm-mcp/main.py): mcp service · Generation service that produces final responses. · `examples/secure-rag-pipeline/mcp-servers/llm-mcp/main.py`
- [Compose file](https://github.com/strongdm/agentic-auth/blob/master/examples/secure-rag-pipeline/docker-compose.yml): deployment wiring · Container orchestration for the distributed RAG example. · `examples/secure-rag-pipeline/docker-compose.yml`

### Other components

- **StrongDM ID**: external identity platform · Tenant-qualified issuer and validation authority used by all examples.

## Connections

- StrongDM ID → Auth layer: issues tokens · Flask middleware validates StrongDM-issued credentials.
- StrongDM ID → Auth middleware: issues tokens · Go middleware checks JWTs or introspection against StrongDM ID.
- StrongDM ID → Validation lib: issues tokens · Next.js middleware uses StrongDM validation material.
- StrongDM ID → Auth stack: issues tokens · Swift app authenticates users and agents through StrongDM ID.
- StrongDM ID → DPoP client: binds tokens · DPoP clients create proof-of-possession material for StrongDM ID flows.
- StrongDM ID → SPIFFE client: trust bundle · SPIFFE clients fetch trust data and JWT-SVIDs from StrongDM ID.
- StrongDM ID → Orchestrator: protects services · Pipeline orchestration relies on StrongDM-protected endpoints.
- Guides → Demo flow: documents · Repository guides explain the identity lifecycle.
- Guides → Use cases: documents · Use-case notes show example integration patterns.
- Flask app → Auth layer: uses · Routes are wrapped by StrongDM-aware auth checks.
- Go server → Auth middleware: uses · Handlers are protected by middleware.
- Bootstrap client → Go server: calls · Client demonstrates enroll-activate-call lifecycle.
- Edge middleware → Validation lib: delegates · Edge middleware delegates token validation to shared logic.
- Edge middleware → API routes: gates · Requests are allowed or denied before route execution.
- Auth stack → Web controllers: protects · Web handlers rely on auth middleware and security helpers.
- Auth stack → API controllers: protects · API handlers use the same auth boundary.
- Data models → API controllers: serves · API controllers read and write persistent identity records.
- Views and assets → Web controllers: renders · Leaf templates and assets back the dashboard and public pages.
- Orchestrator → Docs MCP: queries · Orchestrator starts by accessing documents.
- Orchestrator → Vector MCP: retrieves · Retrieval stage queries the vector service.
- Orchestrator → Ranker MCP: ranks · Ranking stage refines candidate results.
- Orchestrator → LLM MCP: generates · Generation stage produces the final answer.
- Shared auth → Docs MCP: secures · Shared auth is reused by each MCP server.
- Shared auth → Vector MCP: secures · Shared auth is reused by each MCP server.
- Shared auth → Ranker MCP: secures · Shared auth is reused by each MCP server.
- Shared auth → LLM MCP: secures · Shared auth is reused by each MCP server.
- Compose file → Orchestrator: wires · Compose brings the orchestrator and services up together.
- Compose file → Docs MCP: wires · Compose brings the orchestrator and services up together.
- Compose file → Vector MCP: wires · Compose brings the orchestrator and services up together.
- Compose file → Ranker MCP: wires · Compose brings the orchestrator and services up together.
- Compose file → LLM MCP: wires · Compose brings the orchestrator and services up together.
