Correlation ID for better traceability

The Correlation ID links incoming HTTP requests with outgoing requests and log files by using a consistent reference ID. This ensures that all actions stemming from a specific user request are grouped together, enhancing the traceability of the use case through IAM and third-party systems. Example use cases include transaction approval procedures or authentication processes using the Airlock 2FA app as a second factor.

How does the correlation ID work?

At the beginning of a specific transaction, an upstream third party system of Airlock IAM generates an ID and sends this ID in the HTTP request header to IAM. IAM logs this ID as corr_id in its log files. Additionally, IAM forwards the ID unchanged to the downstream third party system(s) that follow in the transaction process.

The following graphic illustrates the functioning of the Correlation ID feature. Within IAM, the feature is supported by all modules (Loginapp, Adminapp, Transaction Approval, etc.) as well as all plugins that define HTTP calls to third party systems.

IAM_correlation-ID

The responsibility for generating the correlation ID lies with the third party system that precedes IAM in the transaction flow. This upstream system determines which correlation ID to set where and when in the incoming request to IAM. IAM only receives, logs and forwards the correlation ID (if configured).

If the incoming HTTP request does not contain a correlation ID, IAM will not generate one itself. In this case, no correlation ID will be available for this specific transaction.

To preserve backward compatibility, the corr_id is only set in the structured log by default (status Q3 2024). It is possible to also log the correlation ID in the Main log, but this requires a manual configuration - for instructions, see further below.

The correlation ID is currently not supported for the parsable log files (used by the Adminapp log viewer).

Within IAM, the X-Correlation-ID header field is set as the default HTTP header field to transfer the correlation ID. However, the X-Correlation-ID header is no general standard. It is possible to use another header for the incoming and/or outgoing correlation ID, if you or your third party systems would prefer this.

Also, the HTTP header field containing the incoming correlation ID does not have to be the same as the HTTP header field containing the outgoing correlation ID. This allows for greater flexibility in adjusting your settings to those of your third party systems.

Configuring the Correlation ID feature

To enable the Correlation ID feature, you need to specify which header fields to use for transferring the value of the correlation ID in the incoming and outgoing HTTP requests.

Prerequisites

As a prerequisite for configuring the Correlation ID feature, first check with your third party systems which HTTP header(s) to use.

Configuring the incoming correlation ID

Correlation ID Settings plugin. This plugin can be specified on the root page of all IAM modules (Loginapp, Adminapp, Transaction Approval, etc.) and on the Main Settings root page. If the header field for the incoming correlation ID differs per IAM module, set the plugin for each module individually. If not, use the Main Settings root page for global settings.

  1. To configure the incoming correlation ID, proceed as follows:
  2. Go to the root page of
    • the Main Settings module, to specify the incoming correlation ID settings globally.
    • a specific module, such as Loginapp or Transaction Approval, if you want to specify the incoming correlation ID settings for this module explicitly.
  3. In the property Correlation ID Settings, create and edit the Correlation ID Settings plugin, as follows below. (If the root page has more than one section, you will find the Correlation ID Settings property in the Advanced Settings section.)
  4. In the property Header Name, define the HTTP header from which to extract the correlation ID on incoming requests.
  5. In the property Validation Pattern, define the regular expression against which the incoming correlation ID will be matched. If the correlation ID value matches the regular expression, IAM logs it for the entire transaction scope triggered by the current HTTP request. If the ID value does not match, no correlation ID will be logged. By setting this property, you can prevent unexpected and/or undesired values from being written to the log files.
  6. You have now configured the settings for the incoming correlation ID. Proceed with the following section to configure the settings for the outgoing correlation ID.

Configuring the outgoing correlation ID

You set the HTTP request header field to transfer the outgoing correlation ID value in the Correlation ID Header Name property. This property is available in most plugins that define HTTP calls to third party systems.

  • This includes the following plugins:
  • All HTTP-based SMS gateway plugins
  • HTTP Client Config plugin, if used by
    • OAuth/OIDC clients
    • On-behalf login identity propagators
  • HTTP Password Service plugin
  • Access Cookie Identity Propagator plugin
  • SAML Access Cookie Identity Propagator plugin

Currently (Q3 2024), the Event Subscriber plugins do not support the correlation ID.

The same is true for the Futurae cloud service. As a result, when an end-user authenticates with the Airlock 2FA app, the corresponding requests sent to the Futurae cloud service do not include a correlation ID.

  1. To configure the outgoing correlation ID, proceed as follows:
  2. The outgoing correlation ID settings can be configured in all plugins that define HTTP calls to third party systems (see the list above).
    Go to the dialog of the plugin for which you want to configure the outgoing correlation ID.
  3. In the property Correlation ID Header Name, enter the HTTP header field to be used to forward the correlation ID. If the current plugin sends an outgoing HTTP request to a third party system, it will fill this request header field with the relevant correlation ID value.
  4. If the plugin dialog has more than one section, you will find the Correlation ID Header Name property in the Advanced Settings section.

  5. Repeat the above steps for all plugins for which you want to configure the outgoing correlation ID.
  6. Activate your configuration.
  7. You have now configured the Correlation ID feature.

Logging the correlation ID in the Main log

IAM logs the value of the incoming correlation ID in its logfiles as corr_id. To preserve backward compatibility, the corr_id is only set in the structured log by default (status Q3 2024). It is possible to also log the correlation ID in the Main log, but this requires a manual configuration. This section explains how to proceed.

The Main log file can be configured manually in the instance.properties file of your IAM instance. This file is located in the instance directory (e.g., <configuration-dir>/instances/auth/instance.properties).

To log the correlation ID in the Main log, you must add the following value to the iam.log.main.pattern property in the instance.properties file (under ### LOGGING):

copy
%e{mdc\:CORRELATION_ID}

The following code snippet shows a full example of the iam.log.main.pattern property including the %e{mdc\:CORRELATION_ID} value:

copy
iam.log.main.pattern = %d{DEFAULT} %-5p [IAM - ${sys\:iam.instance.name} -  ${applicationName} - SID\: %18e{mdc\:GSID\:0} - RID\: %18e{mdc\:REQUEST_ID\:0} - CORR_ID\: %e{mdc\:CORRELATION_ID}] | %e{header\:3}%c{1}\: %m%n