Flow processing internals

This section gives you some internals about flow processing and helps to better understand how flows are processed and configured.

Flow state machine

The flow state machine controls in what order steps are processed and what is done before and after the steps. So-called flow processors are called at various stages of a flow and offer hooks to add custom logic.

The flow state machine roughly accomplishes the following tasks:

Task	Effect
Flow Initialization	A flow is usually started by a REST call selecting a flow or directly using the first step in the flow. The flow state machine is then initialized and information used during the flow is provided. This may be, for example, flow tags acquired during earlier flows in the session or contexts information such as the client IP address or geo-location.
Flow Execution	During flow execution, the state machine ensures the following: execution of steps in the correct order calling the flow processors correctly terminate the flow if successful or failing
Pre-Processing flow steps	Before executing a flow step, the state machine assures that: Preconditions for the step are met. The step does not have to be skipped. If the step has to be activated: if it has been activated in a previous step. Flow processors are called (example: fail if the processed user is not valid).
Post-Processing flow steps	Before executing a flow step, the state machine assures that: New flow tags are stored in the session Newly activated steps are activated. Flow processors are called (example: increase failed logins).

Flow processors

Flow processors are plugins that are called before and after every flow step is processed. They accomplish various tasks that are independent of the steps but required for correct flow processing.

Example flow processor tasks:
Assure that a user has been identified
Increase failed login counters
Update various statistics (e.g. set the latest login attempt timestamp)
Renew session ID to prevent certain attacks
Assure that the user is valid (e.g. not locked)
Assure that a CAPTCHA has been solved correctly

For each flow type, there is a preconfigured set of flow processors. It is strongly recommended to use the corresponding default flow processors plugin.

At the time this article was written, the following default flow processors plugins are available:

Default Authentication Processors
Default Authorization Processors
Default Protected Self-Service Processors
Default Public Self-Service Processors
Default Technical Client Registration Processors
Default Transaction Approval Processors
Default User Self-Registration Processors

To get a better idea of what flow processors are used for, open one of the default flow processors plugins in the Config Editor and have a look at its documentation. Start with the Default Authentication Processors plugin.

The plugin Custom Flow Processors allows configuring custom lists of flow processors. It is especially useful to use custom flow processor plugins in flows.

When using custom lists of flow processors, take great care to include the required flow processors essential for security. Omitting processors like the Failed Factor Attempts Processor or the User Validity Processor may create severe security flaws.

If you need to configure a custom flow processor and you are unsure which other flow processors to use, consult the documentation of the corresponding default flow processors plugin.

Internal flow step structure

Each flow step consists of the following parts:

Part	Effect
Init method	Each flow step must implement an init method. The init method is executed by the state machine when this particular is started. In the init method, all actions before the first potential response to the client are executed. Non-interactive steps: Non-interactive steps do all their work in the init methods. After processing the init method, the step is done and the state machine is told to move on to the next step. Interactive steps: Interactive steps, i.e., the ones involving REST responses and requests, do whatever is required before sending the first REST response to the client. Examples: Send push notification for Airlock 2FA authentication. Send an email with OTP. The init method then sends a response to the REST client, telling the client what to do next (e.g. send OTP token for verification). Processing the next request from the client is not done by the init method but by one or more additional methods. For this, the state machine is told to stay in the same step.
Additional method(s)	One or more additional methods of the step are used to process requests sent by the client (e.g. verify an OTP). Typically, the methods are where the main business logic of the flow step is processed. The term "business logic" is used rather loosely. Examples: validation of an OTP or password receiving and validating user data confirming terms of services validation of policies for attributes, e.g. a Regex Pattern for a phone number or email address generation of attributes, e.g. generating a username persisting data

Part

Effect

Init method

Each flow step must implement an init method. The init method is executed by the state machine when this particular is started.

In the init method, all actions before the first potential response to the client are executed.

Non-interactive steps:

Non-interactive steps do all their work in the init methods. After processing the init method, the step is done and the state machine is told to move on to the next step.

Interactive steps:

Interactive steps, i.e., the ones involving REST responses and requests, do whatever is required before sending the first REST response to the client.

Examples:
Send push notification for Airlock 2FA authentication.
Send an email with OTP.

The init method then sends a response to the REST client, telling the client what to do next (e.g. send OTP token for verification).

Processing the next request from the client is not done by the init method but by one or more additional methods. For this, the state machine is told to stay in the same step.

Additional method(s)

One or more additional methods of the step are used to process requests sent by the client (e.g. verify an OTP).

Typically, the methods are where the main business logic of the flow step is processed. The term "business logic" is used rather loosely.

Examples:

validation of an OTP or password
receiving and validating user data
confirming terms of services
validation of policies for attributes, e.g. a Regex Pattern for a phone number or email address
generation of attributes, e.g. generating a username
persisting data

Further information and links

More information about how to implement a custom flow processor can be found in the IAM Custom Development Guide, which is available on request.