Quarkus OpenID SSF

Master kill switch for the SSF receiver. When false, no push endpoint is registered, no stream is looked up or registered and no transmitter is polled. The beans of the extension stay injectable, but need a configured transmitter to do anything.

Environment variable: QUARKUS_OPENID_SSF_RECEIVER_ENABLED

Issuer of the SSF transmitter, for example a Keycloak realm URL. Every inbound SET must carry this value as its iss claim. It must use https, or http on a loopback address, see allow-insecure-http().

Environment variable: QUARKUS_OPENID_SSF_RECEIVER_TRANSMITTER_ISSUER

Location of the transmitter’s SSF configuration metadata.

If unset, the URL is derived from transmitter-issuer() per SSF 1.0 section 7.2: /.well-known/ssf-configuration is inserted between the host and the path of the issuer, so https://tr.example.com/realms/r1 is looked up at https://tr.example.com/.well-known/ssf-configuration/realms/r1. As transmitters that grew out of OpenID providers tend to append it instead (https://tr.example.com/realms/r1/.well-known/ssf-configuration), that location is tried as a fallback.

Environment variable: QUARKUS_OPENID_SSF_RECEIVER_TRANSMITTER_METADATA_URL

Location of the JWK Set used to verify SET signatures. Discovered from the transmitter metadata (jwks_uri) when not set.

Environment variable: QUARKUS_OPENID_SSF_RECEIVER_TRANSMITTER_JWKS_URL

Whether the transmitter issuer and the endpoints it publishes may use plain http on hosts other than loopback addresses. For test setups only, SSF requires https: the metadata of the transmitter decides where keys come from, and without TLS anyone on the path can change it.

Environment variable: QUARKUS_OPENID_SSF_RECEIVER_ALLOW_INSECURE_HTTP

Audience this receiver is known as at the transmitter. When set, every inbound SET must contain it in its aud claim. When not set, the audience of the stream the receiver registers or looks up on startup (stream-management=RECEIVER, stream-id) is required instead, once the stream is known; until then a pushed SET is answered with 503 and a polled one left unacknowledged, so that the transmitter delivers it again. One of the two, or set-validation.allow-any-audience, is required: a receiver that cannot know the audience of its SETs does not start, as it would accept SETs the transmitter issued for other receivers.

Environment variable: QUARKUS_OPENID_SSF_RECEIVER_EXPECTED_AUDIENCE

Who manages the stream. RECEIVER (the default): the extension looks the stream of this receiver up on startup and creates or updates it if necessary. TRANSMITTER: the stream is created at the transmitter and its identifier is pinned with stream-id(); without a stream id the receiver does not call the stream management API on startup at all.

Environment variable: QUARKUS_OPENID_SSF_RECEIVER_STREAM_MANAGEMENT

Identifier of a stream that was created at the transmitter. When set, the stream is looked up on startup to learn its audience and poll endpoint.

Environment variable: QUARKUS_OPENID_SSF_RECEIVER_STREAM_ID

How SETs are delivered. PUSH (the default, RFC 8935): the transmitter posts each SET to the push endpoint of this application. POLL (RFC 8936): the extension fetches SETs from the poll endpoint of the transmitter, see poll().

Environment variable: QUARKUS_OPENID_SSF_RECEIVER_DELIVERY_METHOD

Event types this receiver wants to subscribe to, as a full URI or an alias (the built-in aliases of the SSF, CAEP, RISC and SCIM event types, CaepSessionRevoked, RiscAccountDisabled, ScimProvCreateFull, …​ or one of event-aliases). Required for a stream managed by the receiver, where it becomes events_requested; informational for a transmitter-managed one.

Environment variable: QUARKUS_OPENID_SSF_RECEIVER_EVENTS_REQUESTED

Static bearer access token to send on calls to the transmitter, for transmitters such as caep.dev that hand out long-lived tokens out-of-band. Takes precedence over oauth2() and the OIDC client.

Environment variable: QUARKUS_OPENID_SSF_RECEIVER_TRANSMITTER_ACCESS_TOKEN

