Airlock 2FA Push Event Subscriber

The Airlock 2FA Push Event Subscriber plugin sends custom notification messages to the Airlock 2FA app whenever a configured IAM event occurs.

Typical use cases are notifications about security-relevant events, for example:

  • the end-user's password has changed,
  • an Airlock 2FA device was registered or deleted,
  • a login from a new device was detected.

The following plugins are available:

  • Airlock 2FA Push Event Subscriber (Loginapp) for events from the Loginapp.
  • Airlock 2FA Push Event Subscriber (Adminapp) for events from the Adminapp.

The notification is sent to all Airlock 2FA devices enrolled for the affected user's Airlock 2FA account. Sending a notification to an individual device or broadcasting them to multiple users or user groups is not supported.

The message is delivered through Futurae's Auth API, using the credentials defined in the global Airlock 2FA settings in the IAM configuration.

Prerequisites

The following prerequisites apply:

  • An Airlock 2FA Advanced Subscription is required.
  • The custom Airlock 2FA app message feature must be enabled in the Futurae service. If it is disabled, no notifications are delivered.
  • The Airlock 2FA app requires version 3.1.5 or later (iOS and Android).
  • Airlock 2FA must be configured and operational in Airlock IAM. This includes the global Airlock 2FA settings and the Futurae server settings (defined in the Airlock 2FA Settings plugin and the Futurae Server plugin, respectively).
  • The affected end-user must have an Airlock 2FA account with at least one enrolled device.

Configuration

Configuration of the event subscriber for the Loginapp

  1. In the Config Editor, go to
    Loginapp >> Event Settings
  2. In the Basic Settings section, Event Subscribers list, add an Airlock 2FA Push Event Subscriber (Loginapp) plugin.
    Note: Add one plugin for each event that should trigger push notifications.
  3. Edit the plugin as follows:
    • Airlock 2FA Settings: Select the Airlock 2FA Settings plugin that defines your global Airlock 2FA settings.
    • Payload Entries: This field defines the content of the notification pushed to the 2FA app, configured with the Airlock 2FA Information Item plugin. You can add more than one plugin. For the configuration details, see Notification content configuration below.
    • Language: Specifies the notification language. Select the predefined String Context Data Value Provider - Existing Language plugin from the drop-down list. The event subscriber will then use the current end-user’s preferred language for the notification.
    •  
      Notice

      If the end-user's preferred language is not one of the valid Loginapp languages, the notification will be sent in the default Loginapp language.

      The language settings for the Loginapp are configured in the Language Settings plugin (Loginapp >> Language Settings).

    • Value Map Providers (optional): Specifies value providers for mapping keys in the notification content. For details, see Customized notification text below.
    • Event: Specifies the event that triggers the notification, for example Password Changed or Airlock 2FA Device Deleted. The Plugin class drop-down list contains all available events. Note that notifications can only be triggered by events that involve end-users.
  5. You have now configured an Airlock 2FA Push Event Subscriber (Loginapp) that notifies a user's 2FA app whenever the specified event occurs in the Loginapp.

Configuration of the event subscriber for the Adminapp

  1. In the Config Editor, go to
    Adminapp >> Event Settings
  2. In the Basic Settings section, Event Subscribers list, add an Airlock 2FA Push Event Subscriber (Adminapp) plugin.
    Note: Add one plugin for each event that should trigger push notifications.
  3. The plugin is configured in the same way as the Airlock 2FA Push Event Subscriber (Loginapp) plugin (see the instructions above). There are only a few differences:
    • You cannot use Value Map Providers for the notification texts. However, you can use all available end-user context data items as notification variables. For details, see Customized notification text below.
    • The notification language is set differently:
      • Language Context Data Name: Defines the end-user's context data field used as notification language. Select the predefined String Context Data Item Name - String Context Data 'language' plugin from the drop-down list.
      • Default Language: Defines which notification language should be used when the current end-user's language is not present.
  5. You have now configured an Airlock 2FA Push Event Subscriber (Adminapp) that notifies a user's 2FA app whenever the specified event occurs in the Adminapp.

Notification content configuration

The Airlock 2FA app notification technically consists of an ordered list of Airlock 2FA Information Item plugins. Each information item contains a key and a value. In the Airlock 2FA app, the key is displayed as a heading and the value as the corresponding text - there is no support for links and rich text formatting.

