Flow processing internals

This section provides 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.

  • Two examples of flows are the authentication- and authorization flows. Each application protected by Airlock makes use of these flows.
  • An authentication flow may be initialized through the Loginapp UI. For more information on the configuration of the Loginapp UI for authentication flows, go to Loginapp UI configuration.

Flow execution

  • During flow execution, the state machine ensures that:
  • Steps are executed in the correct order.
  • Flow processors are called.
  • The flow is correctly terminated.

Pre-processing flow steps

  • Before executing a flow step, the state machine ensures 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 (e.g., fail if the processed user is not valid).

Post-processing flow steps

  • Before executing a flow step, the state machine ensures that:
  • New flow tags are stored in the session.
  • Newly activated steps are activated.
  • Flow processors are called (e.g., 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 are 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. We strongly recommend using the corresponding default flow processors plugin.

  • Currently, the following default flow processor 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

For a better understanding 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. The state machine is told to stay in the same step for this.

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

  • External links:
  • Find more information on implementing a custom flow processor in the IAM Custom Development Guide. This guide is available only available on request.