Exact value the transmitter must send in the Authorization header, for example Bearer s3cr3t. No header check is performed when not set.

Environment variable: QUARKUS_OPENID_SSF_RECEIVER_PUSH_EXPECTED_AUTH_HEADER

URL under which the transmitter reaches the push endpoint of this application, advertised as delivery.endpoint_url of a stream managed by the receiver. Required with stream-management=RECEIVER and PUSH delivery.

Environment variable: QUARKUS_OPENID_SSF_RECEIVER_PUSH_DELIVERY_ENDPOINT_URL

Poll endpoint of the transmitter. Taken from the configuration of the stream when not set, which needs the stream to be looked up or managed on startup.

Environment variable: QUARKUS_OPENID_SSF_RECEIVER_POLL_ENDPOINT_URL

Whether the transmitter is polled by the extension, on a virtual thread of its own per transmitter: every interval, or with one request outstanding when long-polling is on. Set to false to drive polling from application code with SsfPollScheduler.pollNow().

Environment variable: QUARKUS_OPENID_SSF_RECEIVER_POLL_AUTO_START

Time to wait before the first poll after startup.

Environment variable: QUARKUS_OPENID_SSF_RECEIVER_POLL_START_DELAY

Time between two polls. With long-polling, the pause after a failed request, or after a transmitter that does not hold requests answered an empty one at once. The first poll follows the registration of the stream at once.

Environment variable: QUARKUS_OPENID_SSF_RECEIVER_POLL_INTERVAL

Long polling (RFC 8936, section 2.5): the poller keeps one request outstanding that the transmitter holds until SETs are available or long-polling-hold elapses, instead of asking every interval whether there is something. A SET is then fetched as soon as the transmitter has it. The transmitter has to support long polling; one that answers at once is polled every interval as with false.

Environment variable: QUARKUS_OPENID_SSF_RECEIVER_POLL_LONG_POLLING

How long the transmitter holds a long poll request, part of the agreement with it (RFC 8936, section 2.2). The request waits that long plus a margin for the response, http.read-timeout does not apply to it.

Environment variable: QUARKUS_OPENID_SSF_RECEIVER_POLL_LONG_POLLING_HOLD

Maximum number of SETs to fetch with one request (maxEvents, RFC 8936).

Environment variable: QUARKUS_OPENID_SSF_RECEIVER_POLL_MAX_EVENTS

Pause after a 429 without a Retry-After header. Not set: poll again at the regular interval.

Environment variable: QUARKUS_OPENID_SSF_RECEIVER_POLL_RATE_LIMIT_FALLBACK_BACKOFF

Longest pause a Retry-After header or fallback-backoff can cause. Protects the receiver from a transmitter that asks it to stay away for hours.

Environment variable: QUARKUS_OPENID_SSF_RECEIVER_POLL_RATE_LIMIT_MAX_BACKOFF

Whether the stream managed by the receiver is deleted at the transmitter when the application stops, so that short-lived receivers (dev mode, tests) do not leave streams behind. false keeps the stream across restarts.

Environment variable: QUARKUS_OPENID_SSF_RECEIVER_RECEIVER_MANAGED_DELETE_ON_SHUTDOWN

Description of the stream managed by the receiver.

Environment variable: QUARKUS_OPENID_SSF_RECEIVER_RECEIVER_MANAGED_DESCRIPTION

JWS algorithms accepted for SET signatures. Only asymmetric signature algorithms are allowed. A SET signed with another algorithm is rejected.

Environment variable: QUARKUS_OPENID_SSF_RECEIVER_SET_VALIDATION_ACCEPTED_ALGORITHMS

Minimum RSA key size in bits for SET signing keys. 0 disables the check.

Environment variable: QUARKUS_OPENID_SSF_RECEIVER_SET_VALIDATION_MIN_RSA_KEY_SIZE

Whether a SET must be explicitly typed with a typ header of secevent+jwt.

Environment variable: QUARKUS_OPENID_SSF_RECEIVER_SET_VALIDATION_REQUIRE_TYPE_HEADER

How strictly the subject of a SET is validated: strict-ssf-1-0 requires the top-level sub_id claim of SSF 1.0, legacy accepts SETs of transmitters following earlier drafts, which put the subject into the event payload.

Environment variable: QUARKUS_OPENID_SSF_RECEIVER_SET_VALIDATION_SUBJECT_COMPATIBILITY

Tolerated clock skew when checking that a SET was not issued in the future.

Environment variable: QUARKUS_OPENID_SSF_RECEIVER_SET_VALIDATION_CLOCK_SKEW

Accepts SETs whatever audience they carry when neither expected-audience is set nor a stream is registered or looked up (stream-management, stream-id) that tells the audience, with a warning on startup. Off by default: a receiver without a known audience fails to start, because it would accept SETs the transmitter issued for other receivers. Only for a transmitter that sends no aud.

Environment variable: QUARKUS_OPENID_SSF_RECEIVER_SET_VALIDATION_ALLOW_ANY_AUDIENCE

Token endpoint to obtain access tokens from with the client credentials grant. Setting it activates this provider.

Environment variable: QUARKUS_OPENID_SSF_RECEIVER_OAUTH2_TOKEN_ENDPOINT

Client id of this receiver.

Environment variable: QUARKUS_OPENID_SSF_RECEIVER_OAUTH2_CLIENT_ID

Client secret of this receiver.

Environment variable: QUARKUS_OPENID_SSF_RECEIVER_OAUTH2_CLIENT_SECRET

Scopes to request, sent space-separated in the scope parameter.

Environment variable: QUARKUS_OPENID_SSF_RECEIVER_OAUTH2_SCOPES

How the client authenticates at the token endpoint: basic (client_secret_basic, the default) or post (client_secret_post, credentials in the form body).

Environment variable: QUARKUS_OPENID_SSF_RECEIVER_OAUTH2_CLIENT_AUTH_METHOD

Form parameters to send with the token request in addition to the grant, for extensions of the token endpoint.

Environment variable: QUARKUS_OPENID_SSF_RECEIVER_OAUTH2_ADDITIONAL_PARAMS__PARAMETER_

How long before its expiry an access token is renewed; never more than a quarter of the token’s lifetime.

Environment variable: QUARKUS_OPENID_SSF_RECEIVER_OAUTH2_EXPIRY_SAFETY_WINDOW

Name of the OIDC client (quarkus.oidc-client.<name>.*) to obtain access tokens from. The default client (quarkus.oidc-client.*) when not set.

Environment variable: QUARKUS_OPENID_SSF_RECEIVER_OIDC_CLIENT_NAME

Maximum time to wait for an access token from the OIDC client.

Environment variable: QUARKUS_OPENID_SSF_RECEIVER_OIDC_TOKEN_TIMEOUT

Aliases for event type URIs, usable wherever an event type is named: in events-requested, in handlers (eventContext.hasEvent("AcmeLogin")) and as the event tag of the metrics. Keyed by alias, valued by URI:

They add to the built-in aliases of the SSF, CAEP, RISC and SCIM event types (for example CaepSessionRevoked, RiscAccountDisabled, ScimProvCreateFull) and cannot redefine one; a conflicting alias fails the start.

Environment variable: QUARKUS_OPENID_SSF_RECEIVER_EVENT_ALIASES__ALIAS_

The members of a complex subject the application interprets. A transmitter can declare members critical (critical_subject_members in its metadata); a SET whose subject has such a member that is not listed here is rejected as invalid_request, as the SSF specification requires critical members to be interpreted by the receiver. Defaults to the members SsfSubject gives access to.

Environment variable: QUARKUS_OPENID_SSF_RECEIVER_UNDERSTOOD_SUBJECT_MEMBERS

Path of the push endpoint, relative to quarkus.http.root-path. The transmitters with delivery-method=PUSH post their SETs there; which transmitter sent a SET is told by its issuer.

Environment variable: QUARKUS_OPENID_SSF_RECEIVER_PUSH_ENDPOINT_PATH

Connect timeout for calls to the transmitters.

Environment variable: QUARKUS_OPENID_SSF_RECEIVER_HTTP_CONNECT_TIMEOUT

Read timeout for calls to the transmitters: how long to wait for the response to a metadata, JWK Set, stream management, token or poll request.

Environment variable: QUARKUS_OPENID_SSF_RECEIVER_HTTP_READ_TIMEOUT

User-Agent header for calls to the transmitters. The default of the JDK HTTP client (Java-http-client/<version>) is sent when not set.

Environment variable: QUARKUS_OPENID_SSF_RECEIVER_HTTP_USER_AGENT

Whether SETs that were already processed are skipped. A SET that was processed before is acknowledged (202 on PUSH, acknowledged on POLL) without invoking the handlers again. Set to false when the handlers are idempotent anyway.

Environment variable: QUARKUS_OPENID_SSF_RECEIVER_DEDUP_ENABLED

Number of SET identifiers the in-memory store remembers. Overflow evicts the oldest. Ignored by a JDBC store or a custom SsfJtiDedupStore bean.

Environment variable: QUARKUS_OPENID_SSF_RECEIVER_DEDUP_CAPACITY

How long the JDBC store remembers a processed SET. Has to cover the time the transmitter keeps trying to deliver a SET.

Environment variable: QUARKUS_OPENID_SSF_RECEIVER_DEDUP_RETENTION

How long a SET counts as being handled by the instance that claimed it without renewing the claim, which it does every third of this time while its handlers run. A SET is claimed in the store before the handlers run and marked processed afterwards; another instance that receives the same SET meanwhile neither handles nor acknowledges it, the transmitter delivers it again. A claim that was not renewed for the lease counts as abandoned by an instance that crashed, and the SET is handled again.

Environment variable: QUARKUS_OPENID_SSF_RECEIVER_DEDUP_LEASE

Whether the state of the receiver is kept in the default datasource of the application, if it has one (quarkus-agroal), so that all instances of the application share it and it survives a restart: the processed SETs (<prefix>PROCESSED_SET) and, with POLL delivery, the acknowledgements a poller owes its transmitter (<prefix>POLL_ACK). Otherwise both are kept in memory.

Environment variable: QUARKUS_OPENID_SSF_RECEIVER_JDBC_ENABLED

Whether the tables are created at startup if they do not exist, and columns a release added are added to an existing table. With false the tables have to be created with the statements in classpath:org/easyssf/receiver/jdbc/schema.sql (a fresh installation) or the versioned scripts in classpath:org/easyssf/receiver/jdbc/migration/ (Flyway naming, plain SQL), for example by a schema migration, and the start fails naming the statements to run if a table or a column is missing.

Environment variable: QUARKUS_OPENID_SSF_RECEIVER_JDBC_INITIALIZE_SCHEMA

Prefix of the names of the tables.

Environment variable: QUARKUS_OPENID_SSF_RECEIVER_JDBC_TABLE_PREFIX

How often expired rows (processed SETs past dedup.retention, acknowledgements past jdbc.ack-retention) are purged. The stores also purge when they are written to; 0 turns the periodic cleanup off.

Environment variable: QUARKUS_OPENID_SSF_RECEIVER_JDBC_CLEANUP_INTERVAL

How long an acknowledgement or error report the transmitter never accepted is kept in the <prefix>POLL_ACK table.

Environment variable: QUARKUS_OPENID_SSF_RECEIVER_JDBC_ACK_RETENTION

How many acknowledgements one DELETE statement removes from the <prefix>POLL_ACK table (JTI IN (…​)). Databases limit the number of parameters of a statement (SQL Server to 2100, Oracle to 1000 list members); a smaller batch means more statements per poll.

Environment variable: QUARKUS_OPENID_SSF_RECEIVER_JDBC_ACK_DELETE_BATCH_SIZE