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	Redis is required in production for OAuth client-assertion replay protection

Protocol Endpoints

OAuth 2.0

• GET|POST /oauth2/authorize, POST /oauth2/token
• POST /oauth2/introspect (RFC 7662; confidential client, or Bearer of the token being introspected), POST /oauth2/revoke
• GET /oauth2/demo/users, GET /oauth2/demo/clients
• POST /oauth2/demo/clients/machine-client-pkjwt/jwks (owned, active-session, one-shot public-key registration)
• POST /oauth2/demo/caep/revoke-subject (SSF CAEP session-revoked hook; bearer SSF_TO_FEDERATION_TOKEN)
• /oauth2/token optionally accepts a DPoP proof header (RFC 9449), binding the issued access token (and, for authorization_code public clients, the refresh token) to the proof’s key
• Client credentials tokens with ssf.read / ssf.manage last 900 seconds and carry aud = SSF_RESOURCE (default SHOWCASE_BASE_URL)
• Seeded confidential client ssf-stream-client (client_credentials, ssf.read / ssf.manage); secret from SSF_STREAM_CLIENT_SECRET or auto-generated, listed at 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
• /oid4vci/token optionally accepts a DPoP proof header (RFC 9449), enforced at /oid4vci/credential, /oid4vci/nonce, and /oid4vci/deferred_credential when a token is bound

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 and redirect URIs; production requires a pathless HTTPS origin
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
OAUTH2_REPLAY_REDIS_URL	Demo and production	In-memory in development/tests	Shared replay store. Production requires a reachable rediss:// secret; demo may use redis:// on a private local network. Also backs the RFC 9449 DPoP proof jti replay stores for both oauth2 and OID4VCI.
SHOWCASE_DPOP_NONCE_REQUIRED	No	false	Enables the RFC 9449 §8 nonce challenge at oauth2’s /oauth2/token and OID4VCI’s own /oid4vci/token.
SHOWCASE_DPOP_RESOURCE_NONCE_REQUIRED	No	false	Enables the same challenge, independently, at OID4VCI’s resource-server endpoints.
SSF_RESOURCE	No	SHOWCASE_BASE_URL	Audience written into ssf.read / ssf.manage client-credentials tokens
SSF_STREAM_CLIENT_SECRET	No	auto-generated	Secret for the seeded ssf-stream-client Stream Management client. Pin in production so the secret survives restarts.
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.
• In production, keep SHOWCASE_BASE_URL pathless with no trailing slash and configure OAUTH2_REPLAY_REDIS_URL as a TLS-protected secret. OAuth token requests fail closed if replay storage is unavailable.
• 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.