Shared Signals Framework
support for Java, .NET, Go, Rust and Python
easyssf adds an OpenID Shared Signals Framework (SSF) receiver to your Java, .NET, Go, Rust or Python application, so that it reacts when your identity provider revokes a session, changes a credential, or signals a risk.
The receiver verifies the incoming security events, CAEP events about sessions and credentials, RISC events about accounts, and SCIM Events about changes to your users, rejects the affected access tokens, ends the affected sessions, and hands everything else to your code.
Why a SSF receiver?
Your identity provider knows the moment a user signs out everywhere, loses a device, changes a password or trips a risk rule. Your application does not: its session and its access tokens stay valid until they expire. A Shared Signals receiver closes that gap.
Without a receiver
You shorten token lifetimes, poll token introspection on every request, or write the Security Event Token verification, replay protection and stream management yourself. OpenID back-channel logout covers logout only, and a logout request that gets lost on the way stays lost: there is no retry and nothing to poll. It says nothing about credentials, risk or provisioning either.
With easyssf
The receiver verifies the events and acts on them: it rejects the revoked tokens and ends the sessions in the security layer of your framework, out of the box. The events it cannot act on alone, it hands to a handler of yours. One library, one behaviour, on the JVM, .NET, Go, Rust and Python. Get started with the integration for your framework.
Try it before you commit
The shared-signals.dev playground and caep.dev run public transmitters, so you can send yourself a CAEP event from the browser without an identity provider. The example applications come with a Keycloak setup for the full round trip.
How it works
A transmitter, usually your identity provider, delivers Security Event Tokens (SETs) to your application, either by pushing them to an endpoint or by letting the application poll for them. easyssf verifies each token, skips duplicates and routes the events to the integrations that act on them.
Push or pollRFC 8935 · RFC 8936
A push endpoint on a route of your choice, secured by its own stateless filter chain, or a poller that fetches and acknowledges SETs from the transmitter, with long polling if you want it. Acknowledgements survive a restart, and several instances can share a stream.
Every SET verifiedRFC 8417
Signature against the transmitter's JWK Set, discovered from its .well-known/ssf-configuration,
plus typ, iss, aud, jti, iat and events.
The transmitter and every endpoint it publishes must use HTTPS.
Resource server integration
A CAEP session-revoked event makes the application reject the access tokens of that session,
or all tokens of the user issued before the event: built into the Spring Boot starter, a few lines with
quarkus-oidc.
OIDC client integration
session-revoked and credential-change events invalidate the matching local
sessions, by session id, subject or email.
SCIM EventsRFC 9967
The provisioning changes of a SCIM service provider, users created, patched, deactivated or deleted, arrive
as SETs with a scim subject. SsfScimEventHandler hands them to a method per
operation, and a deactivation ends the user's sessions.
Stream management
Let the application create or update its stream at the transmitter on startup, verify it, and use the
whole stream management API through SsfStreamClient. Several transmitters, several Keycloak
realms say, are each configured by name; the issuer of a SET selects the one that verifies it.
Production details covered
State in your database when there is one, with migration scripts for the schema, Micrometer metrics, a health indicator for Actuator or SmallRye Health, retries with backoff, and the application starts even while the transmitter is down. Processing is at least once; every SET carries an idempotency key for the side effects of your handlers.
Use cases
What a receiver does with the events. The first three are the example applications, each for Spring Boot, Quarkus, .NET, Go and Rust, the first also for Python, with a Keycloak setup to run against; the others are handlers of your own.
Reject revoked access tokens
Description
An OAuth2 resource server trusts an access token until it expires. With a CAEP session-revoked
event the API learns that the session is over and rejects the tokens of that session, or all tokens of the
user issued before the event, from the next request on. Built into the Spring Boot starter; a few lines on
top of quarkus-oidc in Quarkus.
End the sessions of a web application
Description
An OpenID Connect relying party keeps its own session after the login. When the identity provider ends the
session or the user changes a credential, session-revoked and credential-change
events let the application find the local session by session id, subject or email and end it, so that the
next request goes through the login again.
Examples: Spring Boot · Quarkus · .NET · Go · Rust
Mirror users from SCIM Events
Description
A SCIM service provider reports the changes of its users as SCIM Events, RFC 9967, instead of being polled. The application mirrors them into its own directory with a handler per operation, and a deactivation or deletion also ends the user's sessions. The example runs without an identity provider, driven by the test transmitter, because Keycloak does not emit SCIM Events.
Examples: Spring Boot · Quarkus · .NET · Go · Rust
React to RISC account events
Description
RISC events report what happened to the account itself at the identity provider. An
account-disabled event, for a hijacked account say, is the moment to lock the local account and
end its sessions; account-enabled lifts the lock; account-purged says the account
is gone for good, so the user's data can go too. credential-compromise and the identifier events
work the same way. Your SsfEventHandler gets each event with its subject and decides.
See React to any event in Getting started, and the RISC events on the tools page.
Track sessions for threat detection
Description
Not every receiver protects its own sessions; some watch. A session-established event reports a
login with the IP addresses, the user agent fingerprint and the authentication context, and
session-presented that the session was used to sign in to another application. An endpoint or
identity threat detection service, EDR or ITDR, consumes them to build a timeline per user, spot sign-ins from
new places and lateral movement across applications, and alert the security team or have the identity
provider revoke the session.
See the session events on the tools page, and React to any event in Getting started.
Getting started
Each tab shows the steps for one integration, from the Spring Boot starter to the Python packages. Whichever you choose, it is the same receiver: it verifies, de-duplicates and dispatches events the same way on the JVM, .NET, Go, Rust and Python.
Three steps for a Spring Boot application with the servlet stack.
Add the starter
<dependency>
<groupId>org.easyssf</groupId>
<artifactId>easyssf-receiver-spring-boot-starter</artifactId>
<version>0.7.0</version>
</dependency>
From Maven Central, where
all modules are listed. Snapshots of main are on the
Central snapshot repository.
Name the transmitter
easyssf:
receiver:
transmitter-issuer: https://idp.example/realms/demo
expected-audience: https://my-app.example
push:
expected-auth-header: Bearer ${SSF_PUSH_SECRET}
The audience is required, unless the application creates or looks up its stream, which tells it: a receiver that cannot know the audience of its SETs does not start.
Create the stream
Create a stream with push delivery at the transmitter that points to
https://my-app.example/ssf/push and sends the configured header, or set
easyssf.receiver.stream.management: receiver and let the application create it.
With spring-boot-starter-security-oauth2-resource-server or
spring-boot-starter-security-oauth2-client on the classpath, revoked sessions are handled
from then on without further code.
React to any event
@Component
class StepUpHandler extends SsfCaepEventHandler {
@Override
protected void onAssuranceLevelChange(SsfCaepEvent event, SsfEventContext eventContext) {
if ("decrease".equals(event.changeDirection())) {
SsfSubject subject = eventContext.subject();
// subject.subject(), subject.sessionId(), subject.email(), event.currentLevel() ...
}
}
}
SsfCaepEventHandler and SsfRiscEventHandler hand each
CAEP or RISC event of a SET to a method per event type, with its claims typed; SsfEventHandler
gets every verified SET as it is. Handlers run before the SET is acknowledged. If one throws, the
transmitter is expected to deliver the SET again, so a SET is handled at least once and
eventContext.idempotencyKey() is the key for a handler's side effects.
Example applications
Complete Spring Boot applications with a Keycloak setup, in the examples module:
- OAuth2 resource server: rejects the access tokens of revoked sessions.
- OIDC relying party: ends the local sessions the events concern.
- SCIM provisioning: mirrors SCIM users into a local directory from SCIM Events.
Three steps for a Quarkus application.
Add the extension
<dependency>
<groupId>io.quarkiverse.openid-ssf</groupId>
<artifactId>quarkus-openid-ssf-receiver</artifactId>
<version>0.7.0</version>
</dependency>
Or quarkus ext add io.quarkiverse.openid-ssf:quarkus-openid-ssf-receiver.
From Maven Central;
0.7.0 is built on
easyssf 0.7.0: poll delivery that survives restarts and runs on several instances, long polling, SCIM Events
and the typed CAEP and RISC handlers, like the Spring Boot starter. The extension is versioned and released
on its own; the versions coincide this time.
Name the transmitter
quarkus.openid-ssf.receiver.transmitter-issuer=https://idp.example/realms/demo
quarkus.openid-ssf.receiver.events-requested=CaepSessionRevoked,CaepCredentialChange
quarkus.openid-ssf.receiver.push.delivery-endpoint-url=https://my-app.example/ssf/push
quarkus.openid-ssf.receiver.push.expected-auth-header=Bearer ${SSF_PUSH_SECRET}
Create the stream
By default the application creates or updates its stream at the transmitter on startup and tells the transmitter to send the configured header. It authenticates at the stream management API with a client of the transmitter:
quarkus.openid-ssf.receiver.oauth2.token-endpoint=https://idp.example/realms/demo/protocol/openid-connect/token
quarkus.openid-ssf.receiver.oauth2.client-id=my-app
quarkus.openid-ssf.receiver.oauth2.client-secret=${SSF_CLIENT_SECRET}
Or set quarkus.openid-ssf.receiver.stream-management=TRANSMITTER
and the stream-id of a stream an operator created. With quarkus-oidc in the same
application, set quarkus.http.auth.proactive=false, so that the header the transmitter sends to
the push endpoint is not taken for an access token. Rejecting revoked access tokens and ending revoked sessions
take a few lines on top of SsfTokenRevocationEventHandler, a SecurityIdentityAugmentor
in a resource server and a TokenStateManager in a web application; the
examples show both.
React to any event
@ApplicationScoped
public class StepUpHandler extends SsfCaepEventHandler {
@Override
protected void onAssuranceLevelChange(SsfCaepEvent event, SsfEventContext eventContext) {
if ("decrease".equals(event.changeDirection())) {
SsfSubject subject = eventContext.subject();
// subject.subject(), subject.sessionId(), subject.email(), event.currentLevel() ...
}
}
}
Every SsfEventHandler bean is invoked for every verified SET,
before the transmitter gets its answer; SsfCaepEventHandler and SsfRiscEventHandler hand
each CAEP or RISC event to a method per event type, with its claims typed. If a handler throws, the transmitter
is expected to deliver the SET again, so a SET is handled at least once and
eventContext.idempotencyKey() is the key for a handler's side effects.
Example applications
Complete Quarkus applications with a Keycloak setup, in the examples of quarkus-openid-ssf:
- OAuth2 resource server: rejects the access tokens of revoked sessions.
- OIDC relying party: ends the local sessions the events concern.
- SCIM provisioning: mirrors SCIM users into a local directory from SCIM Events.
For any other framework, or none: easyssf-receiver has no framework dependencies. Add it,
assemble the parts you need and call them from the endpoint or scheduler of your application. The Spring Boot
starter and the Quarkus extension are two such integrations.
Add the library
<dependency>
<groupId>org.easyssf</groupId>
<artifactId>easyssf-receiver</artifactId>
<version>0.7.0</version>
</dependency>
A Java module that depends on easyssf-core, Nimbus JOSE + JWT and SLF4J only. Add
easyssf-receiver-jdbc for database-backed stores.
Assemble the receiver
A metadata resolver and a verifier for the transmitter, a processor that de-duplicates and dispatches to your handlers, and a push handler or a poller for the delivery method of your stream. The code below is the whole of it.
Wire it into your framework
Call the push handler from the endpoint the transmitter posts SETs to and return its status
and body, or start the poller from your scheduler. Create the stream at the transmitter, or let
SsfStreamClient do it; SsfTransmitter assembles the parts for one transmitter and
wakes the poller up as soon as the stream is registered.
All of it in one place
SsfHttpClient httpClient = new JdkSsfHttpClient();
String issuer = "https://idp.example/realms/demo";
SsfTransmitterMetadataResolver metadata = new SsfTransmitterMetadataResolver(issuer, null, httpClient);
NimbusSsfSetVerifier verifier = new NimbusSsfSetVerifier(issuer,
() -> metadata.resolve().jwksUri().toString(), httpClient);
verifier.setExpectedAudience("https://my-app.example");
SsfEventHandler handler = (eventContext) -> {
if (eventContext.hasEvent("CaepSessionRevoked")) {
SsfSubject subject = eventContext.subjectFor("CaepSessionRevoked");
// end the session subject.sessionId() of the user subject.subject()
}
};
SsfSetProcessor processor = new SsfSetProcessor(verifier, new InMemorySsfJtiDedupStore(10_000), List.of(handler));
// PUSH: call this from the endpoint the transmitter posts SETs to
SsfPushHandler pushHandler = new SsfPushHandler(processor, "Bearer " + pushSecret);
SsfPushResponse response = pushHandler.handle(authorizationHeader, requestBody);
// POLL: fetch SETs from the transmitter instead
SsfPoller poller = new SsfPoller(httpClient, tokenProvider, () -> pollEndpoint, processor);
poller.start();
Handlers run before the SET is acknowledged. If one throws, the push handler
answers with an error and the poller does not acknowledge the SET, so the transmitter delivers it again. A SET is
claimed in the de-duplication store while its handlers run, so two instances never acknowledge a SET one of them
failed on; eventContext.idempotencyKey() is the key for a handler's side effects.
There is no example application for plain Java yet; the README walks through the assembly, and the handlers of the Spring Boot and Quarkus examples are plain Java you can reuse.
Three steps for an ASP.NET Core application on .NET 10, with easyssf-dotnet, the port of the receiver to .NET: feature complete relative to the Java library, with the same conformance test results, database tables and Keycloak setup, released under the version of the Java library it matches.
Add the packages
<PackageReference Include="EasySsf.Receiver.Hosting" Version="0.7.0" />
<PackageReference Include="EasySsf.Receiver.AspNetCore" Version="0.7.0" />
From NuGet, where all packages are listed:
EasySsf.Receiver.Hosting for any Microsoft.Extensions.Hosting application and
EasySsf.Receiver.AspNetCore for the push endpoint and the revocation hooks; add
EasySsf.Receiver.Data for database-backed stores. .NET 10.
Name the transmitter
{
"EasySsf": {
"Receiver": {
"TransmitterIssuer": "https://idp.example/realms/demo",
"ExpectedAudience": "https://my-app.example",
"Push": { "ExpectedAuthHeader": "Bearer s3cr3t" }
}
}
}
In appsettings.json, bound from EasySsf:Receiver and validated on
start. The audience is required, unless the application creates or looks up its stream, which tells it.
Create the stream
Create a stream with push delivery at the transmitter that points to
https://my-app.example/ssf/push and sends the configured header, or set
"Stream": { "Management": "Receiver" } and let the application create it.
AddSsfTokenRevocation() then rejects the access tokens of revoked sessions and users in a
JwtBearer scheme, and AddSsfSessionRevocation() signs revoked cookie sessions out on their
next request, one line each.
React to any event
var builder = WebApplication.CreateBuilder(args);
builder.AddSsfReceiver() // binds EasySsf:Receiver, validates on start
.AddEventHandler<StepUpHandler>(); // any ISsfEventHandler, SsfCaepEventHandler, ...
var app = builder.Build();
app.MapSsfPush(); // POST /ssf/push: the SET authenticates itself
app.Run();
class StepUpHandler(IStepUp stepUp) : SsfCaepEventHandler
{
protected override Task OnAssuranceLevelChangeAsync(SsfCaepEvent caepEvent, SsfEventContext eventContext,
CancellationToken cancellationToken)
{
return (caepEvent.ChangeDirection == "decrease")
? stepUp.RequireAsync(eventContext.Subject.Subject, caepEvent.CurrentLevel, cancellationToken)
: Task.CompletedTask;
}
}
SsfCaepEventHandler, SsfRiscEventHandler and
SsfScimEventHandler hand each event of a SET to a method per event type, with its claims typed;
ISsfEventHandler gets every verified SET as it is. Handlers run before the SET is acknowledged.
If one throws, the transmitter is expected to deliver the SET again, so a SET is handled at least once and
eventContext.IdempotencyKey is the key for a handler's side effects.
Example applications
Complete ASP.NET Core applications with a Keycloak setup, in the examples of easyssf-dotnet:
- OAuth2 resource server: rejects the access tokens of revoked sessions.
- OIDC relying party: rejects the cookie of a session Keycloak ended, or whose password changed.
- SCIM provisioning: mirrors SCIM users into a local directory from SCIM Events.
Three steps for a Go application on net/http, or chi, gorilla/mux, gin or echo, with
easyssf-go, the port of the receiver to Go: feature complete
relative to the Java library, with the same conformance test results, database tables and Keycloak setup,
released under the version of the Java library it matches.
Add the module
go get github.com/easyssf/easyssf-go@v0.7.0
One module: receiver is the receiver, ssf the vocabulary of SETs, subjects
and events, receiver/sqlstore the stores on database/sql for SQLite, PostgreSQL and
MySQL, and ssftest a transmitter for your tests. Go 1.26 or later, no cgo.
Name the transmitter
easyssf:
receiver:
transmitter-issuer: https://idp.example/realms/demo
expected-audience: https://my-app.example
push:
expected-auth-header: "Bearer s3cr3t"
The keys of the Spring Boot starter, bound into receiver.Config with
yaml.v3, koanf, viper or encoding/json over receiver.DefaultConfig(),
and validated when the receiver is built. The audience is required, unless the application creates or
looks up its stream, which tells it.
Create the stream
Create a stream with push delivery at the transmitter that points to
https://my-app.example/ssf/push and sends the configured header, or set
stream.management: receiver and let the application create it.
receiver.RevocationMiddleware then rejects the access tokens of revoked sessions and users
behind your token validation, and a SessionTerminator over your session store ends the sessions
the events name.
React to any event
rcv, err := receiver.New(config, // validated here, every failure at once
receiver.WithLogger(slog.Default()),
receiver.WithHandler(receiver.Caep(stepUp{}))) // any Handler; Caep, Risc and Scim dispatch by type
if err != nil {
log.Fatal(err)
}
rcv.Start(ctx) // registers the stream, starts polling
defer rcv.Stop(context.Background()) // sends the acknowledgements it owes
mux.Handle("POST "+rcv.PushEndpointPath(), rcv.PushHandler()) // POST /ssf/push: the SET authenticates itself
type stepUp struct{ receiver.NoopCaepHandler }
func (stepUp) OnAssuranceLevelChange(ctx context.Context, event *caep.Event, set *receiver.Context) error {
if event.ChangeDirection() == "decrease" {
return requireStepUp(ctx, set.Subject().Sub(), event.CurrentLevel())
}
return nil
}
receiver.Caep, receiver.Risc and
receiver.Scim hand each event of a SET to a method per event type, with its claims typed;
receiver.ForEventFunc takes a function for one event type, and a receiver.Handler
gets every verified SET as it is. Handlers run before the SET is acknowledged. If one returns an error or
panics, the transmitter is expected to deliver the SET again, so a SET is handled at least once and
the SET's jti is the key for a handler's side effects.
Example applications
Complete Go applications with a Keycloak setup, in the examples of easyssf-go:
- OAuth2 resource server: rejects the access tokens of revoked sessions, pushed or polled.
- OIDC relying party: ends the local session Keycloak revoked, or whose password changed.
- SCIM provisioning: mirrors SCIM users into a local directory from SCIM Events.
Three steps for a Rust application on axum, with easyssf-rust, the port of the receiver to Rust: feature complete relative to the Java library, with the same database tables and Keycloak setup, released under the version of the Java library it matches. actix-web has a crate of its own, other frameworks call the push handler directly.
Add the crates
[dependencies]
easyssf-receiver = "0.7.0"
easyssf-receiver-axum = "0.7.0"
From crates.io: easyssf-receiver
is the receiver without a web framework, easyssf-receiver-axum the push router and the
revocation layers for axum, or easyssf-receiver-actix-web for actix-web; add
easyssf-receiver-sqlx for database-backed stores. Rust 1.94 or later.
Name the transmitter
[easyssf.receiver]
transmitter-issuer = "https://idp.example/realms/demo"
expected-audience = "https://my-app.example"
[easyssf.receiver.push]
expected-auth-header = "Bearer s3cr3t"
The keys of the Spring Boot starter, deserialized with serde into SsfReceiverConfig
from TOML, YAML, JSON or the environment through figment, config-rs or the crate of your choice, and
validated when the receiver is built. The audience is required, unless the application creates or looks up
its stream, which tells it.
Create the stream
Create a stream with push delivery at the transmitter that points to
https://my-app.example/ssf/push and sends the configured header, or set
management = "receiver" under [easyssf.receiver.stream] and let the application
create it. SsfRevocationLayer then rejects the access tokens of revoked sessions and users behind
your token validation, and SsfSessionRevocationLayer signs revoked tower-sessions out on their next
request.
React to any event
use easyssf_receiver::{BoxError, SsfReceiver, caep::{SsfCaepEventHandler, caep}, event::SsfEventContext};
use easyssf_receiver_axum::push_router_for;
let config: SsfReceiverConfig = figment.extract_inner("easyssf.receiver")?;
let receiver = SsfReceiver::builder(config) // validates the configuration
.handler(caep(StepUp)) // any SsfEventHandler; caep, risc and scim dispatch by type
.build()?;
receiver.start(); // registers the stream, starts polling
let app = Router::new().merge(push_router_for(&receiver)); // POST /ssf/push: the SET authenticates itself
struct StepUp;
impl SsfCaepEventHandler for StepUp {
async fn on_assurance_level_change(&self, event: SsfCaepEvent, context: SsfEventContext) -> Result<(), BoxError> {
if event.change_direction().as_deref() == Some("decrease") {
step_up.require(context.subject().subject(), event.current_level()).await?;
}
Ok(())
}
}
SsfCaepEventHandler, SsfRiscEventHandler and
SsfScimEventHandler hand each event of a SET to a method per event type, with its claims typed;
for_event takes a closure for one event type, and an SsfEventHandler gets every verified
SET as it is. Handlers run before the SET is acknowledged. If one returns an error, the transmitter is
expected to deliver the SET again, so a SET is handled at least once and
context.idempotency_key() is the key for a handler's side effects.
Example applications
Complete axum applications with a Keycloak setup, in the examples of easyssf-rust:
- OAuth2 resource server: rejects the access tokens of revoked sessions, pushed or polled, with Prometheus metrics.
- OIDC relying party: ends the tower-sessions session Keycloak revoked, or whose password changed.
- SCIM provisioning: mirrors SCIM users into a local directory from SCIM Events.
Three steps for a Python application on FastAPI, with easyssf-python, the port of the receiver to Python on asyncio: at feature parity with the Java library, with the same configuration keys and Keycloak setup, released under the version of the Java library it matches. Other frameworks mount the push endpoint as an ASGI or a WSGI app.
Add the packages
pip install easyssf-receiver-fastapi==0.7.0
From PyPI, or with
uv add: easyssf-receiver is the receiver without a web framework, which
easyssf-receiver-fastapi brings along with the push router, the revocation dependency and the
lifespan for FastAPI; easyssf-test is the test transmitter. Python 3.11 or later.
Name the transmitter
easyssf:
receiver:
transmitter-issuer: https://idp.example/realms/demo
expected-audience: https://my-app.example
push:
expected-auth-header: "Bearer s3cr3t"
The keys of the Spring Boot starter, read by ReceiverConfig.from_mapping from a
parsed YAML, TOML or JSON file or any mapping, and validated when the receiver is built; a key it does not
know is an error that names the one it resembles. The audience is required, unless the application creates
or looks up its stream, which tells it.
Create the stream
Create a stream with push delivery at the transmitter that points to
https://my-app.example/ssf/push and sends the configured header, or set
stream.management: receiver and let the application create it.
revocation_dependency then rejects the access tokens of revoked sessions and users behind your
token validation, and a session_terminator given to the receiver ends server-side sessions as
the event arrives.
React to any event
from fastapi import FastAPI
from easyssf.core import caep
from easyssf.fastapi import push_router_for, receiver_lifespan
from easyssf.receiver import CaepHandler, EventContext, Receiver, ReceiverConfig, caep_handler
class StepUp(CaepHandler):
async def on_assurance_level_change(self, event: caep.Event, context: EventContext) -> None:
if event.change_direction == "decrease":
await step_up.require(context.subject.sub, event.current_level)
config = ReceiverConfig.from_mapping(settings["easyssf"]["receiver"])
receiver = Receiver(config, handlers=[caep_handler(StepUp())]) # validates the configuration
app = FastAPI(lifespan=receiver_lifespan(receiver)) # registers the stream, starts polling
app.include_router(push_router_for(receiver)) # POST /ssf/push: the SET authenticates itself
CaepHandler, RiscHandler and
ScimHandler hand each event of a SET to a method per event type, with its claims typed;
for_event takes a function for one event type, and any async def, plain function or
object with an async handle(context) method gets every verified SET as it is. Handlers run before
the SET is acknowledged. If one raises, the transmitter is expected to deliver the SET again, so a SET is
handled at least once and a handler's side effects should be idempotent.
Example applications
A complete FastAPI application with a Keycloak setup, in the examples of easyssf-python:
- OAuth2 resource server: rejects the access tokens of revoked sessions, pushed or polled.
Subjects as the spec defines them
SsfSubject is the sub_id of the SET: a subject identifier in any RFC 9493 format
(iss_sub, email, opaque, account, phone_number,
did, uri, aliases), the scim format of RFC 9967, or a complex subject with its user,
session, device, tenant and other members. Shortcuts cover the common
cases, nothing is lost.
Your own event type aliases
The SSF, CAEP and RISC event types have built-in aliases such as CaepSessionRevoked. Register
aliases for vendor specific event types, in configuration or in code, and use them wherever an event type is
named. The URIs stay canonical; an alias can never redefine another.
Test your receiver
easyssf-test brings a transmitter that runs inside your test JVM: it signs SETs, serves metadata
and keys, hands out tokens and emulates the stream and poll endpoints. Push a revocation, assert the effect.
The tests of the Spring Boot starter and of the Quarkus extension use it.
Code
One receiver in six repositories on GitHub, each with its examples, Keycloak setup and tests, on one release line, currently 0.7. The Java library sets the line: the .NET, Go, Rust and Python ports follow its minor version once they are at feature parity, with the same configuration keys and database tables, and release patches of their own in between. The Quarkus extension, a Quarkiverse project, is versioned on its own and names the easyssf release it is built on.
easyssf-java
Latest version: 0.7.0
The Java library: the receiver, the Spring Boot starter, the JDBC stores and the test transmitter.
On Maven Central under org.easyssf.
quarkus-openid-ssf
Latest version: 0.7.0
The Quarkus extension is based on the easyssf Java library, with Dev UI and native image support. On Maven Central under
io.quarkiverse.openid-ssf.
easyssf-dotnet
Latest version: 0.7.0
The port for .NET 10: hosting, the ASP.NET Core integration, the ADO.NET stores and test support. On NuGet.
easyssf-go
Latest version: 0.7.0
The port for Go 1.26: the receiver on net/http, the stores on database/sql and
the test transmitter, in one module.
easyssf-rust
Latest version: 0.7.0
The port for Rust 1.94: the receiver, axum and actix-web, the sqlx stores and the test transmitter. On crates.io.
easyssf-python
Latest version: 0.7.0
The port for Python 3.11: the asyncio receiver, the FastAPI integration and the test transmitter. On PyPI.
Interoperability
Keycloak
Tested with the SSF transmitter of Keycloak 26.8 (--features=ssf). The examples ship a
pre-configured realm, and the README documents Keycloak's audience, scopes and single-stream rule.
caep.dev
Point the receiver at caep.dev, SGNL's free hosted transmitter, to receive CAEP events sent from a browser without running an identity provider. See Tools.
OpenID conformance suite
The receiver test plans of the OpenID conformance suite, default and CAEP interop profile with push and poll delivery, run against the receiver in an automated test module.
Standards
Built on the OpenID Shared Signals specifications and the IETF security event RFCs, see Specifications for the complete list and what easyssf takes from each. easyssf is listed in the shared-signals.dev directory of Shared Signals implementations.
Specifications
What easyssf implements, and where each piece is defined.
| Specification | Defines | In easyssf |
|---|---|---|
| OpenID Shared Signals Framework 1.0 | Transmitters, receivers, streams, transmitter metadata discovery, stream verification | Metadata discovery, stream management and verification, the SSF event types |
| OpenID CAEP 1.0 | Continuous Access Evaluation Profile: session-revoked, credential-change, assurance-level-change and the other session and credential events |
Event type aliases, SsfCaepEvent and SsfCaepEventHandler, the resource server and OIDC client integrations |
| OpenID CAEP Interoperability Profile 1.0 | The minimum a CAEP transmitter and receiver must support to work together | The CAEP interop plans of the conformance tests |
| OpenID RISC Profile 1.0 | Risk Incident Sharing and Coordination: account disabled, purged, credential compromise and the other account events | Event type aliases, SsfRiscEvent and SsfRiscEventHandler for your own handlers |
| RFC 8417 | Security Event Token (SET): the JWT profile every event is delivered in | Verification of signature, typ, iss, aud, jti, iat and events |
| RFC 8935 | Push-based SET delivery over HTTP | The push endpoint and its responses |
| RFC 8936 | Poll-based SET delivery over HTTP | The poller, long polling, acknowledgements and setErrs |
| RFC 9493 | Subject identifiers for SETs: account, email, iss_sub, opaque, phone_number, did, uri, aliases |
SsfSubjectIdentifier, every format, and SsfSubject for complex subjects; the matching of events to sessions and users |
| RFC 9967 | SCIM Events: the provisioning changes of a SCIM service provider as SETs, the scim subject identifier, full and notice events |
Event type aliases, SsfScimSubject, SsfScimEvent and SsfScimEventHandler; session termination for deactivated and deleted users |
| RFC 7515 / RFC 7517 | JSON Web Signature and JSON Web Key | Signature checks against the transmitter's JWK Set, with Nimbus JOSE + JWT |