Skip to content
Connect2id

Token issue events

1. Overview

The Connect2id server exposes two plugin interfaces (SPIs) for receiving token issue events:

Every time the Connect2id server issues an ID or access token, any 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, a time series database or some other event sink.

Important: The listeners are called synchronously. If the listener logic is expected to block or spend more than a few milliseconds to process an event, it should run 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 enabled=true
INFO main MAIN - [OP0213] Loaded access token issue event listener [1]: com.nimbusds.openid.connect.provider.spi.events.aws.sqs.TokenEventSQSPublisher enabled=true

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

2. Issuing 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).

Git repohttps://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
}