If several information items are configured, they are displayed one after another.

 
Risk

There is no end-to-end encryption. The notification travels over the trusted channel to the Futurae service and from there to the app. Therefore, never include sensitive data in the payload.

Translation keys

Most 2FA app notification texts can be covered by the translation keys in the strings_*.properties files, which Airlock IAM provides for German, English, and French (and Italian for the Loginapp).

  • The (read-only) strings_*.properties files are available in the installation directory of your IAM instance, under
    • /opt/airlock-iam-<version>/app/loginapp/WEB-INF/classes, or
    • /opt/airlock-iam-<version>/app/adminapp/WEB-INF/classes
  • The relevant file section is # Futurae in-app notifications (Futurae In-App Notification Event Subscriber) #:
    • Possible keys for the notification heading are futurae.in-app-notification.title or futurae.in-app-notification.user-label.
    • Use any of the other keys for the corresponding notification text.

Example

You want to send a push notification to the 2FA app every time the password of the current end-user has been changed. Perform the following steps:

In the Airlock 2FA Push Event Subscriber plugin:

  1. Event property: Add the Password Changed event plugin.
  2. Payload Entries property: Add one Airlock 2FA Information Item plugin.

  3. Edit it as follows:

    • Translation Key for the Key property: Enter futurae.in-app-notification.title.
      This translation key will push the following heading to the 2FA app: Security notification – ${event.createdAt,date,MM/dd/yyyy hh:mm}
    • Translation Key for Value property: Enter futurae.in-app-notification.password-changed-event.message.
      This translation key pushes the following body text to the 2FA app: Your account password was changed.
    • By default, the maximum length for the notification header (key) and text (value) is 100. To change this, go to the Airlock 2FA Information Item plugin's Advanced Settings section, Maximum Key Length and Maximum Value Length properties. Enter the preferred key length and/or value length in the respective field(s).

Variables

As you can see in the above example, the notification texts may contain variables, such as ${event.data.userId}, ${event.metadata.requestIp}, or ${event.createdAt,date,MM/dd/yyyy hh:mm}.

IAM resolves these variables based on the event context. Each event carries a number of attributes, which provide a value for the variables.

For an overview of the available event variables (attributes), see

  • Event attributes, or
  • the Airlock 2FA Push Event Subscriber plugin documentation in the Config Editor.

Customized notification text

Instead of the provided notification texts, you can use your own customized texts by creating custom strings_*.properties files.

Store the custom properties files in the following directories:

  • For a specific IAM instance:
    • Loginapp: ./instances/<instance-name>/loginapp-texts/
    • Adminapp: ./instances/<instance-name>/adminapp-texts/
  • For all IAM instances:
    • Loginapp: ./instances/common/loginapp-texts/
    • Adminapp: ./instances/common/adminapp-texts/
 
Notice

Customizing non-UI-related text elements in the Loginapp REST API explains how to create customized non-UI texts for the Loginapp.

Also, instead of or in addition to variables based on event attributes, you can add custom variables to your notification texts. The required values can be provided by:

  • Loginapp: Any available Value Map Provider plugin. Specify the required Value Map Provider plugin(s) in the Value Map Providers property of the Airlock 2FA Push Event Subscriber (Loginapp). See the configuration instructions for the Loginapp above.
  • Adminapp: All available end-user context data items. For example, the context data item “givenname” gives the variable ${givenName}.
    For an overview of all available context data items, see the Context Data section of the Database User Persister plugin (Main Settings >> Data Sources >> User Data Source >> Database User Persister).

Behavior, logging, and error-handling

Behavior

  • Notifications are sent asynchronously. The triggering user-facing operation is never delayed or blocked.
  • Also, notification delivery is best effort: Futurae holds the payload for a limited time and delivers it to enrolled devices when possible. IAM does not retry failed deliveries.

Logging and error-handling

  • Logged on INFO level:
    • Successfully sent notifications (“Successfully sent in-app notification for …”).
  • Logged on DEBUG level:
    • Per-device delivery status returned by Futurae.
    • If the affected end-user has no Airlock 2FA account. In this case, no notification is sent.
  • Logged as ERROR:
    • If the notification could not be built, for example because a translated value exceeds the configured maximum length and cannot be shortened. In this case, no notification is sent. The event is not retried either, so the notification is lost.