Event Listeners

Server events are triggered by the Curity Identity Server on certain notable occurrences, such as a new user account being created.

Use Cases#

They allow Event Listeners to react to such events, implementing custom logic as necessary.

A simple Event Listener may, for example, send out an email every time a new user account is created. A more advanced example, perhaps, would be to send a request to a login analysis service every time a user logs in, such that further action could be taken upon the detection of suspicious login patterns.

This page documents the basic Server Events components, linking to the appropriate parts of the documentation for more details on the different parts of the system.

Getting Started#

To configure event listeners in the Admin UI, navigate to System → Event Listeners. From there you can create script-based event listeners or configure event listener plugins.

Event Listeners configuration in Admin UI

Event Listener Variations#

The Curity Identity Server supports three categories of event listeners, each suited for different scenarios:

Script Event Listeners

Script event listeners execute scripts in reaction to server events. Configure and modify script logic through the server configuration without requiring a restart. These listeners suit scenarios that need simple event handling, quick prototyping, or configuration-driven responses.

Explore the Script Event Listeners page for implementation details, configuration examples, and best practices.

Event Listener Plugins

Event listener plugins , like script event listeners, perform custom actions in reaction to a Server Event.

They should be preferred when the required logic is too complex to be implemented in a script event listener.

To create an event listener plugin, a plugin descriptor must inherit from EventListenerPluginDescriptor.

To learn more about plugins, see the plugins section.

Event Listeners provided by other Plugins.

Besides the event listener plugins, it’s also possible to provide event listeners from the following plugin types:

These are scoped to specific profiles and only receive events from their associated profile or linked profiles.

This allows plugins of these types to react when certain events happen, which can be necessary for the plugin to provide its main functionality correctly. For example, the Opt-In MFA action can cleanup MFA user data when one of the account deletion events happen.

An important distinction between event listeners provided by the above plugins is that, unlike those provided by script and event listener plugins, they are scoped to a particular profile, hence will only receive events that are published from the same profile or from a profile that links to it.

For example: events published from a User Management Profile will be received by:

  • the OAuth Profile linked to the User Management Profile, if any.
  • the Authentication Profile linked to by that OAuth Profile, if any.

Global events like SystemEvent and DistributedCacheEvent are not received by profile-scoped event listeners.

To activate an event listener, it must be added to the list of active event listener instances. It is not enough to just create and configure the plugin or script event-listener.

Event Types and Hierarchy#

All Events that can occur in the server are subtypes of the Event interface.

Some notable types are (not mutually exclusive):

  • SystemEvent - events related to configuration changes.
  • OAuthEvent - events originating from the Token Profile, including TokenOAuthEvent (issuance or revocation of tokens) and ProblemOAuthEvent (problems when trying to issue tokens).
  • AccountEvent - events related to accounts (see the note below for important information about them).
  • DeniedIntrospectionEvent - problems related to token/nonce introspection. Very useful to debug user issues.
  • ScimEvent - events originating from the SCIM API (User Management).
  • GraphQLEvent - events originating from the GraphQL APIs.
  • AuditableEvent - potentially auditable events (includes a large number of events).
  • DeviceEvent - events related to user devices.
  • CredentialManagerEvent - events related to credential verification and updates.

Most of the above types have several subtypes, and an event may have multiple supertypes. For example, the AccountUpdatedScimEvent is a subtype of both ScimEvent and AuditableEvent.

When an EventListener registers to listen for a certain type, it will be notified if any of its subtypes, including itself, are published.

The AccountEvent subtypes happen when an Account Manager acts on the account. However, GraphQLEvent and ScimEvent are not subtypes of AccountEvent since those events may happen without using an Account Manager. For this reason, CreatedAccountEvent and DeletedAccountEvent are not supertypes of AccountCreatedScimEvent and AccountDeletedScimEvent, respectively, nor of AccountCreatedGraphQLEvent and AccountDeletedGraphQLEvent. This means that to reliably listen for events related to accounts may require listening to all 3 types of events: AccountEvent, GraphQLEvent and ScimEvent.

Learn more#

For comprehensive documentation on available event types and their properties, refer to the Event Interface Documentation.

For practical implementation guidance and advanced integration patterns:

Was this helpful?