Gateway Session Terminator

 
Notice

The Gateway Session Terminator event subscriber is only relevant when Airlock IAM is operated together with Airlock Gateway.

The Gateway Session Terminator event subscriber ensures that when a triggering event occurs, the end-user’s sessions in Airlock Gateway are terminated. This enforces security consistency across the end-user's devices. Use cases are the locking of an end-user account or the change of an end-user password.

Since an end-user may be logged into an application on multiple devices at the same time, several Airlock Gateway sessions can exist simultaneously. If the triggering event occurs, the Gateway Session Terminator closes all those sessions at once, logging the user out on every device.

The Gateway Session Terminator event subscriber behaves differently in Loginapp and in the Adminapp:

  • In the Loginapp, it terminates by default all Gateway sessions of the user except the one that triggered the event. E.g., when an end-user changes their password in the Loginapp, the Gateway Session Terminator will log the user off from all their devices, except the one on which they performed the password change.
  • In the Adminapp, it ends all Gateway sessions of the end-user. E.g., when an administrator locks an end-user in the Adminapp, the Gateway Session Terminator will terminate all currently active sessions of this end-user, on all their devices.

Technically, IAM uses the Gateway REST API to identify and terminate all sessions belonging to the same user. Airlock Gateway attaches audit tokens to sessions, and IAM uses the user ID in those tokens to locate the sessions of an end-user. See the next graphic.

The Gateway Session Terminator event subscriber also works in a high availability or cluster setup with multiple Gateways.

  • If each Gateway manages its own sessions, you must configure one event subscriber per Gateway.
  • If a central Redis database synchronizes sessions across all Gateways, a single event subscriber is sufficient for the entire setup.

For detailed configuration steps, see the instructions further below.

Prerequisites

  • After successful authentication, Airlock Gateway attaches an audit token to each end-user session. This audit token must contain only the user ID (also referred to as username in IAM). This is the default configuration in IAM. See Checking the Gateway Audit Token below to verify your audit token configuration.
  • IAM must be able to access the Gateway REST APIs:
    • The network topology must allow IAM to reach the Gateway Admin interface via the Gateway REST API.
    • Gateway must provide an API access token with the relevant authorizations. For instructions, see Obtaining the API Access Token below. Keep this API token available - you will need it later when configuring the Gateway Session Terminator event subscriber.
 
Functional limitation

Even when all prerequisites are met and the plugin is correctly configured, IAM cannot guarantee termination of all end-user Gateway sessions in every case. 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.

Checking the Gateway Audit Token

For the Gateway Session Terminator event subscriber to work, the Gateway audit token must contain only the user ID of the respective end-user (the default setting). Follow the instructions below to check your configuration of the Gateway audit token in the Config Editor.

Checking the Gateway Audit Token for the Loginapp

  1. Go to
    Loginapp >> Gateway Settings
  2. Check section Advanced Settings, field Audit Token. The correct setting is Username - DEFAULT (the user ID is also referred to as username in IAM).

Checking the Gateway Audit Token for the Adminapp

  1. Go to
    Adminapp >> Gateway Settings
  2. Check section Basic Settings, field Audit Token. The correct setting is Username - DEFAULT (the user ID is also referred to as username in IAM).

Obtaining the API Access Token

The Gateway Session Terminator event subscriber ends an end-user's sessions via the Gateway's REST API. This requires a valid API access token. You can obtain the API token in the Airlock Gateway Configuration Center. Perform the following steps.

  1. In the Airlock Gateway Configuration Center, go to
    System Setup >> System Admin
  2. Go to the section API Keys. The table shows the list of users that have permission to access the REST API.
    • Copy the API key of the admin user, by clicking the Copy to clipboard icon .
  5. You have now obtained the API access token. Keep this API token available - you will need it later when configuring the Gateway Session Terminator event subscriber.

Configuring the Gateway Session Terminator for the Loginapp

