Scriptable plugins

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

  • The Scriptable Step plugin is an additional flow step that can be configured into any IAM flow, e.g., authentication, protected self-service, public self-service, self-registration, and transaction approval. Because the Scriptable Step is non-interactive, you cannot create a UI for it.
    For more information, see Scriptable Step plugin.
  • The Scriptable Validator plugin is used to validate user data during the user self-registration flow. It allows for configuring more complex validation logic than what would be normally possible with the default built-in validators. You configure the Scriptable Validator plugin directly in the User Data Registration Step plugin.
    For more information, see Scriptable Validator plugin.

 
Risk

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

Scripting language Lua

Airlock IAM supports Lua as the scripting language (see The Programming Language Lua for more information). IAM 8.2 and later include Lua 5.4.

If Lua version 5.4 is not suitable 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 support Lua scripting, the lua-cjson library is bundled with the scripting engine. This library deserializes input variables and serializes output variables for data exchange with Airlock IAM.

Starting with IAM 8.5, the luasocket library (luasocket library) is also included. This library is used for the interface between IAM and Lua, including input and output transfer.

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 specified directly in the Config Editor, in a text box that is part of the scriptable plugins. 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 scriptable plugins are 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.

For more details, see Lua and operating system dependencies.

Example for MacOS operating system

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

 
Notice

MacOS may raise a security alert because the developer of lua, luarocks or cjson.so 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/cjson.so to the lib directory in the Airlock IAM installation directory in $IAM_install_dir/res/scripting/lua/lib.