Skip to content
ProtocolSoup

Platform At A Glance

Architecture

Section titled “Architecture”

ProtocolSoup is a Go backend with a Next.js App Router frontend. The backend uses a plugin system where each identity protocol is a self-contained module that registers its own HTTP routes, flow definitions, and demo scenarios. The frontend serves SSR/SSG discovery pages plus client-interactive protocol tooling, and forwards protocol HTTP traffic to backend services.

┌─────────────────────────────────────────────────────┐
│  Browser (Next.js UI)                               │
│  Looking Glass • Token Inspector • Flow Visualizer  │
└──────────────────────┬──────────────────────────────┘
                       │ HTTP + WebSocket (edge-routed)
                       ▼
┌──────────────────────────────────────────────────────┐
│  Gateway (:8080)                                     │
│  Protocol discovery • Request routing • LG sessions  │
└──┬──────────┬──────────┬──────────┬─────────────────┘
   ▼          ▼          ▼          ▼
Federation  SCIM       SSF       SPIFFE
(OAuth2,    (Users,    (CAEP,    (X.509,
 OIDC,      Groups,    RISC,     JWT-SVID,
 SAML,      Bulk,      Push,     mTLS)
 OID4VCI,   Search)    Poll)
 OID4VP)

Services

Section titled “Services”
ServiceImagePortProtocols
Frontendprotocolsoup-frontend3000UI for all protocols
Gatewayprotocolsoup-gateway8080Protocol discovery, routing, Looking Glass
Federationprotocolsoup-federation8080OAuth 2.0, OIDC, SAML 2.0, OID4VCI, OID4VP
SCIMprotocolsoup-scim8080SCIM 2.0 Users, Groups, Bulk, Search
SSFprotocolsoup-ssf8080, 8081SSF with CAEP/RISC events (8081 = receiver)
SPIFFEprotocolsoup-spiffe8080Workload identity (demo or SPIRE-backed)
VCprotocolsoup-vc8080Standalone OID4VCI/OID4VP
Walletprotocolsoup-wallet8080OID4VP wallet harness
SPIREprotocolsoup-spire-server, -agent, -registration8081, 8443SPIRE trust domain infrastructure

Request Flow

Section titled “Request Flow”
  1. User selects a protocol and flow in the frontend UI.
  2. Frontend sends HTTP protocol requests to backend via configured rewrites.
  3. Edge routing sends WebSocket traffic (/ws/*) directly to backend.
  4. Gateway routes to the correct protocol service based on path prefix.
  5. Protocol service executes the flow, generating real tokens, assertions, or credentials.
  6. Each step emits a Looking Glass event over WebSocket.
  7. Looking Glass renders every step, payload, and validation result in the browser in real time.

Plugin System

Section titled “Plugin System”

Each protocol is a Go plugin implementing a standard interface:

  • Info() — returns protocol ID, name, version, description, and tags
  • RegisterRoutes() — mounts HTTP endpoints (e.g. /oauth2/token, /saml/sso)
  • GetFlowDefinitions() — declares available flows for the UI
  • GetDemoScenarios() — provides pre-configured demo scenarios

Plugins are registered at startup and automatically contribute to protocol discovery, Looking Glass integration, and the API index.

Looking Glass Events

Section titled “Looking Glass Events”

Protocol handlers emit structured events during flow execution. Events flow through WebSocket to the frontend where they render as a timeline:

Event TypePurpose
flow.stepMajor protocol steps (redirect, token exchange, assertion delivery)
token.issuedToken creation with decoded claims
token.validatedToken validation pass/fail with details
http.exchangeFull HTTP request/response pairs
security.warningSpec violations and validation failures
crypto.operationSigning, verification, key generation

Each event can carry RFC reference annotations linking to the relevant specification section.

Technology Stack

Section titled “Technology Stack”
LayerTechnology
Backend runtimeGo 1.25, chi router
Frontend frameworkNext.js App Router, React 18
StylingTailwind CSS, Framer Motion
State managementZustand
Real-timeWebSocket (Looking Glass event streaming)
StorageSQLite (SCIM), file-based (SSF, VC state)
IdentityBuilt-in mock IdP with configurable demo users and clients
Container imagesMulti-arch (linux/amd64, linux/arm64), scanned with Trivy

Deployment Options

Section titled “Deployment Options”
ModelCompose FileServicesBest For
Full stackdocker-compose.ymlfrontend, gateway, federation, SCIM, SSFLearning, demos, full exploration
Full stack + SPIFFEdocker-compose.yml + docker-compose.spiffe.ymlAll above + SPIRE + SPIFFEWorkload identity evaluation
Simple monolithdocker-compose.simple.ymlSingle backend + frontendQuick OAuth/OIDC/SAML evaluation
Single servicedocker run from GHCRAny one imageTargeted testing, CI pipelines
Custom topologySelected GHCR imagesYour choicePlatform integration
Section titled “Related”