The following instructions illustrate how to configure a Gateway Session Terminator event subscriber in the Config Editor, for a Password Changed event occurring in the Loginapp. The configuration is similar for other events.

  1. In the Config Editor, go to
    Loginapp >> Event Settings
  2. In the Event Subscribers list, create and edit a Gateway Session Terminator (Loginapp) event subscriber, as follows:
  3. In the Gateway REST APIs plugin list, create and edit a Gateway REST API Connection plugin. This plugin defines the connection details to the Gateway REST API. If your setup includes multiple Airlock Gateways, each managing its own sessions, you must configure one Gateway REST API Connection plugin for each Gateway.
    To configure the plugin, perform the next steps in the Gateway REST API Connection plugin dialog:
    1. In the URL field, enter the base URL of the Gateway's REST API. It is normally accessible at https://<airlock-gateway>/airlock/rest. You may have to adapt firewall rules, so that IAM can connect to this URL.
    2. In the HTTP Client field, create and edit the HTTP client used to connect to the Gateway's REST API. You can choose either the HTTP Client Config plugin or the HTTP Client With Client Certificate plugin. Select the latter option if your setup requires mutual authentication (i.e., both the server and the client authenticate each other using certificates). Perform the next steps in the HTTP Client Config / HTTP Client With Client Certificate plugin dialog:
      • Basic Settings section, Bearer Token field: Connecting to the Gateway's REST API requires a valid API access token from the Gateway's Configuration Center.
        - Enter the previously obtained API token in the Bearer Token field.
      •  
        Notice

        If you have not obtained this API token yet, see Obtaining the API Access Token for instructions.

      • Configure the other sections and fields of the plugin dialog according to your requirements and setup.
      • Return to the Gateway REST API Connection plugin dialog.
  5. You have now configured the connection details to the Gateway REST API.
  6. Repeat the previous step for each Airlock Gateway managing its own sessions in your setup.
  7. After having configured the connection to the Gateway REST API(s), return to the Gateway Session Terminator (Loginapp) dialog.
  8. The Gateway REST API Connection ends all sessions of an end-user when the specified event occurs. Enable the Keep Current User Session checkbox to exclude the session that triggered the event from termination (the default setting).
  9. In the Event field, create and edit the event plugin that triggers the Gateway Session Terminator (Loginapp) event subscriber. In this example, it is the Password Changed event.
  10. Activate your configuration.
  11. You have now configured a Gateway Session Terminator (Loginapp) event subscriber that is triggered each time an end-user changes their password in the Loginapp. It will end all sessions of the end-user, except the one that triggered the event.

Configuring the Gateway Session Terminator for the Adminapp

The following instructions illustrate how to configure a Gateway Session Terminator event subscriber in the Config Editor, for a User Locked event occurring in the Adminapp. The configuration is similar to the configuration of the Gateway Session Terminator for the Loginapp.

  1. In the Config Editor, go to
    Adminapp >> Event Settings
  2. In the Event Subscribers list, create and edit a Gateway Session Terminator (Adminapp) event subscriber, as follows:
  3. In the Gateway REST APIs plugin list, create and edit a Gateway REST API Connection plugin. This plugin defines the connection details to the Gateway REST API. If your setup includes multiple Airlock Gateways, each managing its own sessions, you must configure one Gateway REST API Connection plugin for each Gateway.
    For instructions, see steps 3 and 4 of section Configuring the Gateway Session Terminator for the Loginapp above.
  4. After having configured the connection to the Gateway REST API(s), return to the Gateway Session Terminator (Adminapp) dialog.
  5. In the Event field, create and edit the event plugin that triggers the Gateway Session Terminator (Adminapp) event subscriber. In this example, it is the User Locked event.
  6. Activate your configuration.
  7. You have now configured a Gateway Session Terminator (Adminapp) event subscriber that is triggered each time an administrator locks an end-user in the Adminapp. It will end all sessions of the respective end-user.