License and usage analytics

Airlock IAM can send usage data to the Airlock cloud service. Data science methods are applied to this information to uncover real-world usage patterns. The results guide Airlock in prioritizing development efforts, ensuring that new and improved features align with customer needs.

The data and any insights gained will not be shared with third parties.

 
Notice

The License and Usage Analytics plugin is mandatory. If it is not configured, IAM will fail to start, and config activation will fail.

License analytics data will always be transmitted to the Airlock cloud service, regardless of how the License and Usage Analytics plugin is configured.

Usage analytics data will only be transmitted to the Airlock cloud service if the Enable Usage Analytics property is enabled.

Contents of license and usage analytics

The data transferred is divided into License Analytics and Usage Analytics.

  • License Analytics includes only the data necessary to confirm the proper use of the licensed product.

  • This includes the following information:

    • The license itself
    • The version of Airlock IAM
    • The number of users in the database
    • The deployment form (SCA vs. container)
    • The setting of the Enable Usage Analytics property.
  • Usage Analytics includes data about the product's configuration.

  • This includes the following information:

    • Redacted plugin configuration from the medusa-configuration.xml or from the iam-config.yaml file
    • Redacted instance configuration from the instance.properties file
    • DB schema information
    • IAM metrics (e.g. failed factor rate)

  • Redacted means that all configuration files are processed locally on the IAM server to remove secrets, plugin names, host names, URLs, and any other property values that could identify the customer or reveal details about the system's infrastructure.

Data transfer

The following image explains how the analytics data is transferred from the IAM server to the Airlock cloud service.

The data transfer depicted in the picture above is implemented in the following sequence:

  1. An administrative user logs in to the Adminapp.
  2. The IAM server determines if a data transfer is required. IAM enforces per server a throttle limit of at most one transfer per day.
  3. IAM prepares the data set and stores a plaintext local copy if a transfer is required. An encrypted copy and the authentication key are sent to the administrative user's browser.
  4. The administrative user's browser authenticates with the Airlock cloud service and delivers the encrypted copy of the data.
  5. The Airlock cloud service receives and stores the encrypted data locally in blob storage for further processing.

The Airlock cloud service is hosted on Azure in the switzerlandnorth region. This ensures that Airlock only processes this data in Switzerland.

Security

With each version of IAM, two keys are bundled with the product as follows:

  • Authentication key: Symmetric key to authenticate to the Airlock cloud service. This key prevents unauthenticated traffic from congesting the cloud service.
  • Encryption public key: Asymmetric key used to encrypt the data set before it is transferred to the Airlock cloud service. This protects the data against man-in-the-middle attacks.
  • All data is protected with end-to-end encryption during transfer between the IAM server and the Airlock cloud service, thereby eliminating the risk of theft.
  • Airlock IAM remains fully available, even when sending data to the Airlock cloud service fails.

Transparency

IAM administrators with access to the IAM server's file system can verify the contents of the license and usage analytics data being transferred.

For each transfer, IAM collects all the data to be included in the transfer and stores it in plain text in the following location:
/iam/instances/<instance-name>/usage/usage-data.json

Storing this information is optional. If the storage location is not accessible, the data transfer will still go through without any issues.

Configuration

  1. In the Config Editor, go to
    Adminapp
  2. In the section Advanced Settings, in the property License and Usage Analytics, create and edit a License and Usage Analytics plugin.
  3. Disable the Enable Usage Analytics property if you do not want to share usage analytics data.

Config migration and initialization

The Usage Analytics plugin is a mandatory plugin for every configuration. To ensure customer consent, the IAM CLI now requires users to explicitly choose whether they want to enable Licenses Analytics or Usage Analytics. Based on this consent, the CLI automatically adds and configures the Usage Analytics plugin during the following operations:

  • init
  • upgrade
  • reset

The CLI supports two methods how the CLI can be used to configure the Usage Analytics plugin:

  • IAM_ANALYTICS_MODE is an environment variable. If this variable is present during the CLI operation, the setting will be applied.
  • -a or --analytics is a command line option. If the command line option is present during the CLI operation, it will override the environment variable, and the setting will be applied.

Both environment variable and command line option can be set to two values:

  • LICENSE_DATA will enable License Analytics
  • USAGE_DATA will enable Usage Analytics.

 
Example

Directly on the command line:

./bin/iam init -a USAGE_DATA -c DEMO.config

or in a shell script:

export IAM_ANALYTICS_MODE="USAGE_DATA"
./bin/iam init -c DEMO.config

Example license analytics data

The following example shows what data is included in the license analytics data. Note that it has been abbreviated for easier readability.

 
Example
{
  "createdAt": "2025-08-26T16:18:16.393+01:00",
  "iamVersion": "8.5.0",
  "license": {
    "licenseText": "-----BEGIN LICENSE-----\neJyNVtlyo0gW/ZUJP0-----END LICENSE-----
    "structured": {
      "bundles": [
        "API_ACCESS_MANAGEMENT",
        "IDM",
        "FEDERATION_IDP_OP",
        ...
      ],
      "environment": "Development and Integration",
      "issuedOn": "2024-12-01",
      "licensedInstances": 100,
      "licensedMac48Addresses": ["11:22:33:44:55:66"],
      "licensedTags": [
        "OAuthSocialRegistration",
        "OAuthTokenExchange",
        "OAuthAccountLinking",
        "OAuthClient",
        "OAuthServer",
        ...
      ],
      "licensedUsers": 100,
      "owner": "Airlock PD IAM",
      "validFrom": "2025-01-10",
      "validUntil": "2025-12-31"
    }
  },
  "runningInDocker": false,
  "usageAnalyticsEnabled": true,
  "userCount": 12
}

Further information and links

  • See IAM Command-Line Interface CLI for more information about the Airlock IAM CLI.
  • Run ./bin/iam init --help for detailed information on the usage analytics CLI option.