Token issue event listener SPIs

1. Introduction

The Connect2id server exposes two Java Service Provider Interfaces (SPI) for installing token issue event listeners:

Every time the Connect2id server issues an ID or access token, the installed listeners will get notified. The events can be used to monitor sign-in activity and OAuth 2.0 authorisations in real time, for purposes such as security audit logging and usage metering.

The two SPIs enable developers to implement arbitrary listener logic. The token issue events can for instance be fed into a message queue, time series database or some other event sink.

Important: The listeners are called synchronously, so if you expect the listener logic to block or spend more than a few milliseconds to process an event, do that in a separate thread.

If the Connect2id server detects an SPI implementation for an ID token issue event listener it will log its loading under OP0211, for an access token listener under OP0213.

INFO main MAIN - [OP0211] Loaded ID token issue event listener [1]: com.nimbusds.openid.connect.provider.spi.events.aws.sqs.TokenEventSQSPublisher
INFO main MAIN - [OP0213] Loaded access token issue event listener [1]: com.nimbusds.openid.connect.provider.spi.events.aws.sqs.TokenEventSQSPublisher

The token issue event SPIs were introduced in Connect2id server v6.16 and updated in v6.17.

2. Emitting signed Security Event Tokens (SET)

To cryptographically assert the issuer of the event, it can be encoded into a Security Event Token (SET) signed with the same RSA key which the Connect2id server uses for its JWT-encoded access tokens:

class SignInListener implements IDTokenIssueEventListener {

    @Override
    public void init(InitContext initContext) throws Exception {
        // nothing to init
    }

    @Override
    public boolean isEnabled() {
        return true;
    }

    @Override
    public void idTokenIssued(IDTokenIssueEvent event, EventContext ctx) {

        // Get the ID token claims, such as "sub" and "iat"
        JWTClaimsSet idTokenClaims = event.getJWTClaimsSet();

        // Compose SET
        JWTClaimsSet setClaims = ...

        SignedJWT set = ctx.getJWTSigner().sign(setClaims);

        // Output SET where required
    }


    @Override
    public void shutdown() throws Exception {
        // Shut down hook
    }
}

3. Token event publisher for AWS Simple Queue Service

Connect2id maintains an implementation of the listener SPIs which publishes ID and access token issue events to an AWS Simple Queue Service (SQS). The source code is available for free reuse and modification (Apache 2.0 license).

https://bitbucket.org/connect2id/token-event-publisher-for-aws-sqs

The events are published as JSON objects which include selected claims from the issued token. Java system properties can also be included in the event.

Example token issue event indicating the subject and the issue time; the other token claims are filtered out:

{
  "sub" : "alice",
  "iat" : 1523304728
}

4. Support

Our Connect2id support team is available if you need help with integrating events into your server.