Scriptable Step
IAM uses Lua as its scripting engine. Please refer to the official documentation on https://www.lua.org/ for more information about the Lua language and its features.
inputs) Defines a mapping of input values that are made available to the lua script. The inputs can be accessed from inside the script as a table through the "iam" API object: iam.input_map
If a value cannot be provided by the configured map, its corresponding key will not exist in the resulting mapping. When writing a script, one should always first check if the key is present before trying to operate on its value.
If two value providers contain an entry with the same key, then only the entry of the provider that appears last in the list will be available within the script.
Note that simple date values without a specific time (i.e. LocalDate) are passed as string arguments in the format "yyyy-MM-dd", while more specific date-time values are provided as epoch time with millisecond precision.
Security Note: The inputs to the Scriptable Step may contain sensitive user data. Handle these inputs carefully and make sure that they are not forwarded to the logger. IAM will not obfuscate this data automatically.
script) The Lua script that will be run when the step is initialized.
Each script must define the following function:
function iam_on_step_init ()
return <output_map>
endThe values returned by this function can be accessed using the "Script Execution Result Value Map Provider" with matching namespace. Note that the outputs returned by the script must be declared in the "Outputs" property. If no outputs are expected, then the function's return statement can either be removed, or return an empty mapping.
outputs) Declares the mapping of key-value pairs that are expected to be returned by the Lua script. The outputs are made available under the namespace configured for the step.
The script's outputs are required to match the expected output exactly. If the script's output contains additional results, this will also produce an error.
Individual key-value pairs may be tagged as optional, in which case they are not required to be in the script's output. Note that the order in which the key-value pairs are listed does not matter.
If left undefined, then the output map is expected to be empty.
inputSecrets) The script is always executed on the server and therefore no secrets are transmitted to an external client, e.g. browser.
An example are HTTP basic authentication credentials for the configuration of a REST client.
Secrets must only be referenced in the script by calling the API method iam.secrets:get(identifier) with their configured string identifier.
Security Note: Secrets must be handled with care. Make sure that they are not forwarded to the logger, as IAM will not obfuscate them automatically.
namespace) The namespace under which the output of the step is stored. If left empty, it is stored under the default namespace.
To retrieve the output values of this step, configure the same namespace in the corresponding Script Execution Result Value Map Provider.
skipCondition) If this condition is configured and fulfilled, the step is skipped and the flow execution continues with the subsequent step.
preCondition) requiresActivation) tagsOnSuccess) stepId) onFailureGotos) If the step fails (no retry) and a goto target for the error code is defined here, the flow does not fail and instead a "goto" to the specified target step is executed. Note that even when the "goto" is executed, any error codes that are considered a failed factor attempt will still increment the "failed attempts" counter, and may lead to the user being locked. Therefore, this may still result in a failed flow.
A typical application of this feature is switching to an alternative authentication factor step, if an external service (e.g. Futurae server, SMS gateway) is not available (error code EXTERNAL_SERVICE_UNAVAILABLE with "Strict Counting" disabled, which will not increment the "failed attempts" counter). Other error codes can be found in the IAM REST documentation, in both the general "Error Codes" section and in the documentation of specific endpoints.
customResponseAttributes) A list of custom attributes that are returned in the REST response in addition to the standard attributes the step already returns. The custom attributes defined here are only returned if the step result does not lead to an error response.
Custom attributes are added to the response when a step is initialized and when actions are executed on the step. They will therefore be available in the response leading to this step, and in any responses from endpoints specific to this step. For non-interactive steps, custom attributes are accumulated and added to the response leading to the next interactive step.
Custom attributes are not returned for 'retrieve' endpoints.
customFailureResponseAttributes)
type: ScriptableStep
id: ScriptableStep-xxxxxx
displayName:
comment:
properties:
customFailureResponseAttributes:
customResponseAttributes:
inputSecrets:
inputs:
namespace:
onFailureGotos:
outputs:
preCondition:
requiresActivation: false
script:
skipCondition:
stepId:
tagsOnSuccess: