Scriptable step overview - an incubating feature

Customers of Airlock IAM may face unique requirements that are difficult to address with a standardized product. The new Scriptable Step allows such customers to quickly and conveniently implement solutions for such requirements.

The Scriptable Step can be configured into any IAM flow, e.g., authentication, protected self-service, public self-service, self-registration, and transaction approval.

The Scriptable Step is non-interactive, so it is not possible to create a UI for it.

The scriptable step is an incubating feature. It is intended to gather experience with this type of customization capability and to improve the functionality in future versions of Airlock IAM. It is possible that the plugins provided and the underlying architecture may change fundamentally and without further notice in future releases of IAM.

Input and output

To allow a scriptable step to interact with the flow, both input and output need to be configured in the plugin:

Script input

A list of value map providers is configured in the plugin. The key-value pairs of all configured value maps are made available in the script.


Script inputs that are persisted as sensitive configuration values (secrets) can be provided to a script through environment variables. In the script context, secrets only exist in the IAM server. The script developer is responsible for avoiding leaking secrets.

Script output

The script can return a value map to the flow. In the configuration, a list of the acceptable keys and their data types must be configured to control what keys are accepted back by the flow.

Multiple scripting steps can segregate their return values by assigning their results to different namespaces.


The scripting language is extended with an "iam.log" directive that logs into the Airlock IAM log.

Scripting language Lua

Airlock IAM supports Lua as the scripting language (see The Programming Language Lua for more information).

Table: Lua compatibility matrix

Airlock IAM version

Lua version



If the above version dependency is not acceptable for a particular deployment scenario, the Lua interpreter and dependent libraries can be replaced with a different version. See Lua and operating system dependencies below.

  • Lua was chosen for the following reasons:
  • Lua is lightweight and adds hardly any overhead to the IAM distribution image.
  • Lua provides a well-maintained ecosystem of libraries.
  • Lua is supported by a thriving community of developers.
  • Lua is already well established, and the language is very stable.
  • Lua is the default scripting language of the Airlock Microgateway.

Developer support

To facilitate using Lua, the lua-cjson library has been bundled with the scripting engine. This library deserializes input variables and serializes output variables for data exchange with Airlock IAM.

Additional libraries can be added using The Luarocks package manager and installed directly into the instances folder of Airlock IAM.

Scripts can log different severity levels to the regular Airlock IAM log files. Use this feature to document the progress and outcome of scriptable steps and for debugging purposes.

The scripts are written in a text box in the Scriptable Step plugin to use the scripting feature in Airlock IAM. This solution was chosen for the following reasons:

  • Scripts are part of the configuration and do not require additional effort to deploy or manage script files.
  • The scripting step is not intended for large-scale customizations. Typical scripts are expected to be between 10 and 100 lines of code.

Known limitations

  • The following is a non-exhaustive list of known limitations of the scriptable step:
  • Airlock IAM provides no integrated IDE support for writing or debugging Lua scripts.
  • The current implementation only supports non-interactive flow steps and, therefore, does not support any interactions with the end user.
  • Security hardening is limited as scripts are executed in the IAM process context. There is a limitation on scripts to run at most 30 seconds to prevent scripts from using resources excessively.

Lua and operating system dependencies

The Lua script interpreter and all the pre-bundled shared object libraries are provided in an executable format suitable for Linux operating systems.

  • Lua will work out of the box for the following use cases:
  • Airlock IAM runs as a self-contained application on a Linux operating system.
  • Airlock IAM is deployed as a container image on any compatible platform (e.g. Kubernetes or Openshift).

If Lua is intended to be used natively with another operating system, the lua executable and all shared object libraries must be replaced with versions that work on the target operating system.


On a MacOS operating system, the following tasks must be executed to replace the executable and the shared library files.

MacOS may raise a security alert because the developer of lua, luarocks or is not trusted. This trust must be granted in:
System Settings >> Privacy&Security

  1. Use brew install lua to install the Lua script interpreter locally.
  2. Copy the lua executable from /opt/homebrew/bin/lua to the Airlock IAM installation directory in $IAM_install_dir/res/scripting/lua/.
  3. Use brew install luarocks to install the Luarocks package manager locally.
  4. Use luarocks install --tree /tmp/cjson lua-cjson to install the latest version of cjson locally.
  5. Copy the .so file from /tmp/cjson/lib/lua/<version/ to the lib directory in the Airlock IAM installation directory in $IAM_install_dir/res/scripting/lua/lib.