Shared Signals Framework receivers for Java

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.

Getting started

easyssf comes as a starter for Spring Boot and, through the Quarkiverse extension quarkus-openid-ssf, as an extension for Quarkus. Both are built on the same receiver library and verify, de-duplicate and dispatch events the same way.

<dependency>
    <groupId>org.easyssf</groupId>
    <artifactId>easyssf-receiver-spring-boot-starter</artifactId>
    <version>0.1.0-SNAPSHOT</version>
</dependency>

easyssf:
  receiver:
    transmitter-issuer: https://idp.example/realms/demo
    expected-audience: https://my-app.example
    push:
      expected-auth-header: Bearer ${SSF_PUSH_SECRET}

@Component
class StepUpHandler implements SsfEventHandler {

    @Override
    public void handle(SsfEventContext eventContext) {
        if (eventContext.hasEvent("CaepAssuranceLevelChange")) {
            SsfSubject subject = eventContext.subjectFor("CaepAssuranceLevelChange");
            Map<String, Object> event = eventContext.eventFor("CaepAssuranceLevelChange");
            // subject.subject(), subject.sessionId(), subject.email() ...
        }
    }

}

<dependency>
    <groupId>io.quarkiverse.openid-ssf</groupId>
    <artifactId>quarkus-openid-ssf-receiver</artifactId>
    <version>0.2.0</version>
</dependency>

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}

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}

@ApplicationScoped
public class StepUpHandler implements SsfEventHandler {

    @Override
    public void handle(SsfEventContext eventContext) {
        if (eventContext.hasEvent("CaepAssuranceLevelChange")) {
            SsfSubject subject = eventContext.subjectFor("CaepAssuranceLevelChange");
            Map<String, Object> event = eventContext.eventFor("CaepAssuranceLevelChange");
            // subject.subject(), subject.sessionId(), subject.email() ...
        }
    }

}

Modules

Everything is published under the group id org.easyssf. The Quarkus extension is a Quarkiverse project with its own coordinates.

Without Spring Boot or Quarkus

easyssf-receiver has no framework dependencies. Assemble the parts you need and call them from the endpoint or scheduler of your framework. The Spring Boot starter and the Quarkus extension are two such integrations.

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();

Interoperability

Not included yet: Spring WebFlux applications and long polling.

Specifications

What easyssf implements, and where each piece is defined.

News

Releases and other changes worth knowing about.

All news