Writing Lua scripts for the Scriptable Step

This page explains how to integrate Lua scripts in the Scriptable Step plugin. For more information on Lua itself see The Programming Language Lua.

The following configuration properties/fields are available in the Scriptable Step plugin:

For a script to return output values to Airlock IAM, you must configure a list of keys and corresponding data types in the Outputs property and specify whether the key is required (mandatory).

The Outputs property exists of two parts:

If one of these conditions is not met, an error will result, and the flow will be terminated as failed.

Output data types

IAM supports the following data types for script output values:

Output elements

The script output values can be provided in various output elements. Output elements define the type and structure of the script output, such as lists, maps, or a single output value. You can combine these output elements at will. This allows for highly structured and nested output values, e.g., a list of roles for users.

When specifying the Script Output Declaration plugin, you in fact set the output element of the script.

IAM currently supports the following script output elements:

To successfully run a script in the scriptable step plugin, at least the following function must be defined in the script property:

function iam_on_step_init ()
    <your code>
    return iam.output_map
end

The iam_on_step_init() function is called by IAM when starting the execution of a script.

Input values are configured in the scriptable step plugin through value map providers. For this purpose, Airlock IAM provides a large number of plugins. Refer to the plugin documentation for further information on a particular value map provider.

All the examples in this text configure the Inputs property with a Context Data Map plugin. To read a context data item, the iam.input_map[<key>] table must be used in the script code.

The following example shows how a user's givenname and surname are concatenated into a property full_name. This property is then logged and finally returned to IAM for further use.

function iam_on_step_init ()
    iam.output_map = {}
    iam.output_map["full_name"] = iam.input_map["givenname"] .. " " .. iam.input_map["surname"]
    iam.log:info("User with full name: " .. iam.output_map["full_name"])
    return iam.output_map
end

If multiple value map providers contain a key with the same name, the value from the last value map provider will overwrite previous values.

Optional input values

When configuring value provider maps with optional values, it is the script's responsibility to check whether a particular value is present. In case of a missing value, the iam.input_map[<key>] will return the value nil.

The following code example will check if the key givenname is present or not:

if (iam.input_map["givenname"] ~= nil) then
   <logic if given name is present>
else
   <logic if given name is absent>
end

List all values provided to the script

The following code snippet will iterate over the table of input values provided to the script and output them to the IAM logfile:

for k, v in pairs(iam.input_map) do
    iam.log:info("key : " .. k .. ", value: " .. v)
end 

The following code snippet will achieve the same result, with less formatting:

 iam.log:info("Complete input map of GET request step: " .. iam.cjson.encode(iam.input_map))

Use the Input Secrets property to provide sensitive values to a Lua script. Sensitive values are transferred to the Lua script as environment variables. In the script, these values can be accessed through the IAM API function local secret = iam.secrets:get(<secretId>).

Once made available within the Lua script, secrets are retrieved as plaintext. The script developer is responsible for ensuring that secrets are not leaked (e.g., not logged).

The secretId can only consist of alphanumeric and underscore characters.

Namespaces are optional. They are used to assign a name to the value map from the output of a script. This may be necessary if multiple scripts in the same flow can return an output value with the same key.

If no namespace is configured, the default namespace is used. If several steps return the same key into the default namespace, the value of the scripting step executed last will overwrite the previous value.

The Lua scripting language provides several built-in functions and types.

The ​print() function has been modified for Airlock IAM. It now writes messages to the appropriate Airlock IAM logfile with severity DEBUG.

All other built-in functions and types remain as implemented and documented by Lua.

Care should be taken when using the os object or functions like load(), loadfile(), or dofile(). These functions may have security-relevant side effects as they are run with the IAM user's permissions and can access processes and file system objects.

Airlock IAM provides additional and IAM-specific functions for scripting with Lua:

The Config Editor does not verify the correctness of the Lua script syntax or semantics during configuration activation.

The following behavior is to be expected:

We recommended testing custom scripts before they are deployed with Airlock IAM.

The scriptable step supports the following error codes: