Shared Signals (SSF, CAEP and RISC)
iya-sts is a Shared Signals transmitter (OpenID SSF 1.0), and a small receiver as well. A receiver agrees a stream with it, and it then delivers a Security Event Token (RFC 8417) when something happens, by push (RFC 8935) or poll (RFC 8936). Subjects use the RFC 9493 formats. Both vocabularies that run over SSF are implemented: CAEP 1.0 (what happened to a session) and RISC 1.0 (what happened to an account). Every trust realm has its own transmitter, streams, queues and registers.
Every other protocol here answers a request. This is the one that talks back: it sends an event that nobody asked for, at the moment the event happens.
Features
SSF is the pipe, not the vocabulary
SSF covers how a receiver and a transmitter agree a stream, who the events on it are about, what the events travel in and how they are delivered. It defines only two events of its own, and both are about the pipe:
- verification: the receiver asked whether the stream is alive, and the answer comes back along the normal delivery path. This is the only end-to-end test a stream has. A 200 from the management API means the configuration was accepted. It says nothing about whether an event can reach the receiver.
- stream updated: the stream’s status changed, and the receiver is told in band. A receiver does not have to ask for this event to get it.
The vocabularies run over that pipe:
| Vocabulary | Events | About | Emitted on its own when |
|---|---|---|---|
| CAEP | 8 | a session | someone signs in, uses single sign-on, signs out, a session expires, a person re-authenticates at a different acr, any credential of a person or an application changes, a directory change moves a claim of somebody (or an application) holding live tokens, a registered device’s compliance, risk level or credentials change, a SPIFFE registration entry is removed |
| RISC | 14 | an account | a person or an application entry is deleted; a person is disabled or enabled; any mail address or telephone number changes or is removed, or is given to an account after another released it; the recovery address is added, changed, removed or verified; an administrator resets a password (optionally marking it compromised) or issues a reset or activation link, or sets pwdReset over LDAP; recovery codes are cleared, confirmed or used; the account holder opts out or back in on /portal/signals; a person’s registered device is compromised or removed; this service detects a compromised credential (below) |
Since #164 every CAEP and RISC event type has an act here that sends it: a
registered device’s compliance changing (device-compliance-change), its risk
level changing (risk-level-change, principal DEVICE), its keys and Native
SSO secret changing (credential-change), and a person’s device compromised or
removed (RISC credential-compromise, and the deprecated sessions-revoked
where risc.autoEmitTypes names it, with the device beside the person in the
subject). Devices lists
each. You can still emit any of them by hand from the console or the
management API.
CAEP events covers what triggers each CAEP event.
A compromised credential this service detects is RISC
credential-compromise
(#231):
| What is detected | credential_type |
Also sent |
|---|---|---|
a password that signs in and appears in a data breach (risk.breachCheckAtSignIn) |
password |
account-credential-change-required, once until the password is changed |
| a security key whose signature counter went backwards (a clone) | fido2-roaming or fido2-platform |
nothing more; the person’s risk standing goes to HIGH. The risk-response policy’s own credential-compromise reaction to that standing is not sent again, so a receiver gets one event for one key |
a certificate revoked with the reason keyCompromise (the portal, an enrollment protocol’s revoke, /admin/pki) |
x509 |
the CAEP credential-change revoke |
| the emailed second factor turned off after too many wrong codes | urn:iya:sts:credential-type:email-otp |
the CAEP credential-change delete |
A one-time code presented twice is not an event: someone pressing submit
twice looks exactly like a replay. It is a risk-scoring signal instead
(totp-replay, see Risk scoring).
Credentials with no CAEP type use this service’s own URNs (#236). CAEP 1.0 section 3.3.1 allows any credential type the two parties agree on, and a receiver that does not know one still learns that a credential of the person changed:
| Credential | credential_type |
|---|---|
| the emailed second factor | urn:iya:sts:credential-type:email-otp |
| a SIOPv2 self-issued subject key | urn:iya:sts:credential-type:self-issued-key |
| an ACME External Account Binding key | urn:iya:sts:credential-type:acme-eab-key |
| a HOBA key | urn:iya:sts:credential-type:hoba-key |
| a person’s Kerberos keys | urn:iya:sts:credential-type:kerberos-key |
| a device key, a Native SSO device secret | urn:iya:sts:credential-type:device-key, urn:iya:sts:credential-type:device-secret |
A SCEP challenge password is sent as password, with friendly_name naming
it. A CIBA user code is pin.
A credential cannot be written over LDAP
(#237). An add or modify of a
security key, an authenticator app, recovery codes, an app password, a
signing key pair, a HOBA key, a self-issued subject, the emailed factor,
Kerberos keys, a CIBA user code, an enrollment credential or a device secret
is refused with unwillingToPerform (53), for every bind in both modes, and
the refusal names the page or endpoint to use instead. Those doors check
what they store and send the events above. userPassword is still written
over LDAP; deleting it sends credential-change revoke.
RISC opt-out (section 2.8) is the account holder’s choice. On
/portal/signals a person can stop sharing security events about their
account. Their account enters opt-out-initiated; receivers keep being told
everything; and after risc.optOutDelayHours a scheduler job sends
opt-out-effective, after which only opt-out events are sent about them.
They can cancel during the wait, or opt back in afterwards. The wait stops
somebody who has just taken an account over from silencing it at once.
Only the holder moves it: an administrator’s Reset or Clear on the RISC
register keeps the account’s opt state, and a pending opt-out still becomes
effective on schedule. An application and a service account have no
holder to make the choice (#221),
so the opt-out does not apply to either: every event about them is exchanged,
/admin/risc-accounts and its row’s notes say the gate does not apply, and
/portal/signals shows a service account the reason instead of a button.
Applications are subjects too (#221). An application is named by SSF 1.0’s
complex subject’s application member, { "format": "opaque", "id":
"<client_id>" }; a receiver adds it to a stream like any subject. Its
credentials, its own tokens’ claims, its own grant and its deletion are
sent about it — see the CAEP events, Applications and
workloads.
Every value of mail, telephoneNumber and mobile counts. A second
address changing, or a mobile beside a telephoneNumber, is an
identifier-changed; an address removed is one with no new-value, and it
can then be identifier-recycled to another account. The recovery
address is the first mail value, which /portal/forgot-password mails:
its addition, change, removal or verification is
recovery-information-changed (a change is identifier-changed as well).
A recovery code used is recovery-information-changed, and at sign-in
recovery-activated too.
account-disabled carries a reason only when an administrator gives one
(hijacking or bulk-account, on the console’s disable form or as
riscReason on /admin-api/users/disable).
Five more events belong to this service rather than to any specification. Each one has no subject, because it is about the issuer rather than about a person. A receiver that does not know a type ignores it, as SSF says it should.
Type (urn:iya:sts:secevent:event-type:…) |
Sent when | The document to fetch again |
|---|---|---|
signing-key-rotated |
a realm’s signing keys rotate (on the schedule, by hand, or in an emergency), or an operator pins a key pair as the realm’s signer for an algorithm or unpins it (reason: requested, sent when the pinned key is PUBLISHED, ahead of its use) |
jwks_uri, crypto_metadata_uri |
federation-key-rotated |
a realm’s OpenID Federation entity key rotates (in an emergency, the current and next keys are revoked), or a retired key is revoked | entity_configuration_uri |
spiffe-authority-rotated |
a realm’s SPIFFE X.509 or JWT authority is rotated, or the certificate hierarchy under it is rebuilt | bundle_uri; bundle_changed says whether the bundle itself changed |
tls-certificate-changed |
the certificate the main port presents is re-issued, or the service (or one node of it) starts presenting a certificate other than the one it last announced (reason: restarted). Sent to every realm’s streams |
certificate_uri |
kerberos-tickets-invalidated |
a krbtgt rotation keeps no previous version, so every TGT in the realm is refused: “rotate and invalidate” (reason: invalidated), or an ordinary rotation with krb5.retainedKeyVersions 0 (reason: nothing-retained) |
none |
The first four share one shape: realm, rotated as
<unit> <previous> -> <new>, reason (scheduled, requested or emergency,
and for tls-certificate-changed also restarted), the address above, and
event_timestamp. Each kind of key has its own type so that a receiver
subscribes only to the keys it pins, and every type it receives means one
action: fetch that document again. The refresh-token encryption keys are never
announced, because they are published nowhere.
A start can present a certificate nobody was told about. Each node keeps
its listener key, and the certificate over it, across restarts where minted
state survives (TLS), but a new key or a re-issued certificate at
start is still possible. The service keeps the fingerprint it last announced
in its store and compares it with the certificate it presents once the port
is bound. If they differ, it sends tls-certificate-changed with
reason: restarted, where <previous> is the certificate it last announced.
A restart that presents the same certificate sends nothing.
- Where it works: only where minted state survives a restart, which is
product mode on postgres or a cluster. In
memorymode, on anldifstore and in a single-process development service a restart is not announced. Development builds a new Root at every start anyway. - In a cluster: the record is the SERVICE’s, not a node’s. A node’s
start is announced whenever another node announced after it, and
<previous>may be a certificate another node still presents. A receiver behind the balancer should pin the Root, not a leaf. - Never announced: a self-signed bootstrap certificate or one supplied
through
tls.certificateFile.
A stream this service deletes is told first. SSF 1.0 has no event for a
deleted stream. So when an administrator deletes a stream (on the console or
through /admin-api), or ssf.inactivityAction: delete removes one, the
receiver is first sent stream-updated with status disabled and the reason,
and only then is the stream removed. On a push stream the push is attempted
before the stream goes. On a poll stream the SET leaves with the stream unless
the receiver polls in between, as with any disable. A receiver that deletes
its own stream is sent nothing, because it asked.
Discovery and stream management
SSF fixes no paths. A receiver starts from the transmitter configuration metadata and discovers every endpoint from it:
| Path | What it is |
|---|---|
GET /.well-known/ssf-configuration |
the transmitter configuration metadata. Never gated, and still answers while ssf.enabled is off |
GET /.well-known/ssf-configuration/realm/{id} |
the same document for a trust realm’s transmitter, at the path SSF 1.0 section 7.2 builds from an issuer with a path |
/ssf/stream |
stream management: POST creates, GET reads, PUT and PATCH update, DELETE deletes |
/ssf/status |
read (GET) or change (POST) a stream’s status |
POST /ssf/subjects/add, POST /ssf/subjects/remove |
add (an empty 200) or remove (204) a subject, SSF 1.0 sections 8.1.3.2 and 8.1.3.3 |
POST /ssf/verify |
ask for a verification event |
POST /ssf/poll |
RFC 8936 poll delivery and acknowledgement |
GET /ssf |
a description of the family; ?format=json returns the same as data |
In a trust realm every path is under /realm/{id}. A realm’s metadata is at
both /realm/{id}/.well-known/ssf-configuration and the section 7.2 form above,
which inserts the well-known name between the host and the issuer’s path. The
subject paths use a slash where SSF’s own examples use a colon
(/subjects:add). A receiver reads add_subject_endpoint from the metadata,
so it never sees the difference. spec_version is 1_0.
A receiver picks its event types in events_requested. The transmitter
answers with events_delivered, which is the overlap with what it offers
(ssf.eventsSupported, caep.eventsSupported and risc.eventsSupported,
combined).
Each stream belongs to its receiver
SSF 1.0 section 8 has the transmitter associate each receiver with its streams
and its aud values. Here, a stream belongs to the identity that created it:
a client’s client_id, a person’s sub, a GNAP client instance, or a Basic
username.
- Another receiver’s stream answers 404, word for word as for a stream that
does not exist, on every endpoint that takes a
stream_id. That is the specification’s own wording (“no Event Stream with the given stream_id for this Event Receiver”), and a different answer would reveal which ids exist. GET /ssf/streamwith nostream_idlists only the caller’s own streams, and an empty list when it has none.audis set by the transmitter (section 8.1.1 lists it as Transmitter-Supplied). A new stream’saudis the identifier the receiver authenticated as. A receiver may instead sendaudnaming one or more of the names it is associated with: that identifier, plus the application identifier and everyssfReceiverIdon its registered application entry. Any other value is refused. An update may carryaud, or any other Transmitter-Supplied member (iss,events_supported,events_delivered,min_verification_interval,inactivity_timeout), only unchanged.- A person’s stream is about that person. A stream created with a
person’s own credential is theirs, and it carries only events about them.
That credential is an access token a client obtained for them (for example
by the authorization code grant), or their directory name and password over
Basic. Events about anybody else are not delivered to it, whatever its
subject list and
ssf.defaultSubjectssay, and an Add Subject naming anybody else answers403 access_denied. A relying party that needs events about everybody creates its stream with its own client credentials token.ssf.personStreamsSelfOnlyturns this off. ssf.maxStreamsis per receiver. Creating a stream past it answers 403.- The console’s and portal’s own streams belong to no remote receiver and
are managed only on
/admin/ssfand through/admin-api.
Subjects
A subject can be in any of the eight RFC 9493 formats under their registered
names (account, email, iss_sub, opaque, phone_number, did, uri,
aliases), in one of SSF 1.0 section 3.5’s three (jwt_id,
saml_assertion_id, ip-addresses), or be SSF’s complex subject, which
carries "format": "complex". The complex subject’s members (user,
device, session, application, tenant, org_unit and group, plus any
additional name section 3.3 allows) are what make this session was revoked
possible to say at all. Each format has a closed member set. A subject
carrying a member that its format does not define is refused, and the refusal
names the member, because a conforming receiver has to reject one. Nesting a
complex subject inside another is refused as well. The pre-RFC names
issuer_subject_id and decentralized_identifier are not accepted.
A stream that names a person covers a complex subject naming one of that
person’s sessions. ssf.defaultSubjects controls what a stream with no
subjects covers. With ALL, the default, it covers everybody, and naming a
subject narrows it to the named subjects. Removing the last subject widens it
back to everybody. With NONE it covers nobody until a subject is added.
A stream a person owns covers only subjects that name that person, in any of these forms:
- an
iss_subwith their subject, including thesuba pairwise client is told; - an
email,phone_numberoraccountsubject for their account; - an
aliasessubject in which any alias names them; - a complex subject whose
usermember names them.
A complex subject with no user member names nobody on such a stream.
Push and poll delivery
- Poll (RFC 8936). The receiver calls
POST /ssf/poll— the stream’sdelivery.endpoint_url, which names the stream in its query (?stream_id=…), since RFC 8936’s poll endpoint is per stream — and nothing is dialled. One poll returns at mostssf.pollMaxEventsSETs and setsmoreAvailablewhen more are waiting. An acknowledged SET is never handed out again. Until it is acknowledged, it may be returned again, as RFC 8936 section 2.4 allows. - Push (RFC 8935). The service POSTs each SET to the endpoint the receiver
named on its stream, with the stream’s
authorization_header. A 202 counts as delivery. A 400 with{err, description}means the receiver refused the SET, and it is recorded separately from a network failure. A 200 or 204 is accepted, with a note that it is not quite right.
Push is the one place in SSF where this service makes a request to an address
that a caller chose. Four settings limit it: ssf.pushDelivery turns it off,
ssf.pushAllowedHosts is a host allowlist (empty by default, meaning any
host), only https with the receiver’s certificate verified is used — plain
http only with ssf.pushAllowHttp and verification off only with
ssf.pushSkipTlsVerification, both in development mode only (#171);
product reaches a privately certified receiver through ssf.pushCaFile — and
every push has a timeout, a cap on the response size and no redirects. The
receiver’s host must be in security.outboundAllowedHosts when that is set, in
either mode. In product mode it is also held to the rules every outbound
request follows: it must not resolve to an internal address, and the push goes
to the address that was checked (STS-SSF-0158 otherwise). With push
turned off, SSF still works in full over poll, and delivery_methods_supported
lists only poll.
Stream status
SSF 1.0 section 7.1.2 defines three statuses:
- enabled: events are delivered.
- paused: nothing is delivered and events keep queueing. On a push stream they are pushed, in the order they happened, when the stream is enabled again.
- disabled: the queue is dropped, and the stream’s log records how many events went.
Every status change sends a stream-updated event on the stream, whether or
not the receiver asked for that type (section 8.1.5 allows it, and requires it
when the transmitter changes the status). It goes before the stream stops
when it is paused or disabled, and after it starts again when it is enabled. On
a poll stream that has been paused or disabled, POST /ssf/poll still hands out
the stream-updated event and nothing else. Setting the status a stream
already has sends nothing.
A new stream starts as ssf.streamStatusOnCreate (enabled by default). Set
it to paused to test a receiver that has to enable its own stream first.
Inactivity and transmitter-initiated verification
ssf.inactivityTimeoutS(section 8.1.1’sinactivity_timeout, 0 by default, meaning none): a stream whose receiver has made no management call about it, and on a poll stream no poll either, for that long is paused, disabled or deleted, asssf.inactivityActionsays. A pause or disable is announced withstream-updatedfirst. The value is published on every stream configuration while it is set. It is off by default because a push receiver never needs to call back after creating its stream.- A person’s browser stream times out anyway. A stream a person owns and
collects by poll — what a browser receiver such as
oidc-caep-clientmakes with the person’s own token — takesssf.personStreamInactivityTimeoutS(a day by default) andssf.personStreamInactivityAction(delete) when nothing above sets a timeout. Each poll is activity, so a stream with a tab open never times out; one left behind when its tab was closed, its storage cleared or the person moved browser is removed, and stops counting againstssf.maxStreams. ssf.verificationEveryS(0 by default): every enabled stream is sent a verification event, with nostate, when this transmitter has sent it none for that long. Send a verification event on/admin/ssfdoes the same once.
Both run as the ssf.stream-maintenance scheduler job every
ssf.streamMaintenanceSweepS. The console’s and portal’s own streams are left
alone.
Verification
POST /ssf/verify answers 204 as soon as the event is queued. Section
8.1.4.2 says a receiver must not depend on the event arriving synchronously,
so a failed delivery is not reported in the response: it goes to the stream’s
dead-letter queue and log, like any other failed push. A paused stream holds
the event until it is enabled, and a disabled stream refuses the request with
- The verification event is sent even if the stream did not agree to the type.
Signing
Every SET is signed with ssf.signingAlgorithm, using the same signer as
every other token here. You can pick any algorithm from the full list: RS256,
the PS and ES families, EdDSA, and the post-quantum ones (ML-DSA, SLH-DSA and
the composite ML-DSA algorithms). A SET has typ: secevent+jwt.
ssf.setCertificateHeader controls whether it carries the signing key’s
certificate chain, as x5u (the default), x5c, both, or neither.
Authentication: four schemes, two scopes
The metadata document lists the schemes it accepts in
authorization_schemes:
- OAuth 2.0: an access token from this service with the read scope
(
ssf.read) or the write scope (ssf.manage), which includes read. These are the CAEP Interoperability Profile 1.0 names. DPoP- and certificate-bound tokens are checked the same way as at every other protected endpoint. - HTTP Basic: a directory person’s name and password, so that a client
that has no token flow yet can still reach every endpoint. Basic carries no
scope, so a Basic caller gets both.
ssf.authBasicturns the scheme off. In product mode a person who holds or must hold a second factor is refused their own password with the401a wrong one gets, and uses an app password scoped tossf. - GNAP: a key-bound GNAP access token whose access includes one of those
names, or an object of type
ssfwith the action the call needs, so that a GNAP web application can own a stream itself. See GNAP. - TLS client certificate (
urn:ietf:rfc:8705): the certificate on the connection, sent with noAuthorizationheader. Only a certificate that names an application is taken: one this realm issued to it (on the application’s Credentials section, or throughPOST /admin-api/applications/issue-tls-client-certificate) while the application still holds it, or one from an outside certificate authority stored byte for byte inuserCertificateon that application’s entry and on no other — stored from the Credentials section of its page or withPOST /admin-api/applications/add-certificate(TLS). Either is refused when revoked. The receiver is that application: it owns the streams it creates under its identifier, exactly as a GNAP token for it would, and reaches no other receiver’s. It holds what a token for the application would be issued: the Shared Signals scopes itsoauthAllowedScopedeclares and itsSSF_READandSSF_MANAGEroles authorize, asked again on every call. A person’s certificate, another realm’s, one the application no longer holds and a revoked one are refused with 401 (STS-SSF-0147,0148,0150); an application whose declarations and roles authorize nothing the call needs gets 403 (STS-SSF-0149). A certificate from an authority you added to the truststore that is stored on no entry is refused 401 (STS-SSF-0151), and one stored on more than one (STS-SSF-0152); its common name and subject are never read.ssf.authClientCertturns the scheme off.
ssf.read lets a caller read a stream, its status and the poll queue.
ssf.manage is the write scope: it is needed to create, change or delete a
stream, change subjects or status, or ask for verification. Update, add and
remove subject, and update status are writes; poll is a read. A read token
that attempts a write gets a 403 that names the scope it needs.
Write includes read. The profile says ssf.manage includes every
ssf.read permission, and this service applies that one rule everywhere:
- A token that carries a write scope may read.
- A client that declares a write scope in
oauthAllowedScopemay be issued the read scope as well. A client that declares only the read scope is not issued a write scope. This holds in both modes, through the token endpoint and GNAP. - A token is honoured only while its client still declares a scope that
grants what the call needs (
STS-SSF-0107). A token that holds onlyssf.manage, whose client now declares onlyssf.read, can still read and can no longer write.
ssf.authScopeRead and ssf.authScopeWrite rename the two scopes. A
renamed scope is accepted beside the profile name, which stays accepted. A
renamed write scope includes read, as ssf.manage does, and so does a name
set on both settings. Discovery’s scopes_supported lists every name. With
the defaults that is ssf.read and ssf.manage. This service’s older
names, ssf:read and ssf:write, are not Shared Signals scopes.
The default access-token lifetime (oauth2.accessTokenTtlS, 3600 seconds)
meets the profile’s sixty-minute ceiling. These tokens have no separate cap,
and the lifetime’s own maximum stays thirty days.
Limiting what an application’s stream may carry
An application entry can carry ssfAllowedEvents: caep, risc, or
particular event type URIs. A stream owned by that application then gets only
those types. The limit applies when the stream is created or updated and
again at every delivery, so lifting a limit does not release types that were
held back when the stream was agreed, and a receiver that created its stream
before the limit was tightened gets no way around it. SSF’s own two events are
always allowed. An empty value means no limit.
Dead streams and dead letters
A push that cannot be delivered is not retried unless ssf.pushRetries says
so. The default is 0, because a transmitter that retried would hide a
receiver’s one-off failure from whoever is testing it. When retries are on,
only failures that might go differently next time are retried: no connection,
a timeout, a 5xx or a 429. A 400 is never retried.
A SET that could not be delivered goes to its stream’s dead-letter queue
with the reason, the error code and the receiver’s HTTP status. That happens
when a push fails for good, when the push backlog is full, and when the stream
is dead. A push stream whose pushes have all failed for
ssf.deadStreamTimeoutS is declared dead. Nothing more is pushed to it,
and once per timeout the oldest dead letter is pushed as a probe. A dead
stream is also paused, with a stream-updated event attempted first,
because stopping delivery is a status change the receiver must be told about
(section 8.1.2). When a probe succeeds, or an operator revives the stream, it
is enabled again and announced, and whatever it held is pushed. A stream that
the receiver or an operator paused is never enabled by a revival. Nothing
resends a dead letter except a probe.
Failures are logged once per stream (when it dies and when it revives) and once per sweep as a summary, never once per SET.
This service as a receiver
This service’s own receivers are the admin console’s, the user portal’s and
the reports application’s, which are seeded streams of its transmitter (see Signals received). They
verify each SET’s signature, and refuse one that does not verify when
ssf.receiveRequireSignature is on — product mode always refuses one
(#117). They also refuse a SET whose header’s typ is not secevent+jwt
(section 4.1.1), whose iss is not their stream’s (section 4.1.6), or whose
aud does not name them. Every SET that arrives is recorded first.
POST /ssf/receive and GET /ssf/received, an endpoint that accepted a SET
pushed at this service so that a client could be tested as a
transmitter, were removed in
#593. The test suite’s peer
plays that receiver. To receive a federation partner’s streams, see
Receiving from a federation partner, below.
Receiving from a federation partner
A realm can receive CAEP and RISC events from a federation partner’s
transmitter (#153,
#373). The partner is
configured as a federation relationship on Protocols → Federation, and
its Shared Signals are a section of that relationship. A partner that signs
nobody in here — a device manager, an endpoint agent, an HR system — is an
ssf relationship (#374).
- Turn the signals on on a relationship where this service is the
service provider:
fedSignalsEnabled(anssfrelationship has it on from the start). The partner’s SSF issuer isfedSignalsIssuer, or the relationship’sfedPeerwhen that is empty. SetfedSignalsIssuerfor a SAML or WS-Federation partner, whose entityID is not its SSF issuer. - Say how this realm authenticates to the partner: client credentials
(
fedSignalsTokenUrl,fedSignalsClientId,fedSignalsClientSecret, each falling back to the relationship’s ownfedTokenUrl,fedClientIdandfedClientSecret), orfedSignalsBearer. The two signals credentials are sealed under the key-encryption key wherever keys persist. - Create the stream: Create stream on the relationship’s page, or
POST /admin-api/federation/signals-create-stream. This fetches the partner’s/.well-known/ssf-configurationandjwks_urifirst and checks the document names the issuer. A poll stream (fedSignalsDeliverypoll) is polled everyssf.foreignPollSseconds. A push stream is given/federation/signals/{id}and an authorization header only the two services know.fedSignalsEventsis what the stream asks for. The stream can then be read, updated, replaced (a PUT of every setting this realm supplies), paused or enabled, its status read, verified and deleted from the same page; the token asks forssf.read ssf.manageunlessfedSignalsScopesays otherwise. - Link people. For a partner people sign in through, the links its
sign-ins wrote are what its
iss_subsubjects match:issis the partner (or its SSF issuer) andsubthe identifier it signs them in with — for SAML, the persistent NameID. For anssfrelationship, link each person on their page, with the issuer and subject itsiss_subevents name them by, or the issueropaqueand the id of an opaque subject. Anemailsubject is matched only where the relationship setsfedSignalEmailMatch.
A Security Event Token is acted on only if it verified: its signature against
the keys the partner’s SSF configuration names, typ, iss, the stream’s
aud, and a jti never seen before. Product mode refuses an unverified one.
What it leads to is the signal-response XACML policy’s decision; a
session-revoked is a revocation whatever its initiating_entity. By
default:
| Partner | Events | Reaction here |
|---|---|---|
| signs people in | session-revoked, credential-change, sessions-revoked, credential-compromise, account-purged |
end the sessions this relationship started for the person — the one a complex subject’s session names, else every one. A local sign-in and other partners’ sessions are untouched |
| signs people in | account-disabled |
block this partner’s sign-ins of the person, and end the sessions it started. The account stays enabled; other ways of signing in keep working |
| signs people in | account-enabled |
lift that block |
ssf only |
anything about a person | recorded, nothing more. A global sign-out and an account lock exist for an operator’s policy to permit |
| either | device-compliance-change |
set the device’s compliance |
| signs people in | session-revoked, account-disabled, account-purged, credential-compromise |
revoke the person’s grants and tokens (#432): every GNAP grant they approved, and every OAuth grant (Grant Management), access and refresh token and unredeemed authorization code held for them. A session-revoked reaches only what was issued on the sessions this relationship started. Sessions are left to the rows above. Turned off with ssf.signalsRevokeGrants |
ssf.signalsRevokeGrants is on by default. Turning it off records the
reaction as skipped and revokes nothing — so an account the partner reports
compromised keeps every grant and token it gave clients here until somebody
revokes them by hand; turn it off only where the partner’s signals are not
trusted that far, and prefer narrowing partnerRevokeGrantEvents in the
signal-response policy instead.
An administrator can lift a block with Unblock on the relationship’s page
(POST /admin-api/federation/signals-unblock). Every arrival from every
partner, and every block, is on Monitoring → Signals from partners
(/admin/ssf/transmitters, GET /admin-api/ssf/transmitters). What arrived,
the blocks and the account locks are each paged there — receivedPage,
blocksPage and locksPage, sharing per — and relationship narrows what
arrived before it is paged.
Development records what it would do and does nothing unless
ssf.actOnSignalsInDevelopment is on.
The console, the portal and the reports application are registered receivers
Each trust realm has three streams seeded by the service itself, one each for
the admin console, the user portal and the reports application. Each asks for
every CAEP and RISC event type and collects it over RFC 8936 poll from this
service’s own /ssf/poll. What arrives is shown at /admin/signals and
/portal/signals; the reports application answers it at
GET /report-api/signals and has no page for it.
Signals received explains how this works, and why an
empty page has five possible causes. All three act on what they receive: a
verified event the signal-response policy permits revokes the tokens the
receiving application’s own client holds for the person it names (product
mode; development records it). An unverified event is never acted on.
Broadcast announcements
An administrator can show a short message to everybody signed in to the
admin console, the user portal or the reports application. Open
Server configuration → Broadcast Announcement (/admin/broadcast), type
the message, choose the applications (all three are ticked) and press
Broadcast. Every tab of those applications that is open at that moment
shows it in a banner at the top of the screen. The banner closes itself after
ten seconds, or at once with its ×. A tab opened afterwards does not show
it.
It travels as a Shared Signals event of this service’s own,
urn:iya:sts:secevent:event-type:announcement, on the receiver streams the
three applications already have for CAEP and RISC, and only on those. Each
application’s receiver collects it from /ssf/poll like any other event,
checks it, and keeps a verified one for ssf.announcementKeepS seconds. Each
open tab asks its own API every ssf.announcementPollMs milliseconds:
/admin-api/announcements, /account-api/announcements or
/report-api/announcements. An announcement whose signature does not verify
is recorded on the application’s Signals page and shown to nobody.
- Who can send it: anybody with Admin Write. A realm administrator reaches the people signed in to their own realm. A service administrator in the default realm can also choose Every realm.
- The message is plain text, at most
ssf.announcementMaxCharscharacters. - From a script:
POST /admin-api/broadcast/sendwith{ "message": "…", "surfaces": ["admin-console", "user-portal", "report"], "everyRealm": false }. The answer says how many receiver streams took it in each realm;sent: 0withwhymeans nothing could be delivered (for examplessf.internalReceiversis off, or a stream was disabled at/admin/ssf).
Deliberate defects
A transmitter that is always correct is hard to write error handling against, so each of these switches produces a known mistake.
ssf.legacySubClaim and ssf.breakSetSignature make a SET wrong, and are
honoured in development mode only (#104), and so is
risc.googleSubjectType (#181), whose subject_type RISC 1.0 section 3.1
says new services MUST NOT use. A realm in product mode ignores them where the
SET is built and signed — even one still stored from before the realm was
switched, which is logged once (STS-CORE-0106) — and refuses turning them on
(STS-CORE-0103). The other two produce SETs that conform to their
specifications, and are honoured in both modes.
| Setting | What it breaks |
|---|---|
ssf.legacySubClaim |
adds the deprecated sub claim beside sub_id |
ssf.breakSetSignature |
changes one character of the signature after signing. The first character is changed, not the last, because the last character’s padding bits are discarded and a changed last character still verifies |
caep.omitEventTimestamp |
leaves out event_timestamp, which is optional and which many receivers assume is present |
risc.omitEventTimestamp |
the same, on credential-compromise |
risc.googleSubjectType |
spells the subject discriminator subject_type instead of format, as the RISC specification’s own section 3.1 records one production transmitter doing |
Not implemented
- Subjects are not checked. A stream may name somebody who has never been here, which is what a receiver’s I do not know this subject path needs.
verified: trueon Add Subject is believed. There is no confirmation step to skip.- There is no console or API control that creates a stream. A stream
holds a delivery endpoint that this service will call, and that address may
only come from a receiver that authenticated at
POST /ssf/stream. - A realm receives only from a transmitter an administrator registered (#153). It never follows a URL a SET or a request names; every address comes from that issuer’s own configuration document.
Development and product mode
Under paranoid PKI mode, on by default in product mode, a push to a receiver the certificate of whoever answers is checked before anything is sent: extendedKeyUsage serverAuth and revocation, stapled first, as the tls-server-outbound row of the use cases says. A CA in the realm’s signer truststore is trusted beside ssf.pushCaFile.
| Development | Product | |
|---|---|---|
Credential at /ssf/* |
required, but only a check at the door: any name and any password except invalid passes Basic. A token carries the read scope (ssf.read) or the write scope (ssf.manage) only when its client declares a scope granting that permission in oauthAllowedScope (in both modes), and is honoured only while it still does (STS-SSF-0107). Write includes read |
required, and a Basic password is checked against the person’s hashed userPassword |
| Access tokens | verified | verified |
| Subjects of automatic events | a person with no mail gets an invented @example.com address |
a real value from the directory entry, or the issuer/subject pair. RISC’s two identifier events are not sent when there is no real value |
| Streams, queues, CAEP and RISC registers | in memory, lost on restart | persisted with other minted state (product mode on postgres) |
HTTP Basic in product mode. A password carries no scope, and Basic grants
both the read and the write scope. In product mode the person must therefore
hold Admin Write, or the request is refused with 403 (STS-SSF-0157). Use an
OAuth access token for a receiver or a transmitter.
security.allowUnscopedPeople lifts the check, and ASVS 5.0.0 requirements
8.2.1 and 8.2.2 are then not met.
See What is not checked.
Running several nodes. Every node needs the same global.port, because
the console’s and portal’s own streams are pushed to
<loopback>:<global.port>. global.publicBaseUrl has to be pinned, because
it becomes every SET’s iss. Active-active mode refuses to start while it is
empty.
Configuration
There are 77 settings in three groups, and the SSF table also lists one GNAP
setting that affects streams. Every one can be changed while the service runs
except ssf.internalReceivers. The CAEP and RISC groups have no
effect on SSF itself: turning either vocabulary off only removes its event
types from what a stream may ask for.
Shared Signals (ssf.*)
| Setting | Environment variable | Default | Runtime? | What it does |
|---|---|---|---|---|
ssf.enabled |
STS_SSF_ENABLED |
true |
yes | Turns the whole family on or off. When off, the routes stay and answer 501, and the metadata still answers. |
ssf.issuer |
STS_SSF_ISSUER |
(empty) | yes | The iss of every SET and of the metadata. Empty means this realm’s base URL. |
ssf.signingAlgorithm |
STS_SSF_SIGNING_ALGORITHM |
RS256 |
yes | The JWS algorithm every SET is signed with, post-quantum ones included. |
ssf.setCertificateHeader |
STS_SSF_SET_CERTIFICATE_HEADER |
x5u |
yes | Whether a SET names its signing key’s certificate chain: none, x5c, x5u or both. |
ssf.deliveryMethods |
STS_SSF_DELIVERY_METHODS |
urn:ietf:rfc:8935,urn:ietf:rfc:8936 |
yes | Which delivery methods the service agrees to. push and poll are accepted as shorthand. |
ssf.defaultSubjects |
STS_SSF_DEFAULT_SUBJECTS |
ALL |
yes | What a stream with no subjects covers: everybody (ALL) or nobody (NONE). With ALL, naming a subject narrows the stream to the named subjects, and removing the last one widens it back to everybody. |
ssf.personStreamsSelfOnly |
STS_SSF_PERSON_STREAMS_SELF_ONLY |
true |
yes | A stream created with a person’s own credential (an access token a client obtained for them, or their name and password over Basic) carries only events about that person, whatever its subject list and ssf.defaultSubjects say, and Add Subject naming anybody else is refused with 403. Off, such a stream is treated like a client’s. |
ssf.streamStatusOnCreate |
STS_SSF_STREAM_STATUS_ON_CREATE |
enabled |
yes | The status a new stream starts in. paused makes the receiver enable its own stream. |
ssf.minVerificationInterval |
STS_SSF_MIN_VERIFICATION_INTERVAL |
60 |
yes | The min_verification_interval the service publishes. A stream that asks for less is refused. |
ssf.verificationRateLimit |
STS_SSF_VERIFICATION_RATE_LIMIT |
false |
yes | Answers 429 to a verification request that comes sooner than the published interval. |
ssf.criticalSubjectMembers |
STS_SSF_CRITICAL_SUBJECT_MEMBERS |
(empty) | yes | The complex-subject members a receiver must understand. Adding a complex subject that leaves one out is refused. |
ssf.eventsSupported |
STS_SSF_EVENTS_SUPPORTED |
verification, stream-updated | yes | Which of SSF’s own two event types are offered. |
ssf.pushDelivery |
STS_SSF_PUSH_DELIVERY |
true |
yes | Whether the service may push SETs at all. When off, only poll is offered. |
ssf.pushAllowedHosts |
STS_SSF_PUSH_ALLOWED_HOSTS |
(empty) | yes | Hosts the service may push to. Empty means any host. |
ssf.pushAllowHttp |
STS_SSF_PUSH_ALLOW_HTTP |
false |
yes | Allows http:// endpoints, in development mode only. This service’s own receivers are exempt in both modes. |
ssf.pushSkipTlsVerification |
STS_SSF_PUSH_SKIP_TLS_VERIFICATION |
false |
yes | Development only — a warning. Pushes to a receiver whose certificate nothing here trusts. Ignored in product, and refused on write there. |
ssf.pushCaFile |
STS_SSF_PUSH_CA_FILE |
(empty) | yes | A PEM file of CA certificates a receiver may chain to, beside node’s own store. |
ssf.pushTimeoutMs |
STS_SSF_PUSH_TIMEOUT_MS |
10000 |
yes | How long to wait for a receiver to answer a push. |
ssf.pushMaxResponseBytes |
STS_SSF_PUSH_MAX_RESPONSE_BYTES |
65536 |
yes | How much of a receiver’s answer is read before the push counts as failed. |
ssf.pushRetries |
STS_SSF_PUSH_RETRIES |
0 |
yes | How many times a failed push is retried. Only failures that could go differently are retried. |
ssf.pushRetryDelayMs |
STS_SSF_PUSH_RETRY_DELAY_MS |
1000 |
yes | The wait before a retry, multiplied by the attempt number. |
ssf.pushConcurrency |
STS_SSF_PUSH_CONCURRENCY |
8 |
yes | How many pushes one process makes at once. 0 removes the cap. |
ssf.pushBacklog |
STS_SSF_PUSH_BACKLOG |
2000 |
yes | How many pushes to one receiver may wait for a slot; each receiver has its own queue and a freed slot goes to them in turn. Past that, the SET is dead-lettered. |
ssf.deadStreamTimeoutS |
STS_SSF_DEAD_STREAM_TIMEOUT_S |
300 |
yes | How long a push stream has to fail completely before it is declared dead. 0 turns this off. |
ssf.deadLetterRetentionS |
STS_SSF_DEAD_LETTER_RETENTION_S |
3600 |
yes | How long an undeliverable SET is kept on the dead-letter queue. |
ssf.deadLetterMaxPerStream |
STS_SSF_DEAD_LETTER_MAX_PER_STREAM |
1000 |
yes | The most dead letters one stream keeps. The oldest is dropped first. |
ssf.deadLetterSweepS |
STS_SSF_DEAD_LETTER_SWEEP_S |
60 |
yes | How often expired dead letters are deleted, due probes are sent and the summary is logged. |
ssf.authBasic |
STS_SSF_AUTH_BASIC |
true |
yes | Whether HTTP Basic is accepted and advertised. |
ssf.authClientCert |
STS_SSF_AUTH_CLIENT_CERT |
true |
yes | Whether a receiver’s TLS client certificate is accepted and urn:ietf:rfc:8705 advertised. |
ssf.internalReceivers |
STS_SSF_INTERNAL_RECEIVERS |
true |
no | Seeds the console’s, the portal’s and the reports application’s own receiver streams. |
ssf.announcementPollMs |
STS_SSF_ANNOUNCEMENT_POLL_MS |
5000 |
yes | How often each open console, portal and reports tab asks for a broadcast announcement. |
ssf.announcementKeepS |
STS_SSF_ANNOUNCEMENT_KEEP_S |
60 |
yes | How long each application’s receiver keeps an announcement for its tabs to collect. |
ssf.announcementMaxChars |
STS_SSF_ANNOUNCEMENT_MAX_CHARS |
500 |
yes | The longest announcement, in characters. |
ssf.maxStreams |
STS_SSF_MAX_STREAMS |
25 |
yes | Streams per receiver in a realm. A create past the limit is refused with 403, and the refusal names this setting. The console’s and portal’s own streams do not count. |
ssf.inactivityTimeoutS |
STS_SSF_INACTIVITY_TIMEOUT_S |
0 |
yes | SSF 1.0 section 8.1.1’s inactivity_timeout: a stream whose receiver has made no management call about it (and, for a poll stream, no poll) for this long is dealt with as ssf.inactivityAction says. 0, the default, is no timeout. It is off by default because a push receiver never calls back. |
ssf.inactivityAction |
STS_SSF_INACTIVITY_ACTION |
pause |
yes | pause, disable or delete. A pause or disable is announced with a stream-updated event before the stream stops. |
ssf.personStreamInactivityTimeoutS |
STS_SSF_PERSON_STREAM_INACTIVITY_TIMEOUT_S |
86400 |
yes | The inactivity timeout of a stream a person owns and collects by poll — what a browser receiver makes with the person’s own token — when neither its application nor ssf.inactivityTimeoutS sets one. Each poll is activity, so only an abandoned stream (its tab closed for good) times out. 0 turns it off. |
ssf.personStreamInactivityAction |
STS_SSF_PERSON_STREAM_INACTIVITY_ACTION |
delete |
yes | What that timeout does: delete (frees the place under ssf.maxStreams), disable or pause. |
ssf.verificationEveryS |
STS_SSF_VERIFICATION_EVERY_S |
0 |
yes | Sends every enabled stream a transmitter-initiated verification event (no state) when it has had none for this long. 0 sends none on a schedule. |
ssf.streamMaintenanceSweepS |
STS_SSF_STREAM_MAINTENANCE_SWEEP_S |
60 |
yes | How often the ssf.stream-maintenance scheduler job applies the two settings above. |
ssf.maxSubjectsPerStream |
STS_SSF_MAX_SUBJECTS_PER_STREAM |
100 |
yes | How many subjects one stream may name. |
ssf.maxQueuedEvents |
STS_SSF_MAX_QUEUED_EVENTS |
200 |
yes | How many undelivered SETs one stream holds. The oldest is dropped first. |
ssf.pollMaxEvents |
STS_SSF_POLL_MAX_EVENTS |
20 |
yes | The most SETs one poll returns, whatever the receiver asks for. |
ssf.maxReceivedEvents |
STS_SSF_MAX_RECEIVED_EVENTS |
200 |
yes | How many delivered SETs each of this service’s own receivers (the console’s, the portal’s and the reports application’s) keeps, per realm. |
ssf.maxStreamLogEntries |
STS_SSF_MAX_STREAM_LOG_ENTRIES |
200 |
yes | How many log lines each stream keeps. |
ssf.authScopeRead |
STS_SSF_AUTH_SCOPE_READ |
ssf.read |
yes | The scope that reads a stream, its status or the poll queue. The CAEP profile name ssf.read is always accepted, even when this is renamed. Write includes read, so a write scope reads as well. |
ssf.authScopeWrite |
STS_SSF_AUTH_SCOPE_WRITE |
ssf.manage |
yes | The scope that creates, updates or deletes a stream, changes subjects or status, or asks for verification. The CAEP profile name ssf.manage is always accepted, even when this is renamed. Write includes read, so a name set here reads as well. |
ssf.receiveRequireSignature |
STS_SSF_RECEIVE_REQUIRE_SIGNATURE |
false |
yes | Refuses a received SET whose signature fails, with 400 invalid_key, in development mode. Product mode always refuses one (#117). |
ssf.actOnSignalsInDevelopment |
STS_SSF_ACT_ON_SIGNALS_IN_DEVELOPMENT |
false |
yes | The console, the portal and the reports application revoke their own client’s tokens on a received signal in development too; product always does. |
ssf.signalsRevokeGrants |
STS_SSF_SIGNALS_REVOKE_GRANTS |
true |
yes | A verified event from a federation partner that the signal-response policy answers with signal-revoke-grants revokes the person’s GNAP grants, OAuth grants, tokens and authorization codes (#432). See Receiving from a federation partner. |
ssf.foreignPollS |
STS_SSF_FOREIGN_POLL_S |
30 |
yes | How often the ssf.foreign-poll scheduler job polls every federation partner whose stream is a poll stream. |
ssf.foreignPollMaxEvents |
STS_SSF_FOREIGN_POLL_MAX_EVENTS |
50 |
yes | The maxEvents asked of a partner in one poll. |
ssf.foreignPollMaxRounds |
STS_SSF_FOREIGN_POLL_MAX_ROUNDS |
5 |
yes | How many polls one run makes while the partner says moreAvailable. |
ssf.foreignInboxMax |
STS_SSF_FOREIGN_INBOX_MAX |
500 |
yes | How many SETs from partners a realm keeps, the oldest dropped first. A replayed jti is recognised against these. |
ssf.foreignTimeoutMs |
STS_SSF_FOREIGN_TIMEOUT_MS |
10000 |
yes | How long one request to a partner’s Shared Signals (discovery, its token endpoint, stream management, a poll) may take. |
ssf.legacySubClaim |
STS_SSF_LEGACY_SUB_CLAIM |
false |
yes | Deliberate defect, development only: adds the deprecated sub claim beside sub_id. |
ssf.breakSetSignature |
STS_SSF_BREAK_SET_SIGNATURE |
false |
yes | Deliberate defect, development only: changes one character of every SET’s signature. |
gnap.scopedSignals |
STS_GNAP_SCOPED_SIGNALS |
true |
yes | A stream owned by a GNAP application only hears about people who approved a grant to it. A stream owned by a GNAP resource server hears only session-revoked for the GNAP tokens and grants audienced to it (#432). |
CAEP (caep.*)
| Setting | Environment variable | Default | Runtime? | What it does |
|---|---|---|---|---|
caep.enabled |
STS_CAEP_ENABLED |
true |
yes | Offers CAEP’s eight event types and keeps the session register. |
caep.autoEmit |
STS_CAEP_AUTO_EMIT |
true |
yes | Sends CAEP events automatically for the session acts this service can observe. |
caep.autoEmitTypes |
STS_CAEP_AUTO_EMIT_TYPES |
session-established,session-presented,session-revoked,credential-change,assurance-level-change,token-claims-change,risk-level-change |
yes | Which of those acts produce an event. A type nothing here can cause is dropped with a warning. |
caep.eventsSupported |
STS_CAEP_EVENTS_SUPPORTED |
all eight | yes | Which CAEP types a stream may ask for. Short names are accepted. |
caep.assuranceNamespace |
STS_CAEP_ASSURANCE_NAMESPACE |
NIST-AAL |
yes | The namespace of an assurance-level-change emitted by hand. Automatic ones use urn:sts:acr. |
caep.defaultRiskLevel |
STS_CAEP_DEFAULT_RISK_LEVEL |
MEDIUM |
yes | What a risk-level-change says when the caller does not choose a level. |
caep.reasonLanguage |
STS_CAEP_REASON_LANGUAGE |
en |
yes | The language tag the reason members are keyed under. |
caep.includeReasons |
STS_CAEP_INCLUDE_REASONS |
true |
yes | Whether automatic events carry the optional reason members. |
caep.maxSessionsTracked |
STS_CAEP_MAX_SESSIONS_TRACKED |
200 |
yes | The size of the CAEP session register. The oldest row is dropped first. |
caep.eventsPerSession |
STS_CAEP_EVENTS_PER_SESSION |
25 |
yes | How many recent events a register row lists. The per-type counts are never trimmed. |
caep.historyPerSession |
STS_CAEP_HISTORY_PER_SESSION |
10 |
yes | How many credential-change details a row keeps. |
caep.omitEventTimestamp |
STS_CAEP_OMIT_EVENT_TIMESTAMP |
false |
yes | Deliberate defect: leaves out the optional event_timestamp. |
RISC (risc.*)
| Setting | Environment variable | Default | Runtime? | What it does |
|---|---|---|---|---|
risc.enabled |
STS_RISC_ENABLED |
true |
yes | Offers RISC’s fourteen event types and keeps the account register. |
risc.autoEmit |
STS_RISC_AUTO_EMIT |
true |
yes | Sends RISC events automatically for the directory changes this service can observe. |
risc.autoEmitTypes |
STS_RISC_AUTO_EMIT_TYPES |
every type but sessions-revoked |
yes | Which of those acts produce an event. |
risc.recycleWindowDays |
STS_RISC_RECYCLE_WINDOW_DAYS |
365 |
yes | How long after an account released an address or number another account taking it is reported as identifier-recycled. Also bounded by risc.maxAccountsTracked. 0 reports nothing. |
risc.optOutDelayHours |
STS_RISC_OPT_OUT_DELAY_HOURS |
24 |
yes | How long an opt-out waits in opt-out-initiated before the risc.opt-out-effective job makes it effective. |
risc.eventsSupported |
STS_RISC_EVENTS_SUPPORTED |
all fourteen | yes | Which RISC types a stream may ask for, including the deprecated sessions-revoked. |
risc.subjectFormat |
STS_RISC_SUBJECT_FORMAT |
iss_sub |
yes | The RFC 9493 format of an account subject: iss_sub, email or opaque. The two identifier events always use email. |
risc.honourOptOut |
STS_RISC_HONOUR_OPT_OUT |
true |
yes | Suppresses events for an account in the opt-out state, except the four opt-out events. |
risc.googleSubjectType |
STS_RISC_GOOGLE_SUBJECT_TYPE |
false |
yes | Deliberate defect: spells the subject discriminator subject_type on RISC subjects. Development mode only: ignored in product, and turning it on is refused (#181). |
risc.reasonLanguage |
STS_RISC_REASON_LANGUAGE |
en |
yes | The language tag of the reason members on credential-compromise. |
risc.includeReasons |
STS_RISC_INCLUDE_REASONS |
true |
yes | Whether credential-compromise carries its optional reason members. |
risc.omitEventTimestamp |
STS_RISC_OMIT_EVENT_TIMESTAMP |
false |
yes | Deliberate defect: leaves event_timestamp off credential-compromise. |
risc.maxAccountsTracked |
STS_RISC_MAX_ACCOUNTS_TRACKED |
200 |
yes | The size of the RISC account register. The oldest opted-in row is dropped first. A row whose holder opted out is never dropped; the register stays over the cap and logs STS-SSF-0130 instead. |
risc.eventsPerAccount |
STS_RISC_EVENTS_PER_ACCOUNT |
25 |
yes | How many recent events a register row lists. |
risc.historyPerAccount |
STS_RISC_HISTORY_PER_ACCOUNT |
10 |
yes | How many credential-compromise and identifier-change records a row keeps. |
For how a value is resolved and where it can be changed, see
Configuration. Each group is on its own console page
(/admin/ssf, /admin/caep, /admin/risc), and every setting can also be
changed with POST /admin-api/config/set.
Design decisions
- SSF is the pipe; CAEP and RISC are vocabularies over it. SSF’s two events are about the stream itself. Session and account events are rows in a table on top of it, so adding RISC’s fourteen types changed nothing in the envelope, the subjects, delivery or stream management.
- CAEP keeps a register of sessions and RISC keeps a register of accounts, and they are separate. A session starts, is used and ends, and one person can have many. An account is the person and outlives every session. RISC also tracks three things per account that change independently: its lifecycle, its opt-out state and whether a credential is compromised.
- Both registers keep a row after the session or account is gone. A revoked session disappears from the session store, and a purged account disappears from the directory. After that, the register row is the only evidence that anybody was told.
- RISC watches the directory, not SCIM. A person can be deleted or
disabled over SCIM, LDAP or the console. A RISC feature that only noticed
SCIM would say nothing about a deprovisioning done with
ldapmodify. - An attribute that is absent is not the same as one that is false. A
write that does not mention
activesends noaccount-disabled. Otherwise every person created without the attribute would be reported as disabled. - A transmitter reports, and a receiver decides. RISC tells a receiver that an account was disabled or purged here. What the receiver does about it is the receiver’s decision, which is how the profile divides the work.
- The four opt-out events are never suppressed.
opt-out-effectiveannounces that the account is going quiet, andopt-inis the only way a receiver learns it came back. Holding either back would make an opt-out look like a transmitter that had stopped working. The middle state,opt-out-initiated, still exchanges everything, so that someone who hijacks an account cannot silence the events that would report them. - The first time a new session is presented, no event is sent. Every
sign-in ends with the browser returning to the authorization endpoint. If
that counted,
session-establishedandsession-presentedwould always arrive milliseconds apart. initiating_entitysays who really ended a session. An expiry sayspolicy. An administrator ending someone’s session saysadmin. It never claims the person signed themselves out when they did not.- Push is not retried by default. A transmitter that retried would hide a
receiver’s one-off failure. A deployment can set
ssf.pushRetries. - A push that fails goes to a dead-letter queue; logging stays per stream. A burst of failures produces one line when the stream dies and one summary per sweep. Signing a SET that nothing will receive is skipped.
- The metadata document is always open. A receiver has to read which schemes the endpoints take before it can authenticate to them.
audis the transmitter’s to assign. It comes from the receiver’s own identity, so a receiver cannot have its events addressed to another receiver.- The console’s and portal’s signals come through a real push. Passing events to those pages internally would skip the body, media type, authorization header and signature, which is everything a receiver does. Their stream IDs and authorization tokens are derived from the realm and the surface, so every process and every node arrives at the same values.
- SETs are worth signing with a post-quantum algorithm. RFC 8417 forbids a SET from expiring, so it is read long after it was written.
In the running service
- Protocols → Shared Signals (
/admin/ssf): thessf.*settings, and every stream this realm’s transmitter holds, with its subjects, queue, counters, log and dead letters. A dead stream is marked. Each stream has controls to change its status, delete it, send it a SET, Send a verification event, Revive it and Drop its dead letters. There is no control to create a stream (see Not implemented). - Protocols → CAEP (
/admin/caep): thecaep.*settings, the catalogue of the eight event types and their members, and the form for sending one by hand. You pick a session by searching for the person, and only live sessions are offered. - Protocols → RISC (
/admin/risc): therisc.*settings, the catalogue of the fourteen event types, and the form for sending one by hand about an account. - Monitoring → Shared Signals: CAEP sessions (
/admin/caep-sessions), RISC accounts (/admin/risc-accounts), Signals received (/admin/signals) and Dead letters (/admin/ssf/dead-letters). The dead-letters page counts every held SET by cause, error code, receiver HTTP status, event type, time and stream. It shows the letters themselves, but not their tokens. - The management API mirrors all of these:
GET /admin-api/ssfandPOST /admin-api/ssf/{action}(status,delete,transmit,revive,clear-dead-letters,verify),GET /admin-api/ssf/dead-letters,GET /admin-api/caep,GET /admin-api/caep/sessionsandPOST /admin-api/caep/{action}(emit,reset-session,clear),GET /admin-api/risc,GET /admin-api/risc/accountsandPOST /admin-api/risc/{action}(emit,reset-account,clear), and/admin-api/signals. The request and response shapes are in/admin-api/openapi.json. GET /ssfdescribes the family, its gate and what it deliberately does not do. Every endpoint is listed live on/admin/sts-metadata.- Monitoring → Scheduler (
/admin/scheduler) lists the dead-letter sweep and the stream-maintenance jobs.
Every failure is recorded under an STS-SSF-NNNN code. See
error codes.
Related
- CAEP events: what triggers each of the eight CAEP events
- Signals received: the console and portal as receivers
- Sessions, Signing out: the session acts CAEP reports
- GNAP: GNAP streams and the signals a grant produces
- SCIM, LDAP: the directory writes RISC reports
- OAuth 2.0 & OpenID Connect: getting an
ssf:*token - Trust realms, What is not checked, Configuration