Scriptable Validator
A customizable validator for self-registering users, which runs the configured script to validate the user data.
The input of the script consists of the following entries (here displayed as JSON):
{
-- All user data that does not fall under context data, such as username and password.
-- If the user data is not defined at the time the script is run, the key-value pair will not exist in the input map.
"user_data":
{
"username": "bob",
"password": "hunter123",
"auth_method": "password",
"next_auth_method": "mtan",
"auth_migration_date": "2026-10-24"
"roles":
[
{
"name": "customer",
"lifetime": 86400,
"idle_timeout": 360
}, ...
]
},
-- All provided context data of the user. If context data has not been specified, the entry will not exist in the map.
"context_data": { ... },
-- Any additional data provided by the configured value provider maps.
"additional_data": { ... }
}
The output for this script must follow the following format (here displayed in JSON):
{
-- The list of validation errors. If no validation errors are found, the return statement may be empty or omitted entirely, in which case the result is valid.
-- Multiple errors may be returned, corresponding to the context data field that caused the error.
"errors":
[
-- Example of a validation error where a field with label "username" must have at least 8 characters.
{
-- Mandatory: The type of the validation error to display in the UI, which supports existing as well as custom validation error types.
-- This is used as the last segment of the translation key. For example, the following type is transformed into: "error.validation-failed.min-length"
"type": "min-length",
-- Optional: Input field where the validation error should be displayed. Must always be a string.
-- Errors without a field are displayed as page alerts. Only one page alert may be displayed at the same time.
"field": "username",
-- Optional: Parameters to provide to the translation key. Keys and values of this map are required to be strings.
"parameters": { "requiredLength": "8" }
}
]
}
To construct your validation output, you may also use the following utility functions:
iam.validator:valid()— Represents a valid result.iam.validator:invalid(...)— Represents an invalid result. Arguments must be field-specific errors or alerts.iam.validator:error(errorType, field, parameters)— Constructs a field-specific error message.iam.validator:alert(errorType, parameters)— Constructs a page alert.
Note that the validator script is always executed with each request sent to the user self-registration REST endpoints, as well as when the step is initialized. It is therefore not guaranteed that user data will be present in the inputs when the script is executed.
The results of the script are consumed directly. Unlike with the Scriptable Step plugin, the outputs will not be stored in the flow attributes.
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.
additionalInputs) Defines a mapping of additional 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.additional_data"
Note that the user context data is always made available through the key "iam.input_map.context_data", even if this property is left empty.
If a value cannot be provided by the configured map, its corresponding key-value pair 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 validator 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 a user submits the self-registration form.
Each script must define the following function:
function iam_on_user_validation ()
return <output_map>
endThe validation errors returned by this function are expected to follow a predefined format, see the plugin description for a more detailed documentation.
inputSecrets) Secret strings that are passed in plaintext as environment variables to the IAM script process.
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.
type: ScriptableSelfRegisteringUserValidator
id: ScriptableSelfRegisteringUserValidator-xxxxxx
displayName:
comment:
properties:
additionalInputs:
inputSecrets:
script: