Products » Connect2id server » Documentation » Integration »

Subject (end-user) authentication and consent event listener SPI

1. Overview

The Connect2id server exposes a plugin interface (SPI) for receiving an event every time an end-user gets authenticated and submits their consent at the authorisation endpoint. The events can be used to monitor user activity in real time, for purposes such as audit logging.

2. The SPI

The SubjectAuthAndConsentEventListener SPI has the following features:

  • Provides an initialisation method, to configure the listener or establish a database connection.

  • Every event provides access to:

    • The subject (end-user) ID. This is always the local ID, including when the client is registered to receive pairwise IDs.
    • The client ID.
    • The ID token claims set, if an ID token is issued.
    • The consented scope and claim names, if any.
    • The authorisation data, if any.
    • The associated subject session. Note, in the edge case when the session expires in the time window between the event and its dispatch, the session reference will not be provided.

  • Every event further provides a context with access to:

    • The issuer URL.
    • The registered information for the client ID.
    • An interface for signing JWTs using a Connect2id server signing key.

  • For clients using the code flow (response_type=code), the event is dispatched when the client submits a valid authorisation code at the token endpoint of the Connect2id server.

  • For clients using an implicit (response_type=token, response_type=id_token, id_token token) or hybrid flow (response_type=code id_token, response_type=code token, response_type=code id_token token), the event is dispatched when the request at the authorisation endpoint of the Connect2id server successfully completes.

Note that at present the event does not distinguish between regular and prompt=none requests at the authorisation endpoint.

The SPI enables developers to implement arbitrary listener logic. The events can for instance be fed into a message queue, a time series database or some other event sink.

Important: The listener is 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 authentication and consent event listener it will log its loading under OP0211.

INFO main MAIN - [OP0215] Loaded subject auth + consent event listener [1]: class=com.nimbusds.openid.connect.provider.spi.events.aws.sqs.SubjectEventSQSPublisher enabled=true

This event SPI was introduced in Connect2id server v15.6.

3. Issuing signed Security Event Tokens (SET)

The authentication and consent event can be cryptographically secured, by encoding it into a Security Event Token (SET). The token issue event listener documentation provides an example.