Federation

Federation (`protocolsoup-federation`)

Image: ghcr.io/parlesec/protocolsoup-federation

When To Use

Use federation when you need OAuth 2.0, OIDC, SAML 2.0, OID4VCI, and OID4VP in a single service. This is the most protocol-rich image in ProtocolSoup.

Runtime Contract

Property	Value
Port	`8080`
Health	`GET /health`
API index	`GET /api`
Storage	File-based (optional persistent volume)
Database	None required

Protocol Endpoints

OAuth 2.0

GET|POST /oauth2/authorize, POST /oauth2/token
POST /oauth2/introspect, POST /oauth2/revoke
GET /oauth2/demo/users, GET /oauth2/demo/clients

OIDC

GET /oidc/.well-known/openid-configuration
GET /oidc/.well-known/jwks.json
GET|POST /oidc/authorize, POST /oidc/token, GET|POST /oidc/userinfo

SAML

GET /saml/metadata, GET|POST /saml/sso, GET|POST /saml/acs, GET|POST /saml/slo

OID4VCI

GET /oid4vci/.well-known/openid-credential-issuer
POST /oid4vci/offers/pre-authorized, POST /oid4vci/token
POST /oid4vci/credential, POST /oid4vci/deferred_credential

OID4VP

POST /oid4vp/request/create, GET|POST /oid4vp/request/{requestID}
GET /oid4vp/verifier-attestation/.well-known/openid-configuration, GET /oid4vp/verifier-attestation/.well-known/oauth-authorization-server, GET /oid4vp/verifier-attestation/jwks
POST /oid4vp/response, GET /oid4vp/result/{requestID}

Configuration

Variable	Required	Default	Description
`SHOWCASE_BASE_URL`	Yes	`http://localhost:8080`	External URL for issuer metadata, redirect URIs
`SHOWCASE_CORS_ORIGINS`	No	`http://localhost:3000,http://localhost:5173`	Allowed browser origins
`SHOWCASE_MOCK_IDP`	No	`true`	Enable built-in identity provider
`SHOWCASE_DATA_DIR`	No	-	Persistent storage for VC/session state
`SHOWCASE_ENV`	No	`development`	Environment mode
`OID4VP_VERIFIER_ATTESTATION_ISSUER`	No	`<SHOWCASE_BASE_URL>/oid4vp/verifier-attestation`	Issuer URL exposed for `verifier_attestation` metadata and JWKS
`OID4VP_VERIFIER_ATTESTATION_CLIENT_ID`	No	`verifier_attestation:<public-host>`	Verifier client ID used when `client_id_scheme=verifier_attestation`
`OID4VP_VERIFIER_ATTESTATION_PRIVATE_KEY_PEM`	No	Ephemeral in-memory key	PEM-encoded stable signing key for verifier attestation JWTs and JWKS
`OID4VP_X509_SANDNS_CLIENT_ID`	No	`x509_san_dns:<public-host>`	`x509_san_dns` verifier identifier; must match a DNS SAN in the leaf certificate
`OID4VP_X509_SANDNS_CERT_CHAIN_PEM`	No	Ephemeral self-signed chain	PEM-encoded certificate chain for `x509_san_dns` request signing. When unset, an ephemeral CA + leaf chain is auto-generated at startup.
`OID4VP_X509_SANDNS_PRIVATE_KEY_PEM`	No	Ephemeral key	PEM-encoded private key matching the leaf certificate. When unset, generated alongside the ephemeral chain.

Run

docker run -p 8080:8080 \
  -e SHOWCASE_BASE_URL=http://localhost:8080 \
  ghcr.io/parlesec/protocolsoup-federation:latest

With persistent storage:

docker run -p 8080:8080 \
  -e SHOWCASE_BASE_URL=http://localhost:8080 \
  -e SHOWCASE_DATA_DIR=/app/data \
  -v federation-data:/app/data \
  ghcr.io/parlesec/protocolsoup-federation:latest

Operational Notes

SHOWCASE_BASE_URL must match your external URL. OIDC discovery, SAML metadata, and OID4VCI issuer metadata all derive from this value.
Mock IdP is enabled by default. It provides demo users and clients for flow execution.
Mount persistent storage if you need VC credential and session continuity across restarts.
Pair with gateway for unified routing in multi-service deployments.
OID4VP verifier identities support redirect_uri, did:web, verifier_attestation, and x509_san_dns. Both verifier_attestation and x509_san_dns auto-provision ephemeral keys/certificates when their PEM env vars are unset.
Set OID4VP_VERIFIER_ATTESTATION_PRIVATE_KEY_PEM in production so verifier attestation JWKS and signed request objects remain verifiable across restarts and deploys.
Set OID4VP_X509_SANDNS_CERT_CHAIN_PEM and OID4VP_X509_SANDNS_PRIVATE_KEY_PEM in production for stable x509_san_dns certificate continuity.