Quarkus OpenID SSF

Master kill switch for the SSF receiver. When false, all startup observers (validator, push route registration, transmitter probe, receiver-managed registrar, POLL scheduler) become no-ops and no inbound SETs are accepted or pulled. Other beans (SsfStreamClient, metrics, alias resolver) stay wired in CDI so application code that touches them directly still works — but nothing happens automatically.

Useful for %test.quarkus.openid-ssf.receiver.enabled=false or runtime kill-switch via env var. Defaults to true so existing apps upgrade without behavior change.

Note: transmitter-issuer() is still resolved by the config layer at startup, so even when disabled, set it to any non-empty URI (the value is never read in disabled mode).

Environment variable: QUARKUS_OPENID_SSF_RECEIVER_ENABLED

Issuer URL of the SSF transmitter (e.g. a Keycloak realm URL).

Environment variable: QUARKUS_OPENID_SSF_RECEIVER_TRANSMITTER_ISSUER

Expected aud value on inbound SETs. If set, the SET must contain a matching audience entry — otherwise it is rejected with 400. If absent, no audience check is performed.

Environment variable: QUARKUS_OPENID_SSF_RECEIVER_EXPECTED_AUDIENCE

Who owns the stream lifecycle. StreamManagement#RECEIVER (the default) means the extension performs a discover-or-create on startup — see ReceiverManaged — and is the most common shape for SSF receivers in practice. StreamManagement#TRANSMITTER means the operator pre-creates the stream in the transmitter’s admin console and pins the assigned stream-id() here.

Environment variable: QUARKUS_OPENID_SSF_RECEIVER_STREAM_MANAGEMENT

Stream id pinned by the operator. Required when stream-management() is StreamManagement#TRANSMITTER; optional in StreamManagement#RECEIVER mode (if set, the registrar skips its discover-or-create step and uses this id directly).

Environment variable: QUARKUS_OPENID_SSF_RECEIVER_STREAM_ID

How SETs are delivered. DeliveryMethod#PUSH (the default, RFC 8935) — the transmitter POSTs each SET to Push#endpointPath(). DeliveryMethod#POLL (RFC 8936) — the extension pulls SETs from the transmitter’s poll endpoint; see Poll.

Environment variable: QUARKUS_OPENID_SSF_RECEIVER_DELIVERY_METHOD

Path of the push endpoint, relative to quarkus.http.root-path.

Environment variable: QUARKUS_OPENID_SSF_RECEIVER_PUSH_ENDPOINT_PATH

If set, the push endpoint requires this exact value in the inbound Authorization header.

Environment variable: QUARKUS_OPENID_SSF_RECEIVER_PUSH_EXPECTED_AUTH_HEADER

Externally-reachable URL of the push endpoint, advertised to the transmitter as delivery.endpoint_url in the create-stream request. Required when stream-management=RECEIVER; ignored otherwise.

Environment variable: QUARKUS_OPENID_SSF_RECEIVER_PUSH_DELIVERY_ENDPOINT_URL

Poll endpoint URL. Optional override; if absent, the extension reads it from the stream’s delivery.endpoint_url via the configuration_endpoint on startup. Per RFC 8936, this URL is advertised by the transmitter — receivers normally don’t pin it.

Environment variable: QUARKUS_OPENID_SSF_RECEIVER_POLL_ENDPOINT_URL

If true (the default), the poller schedules a periodic Vert.x timer on startup. Set to false to keep the poller idle — application code drives polling explicitly via SsfPoller.pollNow() (e.g. behind a REST endpoint, a scheduled job, or a Kafka consumer trigger).

Environment variable: QUARKUS_OPENID_SSF_RECEIVER_POLL_AUTO_START

Delay before the first poll fires after startup. Useful when other components need to warm up first (DB pool, config server, …). Defaults to 0s — poll immediately.

Environment variable: QUARKUS_OPENID_SSF_RECEIVER_POLL_START_DELAY

How often to poll the transmitter. Defaults to 30s.

Environment variable: QUARKUS_OPENID_SSF_RECEIVER_POLL_INTERVAL

maxEvents parameter sent on each poll request (RFC 8936 §2.1). Defaults to 100.

Environment variable: QUARKUS_OPENID_SSF_RECEIVER_POLL_MAX_EVENTS

returnImmediately parameter (RFC 8936 §2.1). When false, the transmitter holds the request open until events are available (long-poll). Defaults to true.

Environment variable: QUARKUS_OPENID_SSF_RECEIVER_POLL_RETURN_IMMEDIATELY

If true and the transmitter sets moreAvailable=true, keep polling synchronously until the queue drains rather than waiting for the next periodic tick. Defaults to true.

Environment variable: QUARKUS_OPENID_SSF_RECEIVER_POLL_DRAIN_ON_POLL

