Scriptable Validator plugin

All key/value pairs relevant for the self-registration process are stored in the Lua table iam.input_map - the Scriptable Validator accesses this table to get the input for the script.

The iam.input_map table provides three types of input data:

The following table lists the available keys and their possible values for the iam.input_map.user_data input data map. Note that some values are not entered in the self-registration UI but are automatically provided to the end-user by preceding flow steps.

If an end-user does not specify a value during registration, the corresponding key-value pair will not be present in the map. Therefore, always verify that an entry exists before operating on it.

All user context data specified during your user self-registration flow, such as home town or date of birth, is provided as iam.input_map.context_data input data to your validation script.

User context data fields are defined with the User Context Data Item plugin. There are several types of user context data item plugins, for the different types of context data:

The key of a specific user context data is the corresponding name of the context data field under which the data value is stored. For example, for the “Date of birth” context data item, the key may be birthday. This key is defined in the Context Data Name property of the corresponding User Context Data Item plugin.

As noted previously, keys may be absent if no value was provided.

The iam.input_map.additional_data input data map provides additional script input that is not available by default during the end-user registration flow. To use it, you must explicitly configure additional value map providers in the Additional Inputs property of the Scriptable Validator.

Use case: mTAN user input data

mTAN user data is not provided by default. If you need to validate the end-user’s mTAN number (mobile phone number) or label, you must configure the corresponding mTAN value map provider in the Additional Inputs field.

First, select the Value Provider Map plugin in the Additional Inputs field. Then configure the plugin according to the mTAN data required by your script. The following table describes the available options.

Note: Value providers must be set to “non-mandatory”, as the values are initially empty.

The following code snippet provides a sample script input (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": 
    { 
        "town": "Zürich",
        "birthdate": "1980-12-20"
    },

    -- Any additional data provided by the configured value provider maps.

    "additional_data": { ... }
}

The Scriptable Validator validates user input provided during the user self-registration process. If a specific input element is not valid, the validator will trigger error messages on the user self-registration page.

There are two types of validation error messages:

To trigger the correct error messages, your script must include an errors map listing the possible validation errors. This map follows a predefined structure, as shown in the following code snippet:

{
"errors":
[
    {
        "type": "<typeNameA>",
	"field": "<fieldNameA>",
        "parameters": { "param1A": "<param1A>", "param2B": "<param2B>", ... }
    },
    ...
]
}

You do not have to manually construct the errors map: Airlock IAM provides a number of utility functions that facilitate the creation of a validation errors list.

The utility functions are API and perform additional validation on the inputs. We highly recommend using them in place of constructing the errors output manually.

The table below lists all available error type translation keys, their corresponding English translations, and any parameters that can be included in the texts, if applicable.

Sample script 1 - validation without errors

function iam_on_user_validation ()
        return iam.validator:valid()
end

Sample script 2 - validation with errors

function iam_on_user_validation ()
        return iam.validator:invalid(
            iam.validator:error("max-length", "username", {"requiredLength" = "16"}),
            iam.validator:error("min-length", "password", {"requiredLength" = "8"}),
            iam.validator:error("after_max_date", "birthdate", {["max-date"] = "2008-01-01"}),           
            iam.validator:error("not-identical", "password_confirmation"))
end

where:

The Scriptable Validator also allows defining custom validation error messages, whose content differs from the predefined validation error messages in the .properties translation files.

Proceed as follows: