Event subscribers
Event bus instantiation
Airlock IAM emulates a centralized event bus for the Loginapp and the Adminapp by instantiating one event bus for every incoming request and registering the configured event subscribers.
Every event subscriber must configure an event type for which this subscriber will be processed. E.g., the event type Logged in from New Device will only be handled by the event subscriber that is configured for this event type.
Airlock IAM currently supports the following types of event subscribers:
Loginapp | Adminapp | |
|---|---|---|
Email Event Subscriber | ||
Remote Event Subscriber | ||
SMS Event Subscriber | ||
Gateway Session Terminator |
Currently, only the modules Loginapp and Adminapp can configure event subscribers. Loginapp and Adminapp handle event requests as exclusive processes.
Because the Loginapp and the Adminapp run as separate processes, you may need to configure the same event subscriber in both modules, to ensure that the event will be processed in all cases. For this reason, event subscribers can be configured under Event Settings, which is at the top level in both modules.
Email Event Subscriber
The Email Event Subscriber plugin sends email messages with event details. The plugin's configuration defines the recipient, who may, for example, be the end-user or an administrator.
Event attributes (see Event attributes) can be referenced to include event data in both the email subject and body. For further information, refer to the plugin documentation in the Config Editor.
Remote Event Subscriber
The Remote Event Subscriber plugin connects to a remote HTTP endpoint using the configured HTTP Method and Content Type. It can, for example, be used to send event data to a remote REST API.
Event attributes (see Event attributes) can be referenced to include event data in both the request URL and the request body. For further information, refer to the plugin documentation in the Config Editor.
SMS Event Subscriber
The SMS Event Subscriber plugin allows you to send event-triggered SMS notifications to multiple phone numbers at the same time. Depending on the configured Phone Number Providers, SMS notifications will be sent either to the phone number stored in the credential or token data model, or to the one dynamically provided in the current flow. It is not possible to configure a preferred communication mobile phone number.
In case of an MTAN Token Phone Number Changed event, it is also possible to send the message to the old (replaced) phone number.
Example:
Event attributes (see Event attributes) can be referenced to include event data text messages. Refer to the plugin documentation in the Config Editor for further information.
Phone number provider plugins | mTAN handler | Description |
|---|---|---|
All Phone Numbers Provider | Token Data mTAN Handler | This handler can hold multiple phone numbers. |
Credential Data mTAN Handler | This handler can only hold a single phone number. We recommend using the Token Data mTAN Handler instead. | |
Old Phone Number Provider | – | Provides the user's old phone number in case of a phone number change or deletion. |
Phone Numbers from String Value Providers | - | Allows you to configure value providers to dynamically supply recipient phone numbers. You can use the standard IAM string value providers. For example, the context-data-map value provider to obtain the phone number from the user context data, or the script-execution-result value map value provider to retrieve the number from a scriptable step. For a use case, see Phone Numbers from String Value Providers - Use case |
Gateway Session Terminator
The Gateway Session Terminator event subscriber ends the end-user’s sessions in Airlock Gateway when a triggering event occurs. This feature enforces security consistency across the end-user's devices.
When the event is triggered, the Gateway Session Terminator plugin contacts one or more Airlock Gateways via their REST APIs to terminate the sessions of the end-user. You can exclude the session that triggered the event, if needed.
For this feature to work, the Gateway audit token must contain only the end-user's user ID. Furthermore, IAM must be able to open HTTP(s) connections to the Airlock Gateways. Depending on your setup, this may require changes to your network topology.
For more information, see Gateway Session Terminator.
The Gateway Session Terminator event subscriber is only relevant when Airlock IAM is operated together with Airlock Gateway.
Although the new plugin improves security, it cannot guarantee the termination of all end-user Gateway sessions on all occasions. This limitation is due to the following factors:
- Communication issues: IAM may encounter problems when communicating with Airlock Gateway. In such cases, requests to terminate end-user sessions are not executed at all.
- Missing audit tokens: In rare cases, an end-user may have an active Gateway session that lacks a Gateway audit token due to race conditions. Without this token, IAM cannot identify and terminate the session.
Filtered Flow Event
This event subscriber is only available for the Loginapp.
For most use cases, directly configuring the event type this subscriber needs to process is sufficient. A Filtered Flow Event can be used if more fine-grained control is required.
The Filtered Flow Event plugin allows additional selection criteria to be added.
The plugin contains the following (filter) properties:
- Event is a mandatory field to set the event type.
- Step ID Pattern is a pattern to filter for step ID.
- Flow ID Pattern is a pattern to filter for flow ID/application ID.
- Required Flow Type offers several options to filter for the type of flow that generated the event.
All criteria must match (logical AND) if multiple selection criteria are set.
Example:
MTAN Token Registered events can be issued in different flows (self-registration, protected self-service). An email message is sent to notify the user about this event and to use a different communication channel. The content of the email depends on the flow that created the event. Specifying Flow ID Pattern conditions in the Email Event Subscriber will achieve the desired result.
Event filtering
Some event types support event-specific filtering - for example, the User Locked event or the Context Data Changed event. The corresponding event plugins provide additional filter fields that allow you to define these filters. The event subscriber will only handle those events that match the defined filter criteria, such as a specific lock reason or particular changed context-data fields.