ProtocolSoup
A sandbox for exploring authentication and identity protocols. Run real flows against a local MockIdP, inspect HTTP traffic, decode tokens.
Install / Use
/learn @ParleSec/ProtocolSoupREADME
ProtocolSoup
An interactive sandbox for exploring authentication and identity protocols. Execute real protocol flows against a local Mock IdP, inspect HTTP traffic in real-time, decode tokens, and understand security protocols hands-on.
Real flows against real infrastructure
Protocols: OAuth 2.0 • OpenID Connect • SAML 2.0 • SPIFFE/SPIRE • SCIM 2.0 • Shared Signals (SSF)
Live Website
Quick Start
Features
| Feature | Description | |---------|-------------| | Looking Glass | Execute protocol flows and inspect every HTTP request/response in real-time via WebSocket | | Token Inspector | Decode JWTs (access, ID, refresh tokens), examine claims, verify signatures, view SAML assertions | | Mock IdP | Self-contained identity provider with preconfigured test users and clients | | Flow Visualizer | Step-by-step animated protocol flow diagrams | | Plugin Architecture | Add new protocols without modifying core infrastructure | | SSF Sandbox | Interactive Shared Signals Framework testing with real-time event delivery |
Supported Flows
OAuth 2.0
| Flow | RFC | Description | |------|-----|-------------| | Authorization Code | RFC 6749 | Standard web app flow with PKCE support | | Client Credentials | RFC 6749 | Machine-to-machine authentication | | Refresh Token | RFC 6749 | Token renewal flow | | Token Introspection | RFC 7662 | Active token metadata inspection | | Token Revocation | RFC 7009 | Token invalidation |
OpenID Connect
| Flow | Spec | Description | |------|------|-------------| | Authorization Code | OIDC Core | OAuth 2.0 + ID token for identity | | Hybrid Flow | OIDC Core | Immediate ID token + code exchange | | Discovery | OIDC Discovery | OpenID Provider metadata endpoint | | UserInfo | OIDC Core | User claims endpoint |
SAML 2.0
| Flow | Binding | Description | |------|---------|-------------| | SP-Initiated SSO | POST / Redirect | Service Provider starts authentication | | IdP-Initiated SSO | POST | Identity Provider starts authentication | | Single Logout (SLO) | POST / Redirect | Federated logout |
SPIFFE/SPIRE
| Flow | Description | |------|-------------| | X.509-SVID | Acquire X.509 certificate via Workload API | | JWT-SVID | Acquire JWT identity token | | mTLS Configuration | Automatic certificate rotation | | Trust Bundle | CA certificate distribution |
SPIFFE flows execute against real SPIRE infrastructure on protocolsoup.com.
SCIM 2.0
| Flow | RFC | Description | |------|-----|-------------| | User Lifecycle | RFC 7643/7644 | Create, read, update, delete users | | Group Management | RFC 7643/7644 | Group membership provisioning | | Filter Queries | RFC 7644 | SCIM filter syntax for searches | | Schema Discovery | RFC 7643 | Resource type and schema introspection |
Shared Signals Framework (SSF)
| Flow | Spec | Description | |------|------|-------------| | Stream Management | OpenID SSF | Create and configure event streams | | CAEP Events | CAEP | Session revocation, token revocation, credential change | | RISC Events | RISC | Account compromise, credential compromise indicators | | SET Delivery | RFC 8935 | Security Event Token push delivery |
Test Credentials
Demo users and client secrets are generated at startup unless provided via environment variables.
Environment overrides:
MOCKIDP_ALICE_PASSWORDMOCKIDP_BOB_PASSWORDMOCKIDP_ADMIN_PASSWORDMOCKIDP_DEMO_CLIENT_SECRETMOCKIDP_MACHINE_CLIENT_SECRET
You can fetch the current demo credentials from:
GET /oauth2/demo/usersGET /oauth2/demo/clientsGET /saml/demo/users
API Reference
OAuth 2.0
GET /oauth2/authorize Authorization endpoint
POST /oauth2/token Token endpoint
POST /oauth2/introspect Token introspection
POST /oauth2/revoke Token revocation
POST /oauth2/authorize Authorization form submit
OpenID Connect
GET /oidc/.well-known/openid-configuration Discovery document
GET /oidc/.well-known/jwks.json JSON Web Key Set
GET /oidc/authorize Authorization endpoint
POST /oidc/token Token endpoint
GET /oidc/userinfo UserInfo endpoint
SAML 2.0
GET /saml/metadata IdP Metadata (XML)
GET /saml/sso SSO Service (Redirect Binding)
POST /saml/sso SSO Service (POST Binding)
POST /saml/acs Assertion Consumer Service
GET /saml/slo Single Logout (Redirect)
POST /saml/slo Single Logout (POST)
SPIFFE/SPIRE
GET /spiffe/status Workload API status
GET /spiffe/svid/x509 X.509-SVID certificate
GET /spiffe/svid/x509/chain PEM certificate chain
GET /spiffe/svid/jwt?audience=<aud> JWT-SVID token
GET /spiffe/.well-known/spiffe-bundle SPIFFE bundle endpoint
GET /spiffe/trust-bundle Trust bundle details
GET /spiffe/workload Workload identity info
POST /spiffe/validate/jwt Validate JWT-SVID
POST /spiffe/validate/x509 Validate X.509-SVID
SCIM 2.0
GET /scim/v2/ServiceProviderConfig Service provider configuration
GET /scim/v2/ResourceTypes Available resource types
GET /scim/v2/Schemas Schema definitions
GET /scim/v2/Users List users (supports filtering)
POST /scim/v2/Users Create user
GET /scim/v2/Users/{id} Get user by ID
PUT /scim/v2/Users/{id} Replace user
PATCH /scim/v2/Users/{id} Partial update user
DELETE /scim/v2/Users/{id} Delete user
GET /scim/v2/Groups List groups
POST /scim/v2/Groups Create group
GET /scim/v2/Groups/{id} Get group by ID
PATCH /scim/v2/Groups/{id} Update group membership
DELETE /scim/v2/Groups/{id} Delete group
POST /scim/v2/Bulk Bulk operations
Shared Signals Framework (SSF)
GET /ssf/.well-known/ssf-configuration Transmitter configuration
GET /ssf/jwks Signing keys (JWKS)
POST /ssf/stream Create event stream
GET /ssf/stream/{id} Get stream configuration
PUT /ssf/stream/{id} Update stream
DELETE /ssf/stream/{id} Delete stream
POST /ssf/stream/{id}/subjects Add subject to stream
DELETE /ssf/stream/{id}/subjects/{subject} Remove subject
POST /ssf/stream/{id}/events Emit event to stream
GET /ssf/stream/{id}/events List stream events
POST /ssf/actions/{event-type} Trigger security event (demo)
GET /ssf/security-state/{email} User security state
GET /ssf/receiver/events List received events (proxy to 8081)
GET /ssf/receiver/status Receiver status (proxy to 8081)
GET /ssf/receiver/actions Response actions taken (proxy to 8081)
Internal API
GET /api/protocols List available protocols
POST /api/lookingglass/decode Decode tokens
WS /ws/lookingglass/{session} Real-time event stream
GET /health Health check
Project Structure
ProtocolSoup/
├── backend/
│ ├── cmd/server/main.go # Application entry point
│ └── internal/
│ ├── core/ # HTTP server, config, middleware
│ ├── crypto/ # JWT/JWK key management (RS256, ES256)
│ ├── lookingglass/ # Real-time protocol inspection engine
│ ├── mockidp/ # Mock identity provider (users, clients, sessions)
│ ├── plugin/ # Plugin system interfaces & lifecycle
│ ├── spiffe/ # SPIFFE Workload API client, mTLS utilities
│ └── protocols/
│ ├── oauth2/ # OAuth 2.0 implementation
│ ├── oidc/ # OpenID Connect (extends OAuth 2.0)
│ ├── saml/ # SAML 2.0 SSO & SLO
│ ├── scim/ # SCIM 2.0 user/group provisioning
│ ├── spiffe/ # SPIFFE/SPIRE handlers
│ ├── ssf/ # Shared Signals Framework
│ ├── oid4vci/ # OID4VCI credential issuance
│ └── oid4vp/ # OID4VP verifiable presentations
├── frontend/
│ └── src/
│ ├── components/ # Shared UI components
│ │ ├── common/ # Layout, navigation
│ │ └── lookingglass/ # Token inspector, flow diagrams, timeline
│ ├── lookingglass/ # Flow executors & visualization
│ │ └── flows/ # Protocol-specific executors
│ ├── pages/ # Route pages (Dashboard, LookingGlass, etc.)
│ ├── protocols/ # Protocol registry
│ └── hooks/ # WebSocket, state management
├── docker/
│ ├── docker-compose.yml # Split services (base)
│ ├── docker-compose.spiffe.yml # SPIFFE/SPIRE overlay
│ ├── docker-compose.simple.yml # Legacy monolith (no SPIFFE)
│ ├── docker-compose.dev.yml # Legacy development configuration
│ ├── docker-compose.prod.yml # Legacy production configuration
│ ├── spire/ # SPIRE server/agent configurations
│ └── Dockerfile.* # Container definitions
├── docs/
│ ├── ARCHITECTURE.md
