easyssf

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.

The transmitter pushes signed Security Event Tokens to your application, or the application polls for them periodically; inside the application the easyssf receiver library verifies them and acts on the resource server, the OIDC client and your handlers Transmitter identity provider, e.g. Keycloak signs SETs with its JWK Set Your application Spring Boot, Quarkus or any other JVM application; easyssf-receiver is a library inside it easyssf receiver verify the SET · RFC 8417 skip duplicates (jti) dispatch to event handlers stream management · metrics state in memory or in your database Resource server rejects revoked access tokens OIDC client ends the sessions concerned Your handlers step-up, audit, anything else push · RFC 8935 periodically poll · RFC 8936 SET SET

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

Identity provider revokes a session Client still holds the token API easyssf receiver marks the session as revoked rejects its tokens with 401 session-revoked request with the old token

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

Identity provider logout, new password Browser has a session cookie Web application easyssf receiver finds the session by sid, sub or email ends it: the next request logs in again session-revoked credential-change next request

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.

Mirror users from SCIM Events

SCIM provider users and groups Local directory of the application Application easyssf receiver handler per operation: create, patch, put, … deactivate and delete end the user's sessions prov:create · patch deactivate · delete create, update, deactivate users

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.

React to RISC account events

Identity provider account state changes Local accounts and the user's data Application your SsfEventHandler disabled: lock the account, end sessions enabled: unlock purged: delete data account-disabled enabled · purged lock, unlock, delete

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.

Track sessions for threat detection

Identity provider logins and sign-ins Security team SIEM, SOC Detection service EDR / ITDR · easyssf timeline per user: IPs, user agent, acr detects new locations and lateral movement session-established session-presented alerts, revocation requests

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.

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.

Select your platform:
Pick your integration:

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:

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.

easyssf is pre-1.0 and its API may still change. The Java modules are on Maven Central, the .NET packages on NuGet, the Go module at pkg.go.dev, the Rust crates on crates.io, the Python packages on PyPI and the source on GitHub. See the README for the complete configuration reference of the Spring Boot starter, and the README of quarkus-openid-ssf for the one of the Quarkus extension.

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.

Java

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.

Spring Boot 4.1 Java 21+
Java

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.

Quarkus 3.27
.NET

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.

.NET 10
Go

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.

Go 1.26+
Rust

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.

Rust 1.94+
Python

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.

Python 3.11+

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.

SpecificationDefinesIn 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

News

Releases and other changes worth knowing about.

See the news page.

All news