Connect/read timeout for outbound poll requests. Defaults to 30s.

Environment variable: QUARKUS_OPENID_SSF_RECEIVER_POLL_TIMEOUT

If true, the extension performs a discover-or-create dance on app startup: it lists the receiver’s existing streams on the transmitter (§7.1.1.2 with no stream_id), reuses one whose delivery.endpoint_url (or audience) matches this receiver, and creates a new stream if none matches. Defaults to true.

Set to false to manage stream lifecycle entirely from application code (e.g. via SsfStreamClient.createStream).

Environment variable: QUARKUS_OPENID_SSF_RECEIVER_RECEIVER_MANAGED_REGISTER_STREAM

If true, the extension issues a stream-delete call against the transmitter on app shutdown so the transmitter doesn’t accumulate stale stream registrations from short-lived receivers (dev mode, tests, …). Defaults to false so a normal restart keeps the existing stream.

Environment variable: QUARKUS_OPENID_SSF_RECEIVER_RECEIVER_MANAGED_DELETE_ON_SHUTDOWN

Optional human-readable description sent in the create-stream request.

Environment variable: QUARKUS_OPENID_SSF_RECEIVER_RECEIVER_MANAGED_DESCRIPTION

Master switch for the jti dedup layer. When true (the default), the extension consults SsfJtiDedupStore.seenBefore(jti) before invoking the application’s SsfEventHandler on both PUSH and POLL paths; duplicates are silently dropped (still 202 on PUSH, still acked on POLL — the SET was successfully received).

Set to false when the application’s handler is naturally idempotent (e.g. natural-key upsert into a database) and the extra lookup is wasted work.

Environment variable: QUARKUS_OPENID_SSF_RECEIVER_DEDUP_ENABLED

Capacity of the default in-memory dedup store. Overflow evicts the oldest jti. Tune to roughly cover the longest expected redelivery window — defaults to 10_000, which on a typical SSF stream (a few events per second peak) is several minutes of memory.

Ignored by custom SsfJtiDedupStore implementations.

Environment variable: QUARKUS_OPENID_SSF_RECEIVER_DEDUP_CAPACITY

Allowed JWS alg values on inbound SETs. Any SET whose header advertises an algorithm outside this list is rejected before signature verification — defense against alg-substitution attacks. Default is [RS256] (CAEP Interop §3.1).

Environment variable: QUARKUS_OPENID_SSF_RECEIVER_SET_VALIDATION_ACCEPTED_ALGORITHMS

Minimum RSA key size, in bits, accepted for SET signature verification. SETs signed with an RSA JWK whose modulus is shorter than this are rejected. Default is 2048 (CAEP Interop §3.1). Set to 0 to disable the check (not recommended).

Environment variable: QUARKUS_OPENID_SSF_RECEIVER_SET_VALIDATION_MIN_RSA_KEY_SIZE

If true (the default), on startup the extension fetches the configured stream’s configuration and status from the transmitter and logs a one-line summary — useful for confirming the stream exists and is enabled. Probe failures are warnings, never fatal.

Set to false when the receiver doesn’t have outbound credentials configured (push-only with public JWKS), or to keep boot silent.

Environment variable: QUARKUS_OPENID_SSF_RECEIVER_TRANSMITTER_MANAGED_PROBE_ON_STARTUP

Explicit URL of the transmitter’s SSF metadata document.

If unset, the URL is derived from transmitter-issuer() per SSF spec §7.2 — /.well-known/ssf-configuration is inserted between the host and the path of the issuer (NOT appended to the end). For example:

Set this property explicitly when the transmitter doesn’t follow the SSF rule — for example, OIDC-derived transmitters that serve the document at the OIDC-style appended path (<issuer>/.well-known/ssf-configuration) instead.

Environment variable: QUARKUS_OPENID_SSF_RECEIVER_TRANSMITTER_METADATA_URL

JWKS URL of the transmitter. Defaults to the jwks_uri advertised in transmitter metadata.

Environment variable: QUARKUS_OPENID_SSF_RECEIVER_TRANSMITTER_JWKS_URL

Static bearer access token to send on outbound calls to the transmitter. If set, the deployment processor registers a StaticTransmitterTokenProvider instead of the OIDC-backed one — useful for transmitters such as caep.dev that issue long-lived bearer tokens out-of-band rather than via an OAuth grant. Mutually exclusive with quarkus-oidc-client; when both are configured this token wins.

Environment variable: QUARKUS_OPENID_SSF_RECEIVER_TRANSMITTER_ACCESS_TOKEN

Event types this receiver wants to subscribe to. Required when stream-management() is StreamManagement#RECEIVER (sent in the events_requested field of the create-stream request). Informational for transmitter-managed streams — the transmitter (e.g. Keycloak admin) already controls the actual subscription set.

Each entry can be a full URI (e.g. https://schemas.openid.net/secevent/caep/event-type/session-revoked) or a short alias registered with event-aliases() event-aliases — including the SSF / CAEP / RISC built-ins (e.g. CaepSessionRevoked, RiscAccountDisabled). Resolution is performed by io.quarkiverse.ssf.receiver.runtime.event.SsfAliases#resolveEventTypeRef(String) at startup; an unregistered name fails fast with a list of available aliases.

Example:

Environment variable: QUARKUS_OPENID_SSF_RECEIVER_EVENTS_REQUESTED

Short aliases for event-type URIs — used as the event tag value on the ssf.receiver.events.processed meter and as accepted input to events-requested(). Keyed by alias, valued by URI:

Built-in aliases for the OpenID SSF, CAEP 1.0, and RISC 1.0 spec event types are always registered out of the box (e.g. SsfStreamVerification, CaepSessionRevoked, RiscAccountDisabled, …); user entries with the same URI override the built-in alias name. Unknown URIs fall back to the URI itself as the tag value.

Environment variable: QUARKUS_OPENID_SSF_RECEIVER_EVENT_ALIASES__EVENT_ALIASES_

Short aliases for transmitter issuer URLs — used as the iss tag value on the ssf.receiver.events.processed meter. Keyed by alias, valued by issuer URL:

No built-in defaults — issuer URLs are deployment-specific. Unknown URLs fall back to the URL itself as the tag value.

Environment variable: QUARKUS_OPENID_SSF_RECEIVER_ISSUER_ALIASES__ISSUER_ALIASES_

Short, stable name for this receiver — surfaced as the receiver tag on the ssf.receiver.events.processed meter so multiple receiver instances scraping into the same monitoring store stay distinguishable.

Falls back to expected-audience() if unset, then to "unknown".

Environment variable: QUARKUS_OPENID_SSF_RECEIVER_ALIAS

Token endpoint URL where the OAuth2 grant is exchanged. Setting this activates the OAuth2 provider; leaving it empty falls through to the OIDC / no-op providers.

Environment variable: QUARKUS_OPENID_SSF_RECEIVER_OAUTH2_TOKEN_ENDPOINT

OAuth2 grant type sent in the grant_type form parameter. Default is client_credentials (RFC 6749 §4.4) — the only grant the receiver needs for outbound transmitter calls. Override for non-standard or extension grants (e.g. urn:ietf:params:oauth:grant-type:jwt-bearer).

Environment variable: QUARKUS_OPENID_SSF_RECEIVER_OAUTH2_GRANT_TYPE

Which client-authentication method to use when sending the client-id() / client-secret() pair. RFC 6749 §2.3.1 defines two:

Environment variable: QUARKUS_OPENID_SSF_RECEIVER_OAUTH2_CLIENT_AUTH_METHOD

OAuth2 client identifier. Sent in the client_id form parameter when client-auth-method() is post, or as the basic-auth username when basic.

Environment variable: QUARKUS_OPENID_SSF_RECEIVER_OAUTH2_CLIENT_ID

OAuth2 client secret. Sent in the client_secret form parameter when client-auth-method() is post, or as the basic-auth password when basic.

Environment variable: QUARKUS_OPENID_SSF_RECEIVER_OAUTH2_CLIENT_SECRET

Optional space-separated scope request parameter. List form in config (e.g. quarkus.openid-ssf.receiver.oauth2.scopes=ssf.read,ssf.manage); the values are joined with single spaces on the wire.

Environment variable: QUARKUS_OPENID_SSF_RECEIVER_OAUTH2_SCOPES

Extra form parameters appended verbatim to the token-endpoint POST. Escape hatch for server-specific extensions (e.g. resource= on Microsoft Entra, vendor-specific tenant identifiers, etc.).

Environment variable: QUARKUS_OPENID_SSF_RECEIVER_OAUTH2_ADDITIONAL_PARAMS__ADDITIONAL_PARAMS_

Subtracted from the token endpoint’s reported expires_in before the provider treats a cached token as expired. Default is 30s, which covers typical clock skew + the duration of the outbound call the token is about to authenticate.

Environment variable: QUARKUS_OPENID_SSF_RECEIVER_OAUTH2_EXPIRY_SAFETY_WINDOW

Connect / read timeout for the token endpoint POST. Default is 5s.

Environment variable: QUARKUS_OPENID_SSF_RECEIVER_OAUTH2_TIMEOUT

Maximum time to wait when fetching an access token from OidcClient.getTokens() for outbound calls to the transmitter. Bounds the Uni.await().atMost(…​) on the call site so a slow / unresponsive OIDC token endpoint doesn’t stall a Vert.x event loop indefinitely. Defaults to 2s.

Environment variable: QUARKUS_OPENID_SSF_RECEIVER_OIDC_TOKEN_TIMEOUT