One-shot authentication with flows

This article explains how to configure one-shot authentication using flows in Airlock IAM. This method was introduced with IAM 8.5 and is the preferred method for one-shot authentication.

  • Dedicated REST API endpoint: /rest/public/authentication/one-shot/applications/{application id}
 
Notice

If you are still working with one-shot based on authenticators, you should replace this legacy approach as soon as the flow-based approach supports your authentication mechanism (see below).

Supported steps and authentication methods

One-shot authentication based on flows currently supports the following steps and authentication methods:

Supported steps:

  • Basically, a one-shot authentication flow must include non-interactive steps only.
  • However, several steps that already respond with Next Step code during initialization (e.g., Terms Of Service Step) also work and can be useful.

Supported authentication methods:

  • Basic HTTP authentication
  • Kerberos (experimental, limited testing)
  • SSO Tickets (experimental, limited testing)
  • Planned (future): OAuth2/OIDC

Configuring flow-based one-shot authentication

The following instructions will guide you through configuring a one-shot authentication flow. In this use case, IAM will terminate the flow if the client does not have an operator role. The use case only supports basic HTTP authentication.

The one-shot authentication flow consists of the following steps:

  • An HTTP Basic Authentication Step, in which IAM verifies the credentials provided by the client in the HTTP Basic Authentication request header.
  • An Abort Step, to terminate the flow if the client has no operator role.

Further below, you'll find a diagram that visually represents the steps.

Perform the following steps:

  1. In the Config Editor, go to
    Loginapp >> Applications and Authentication
  2. In section One-Shot Authentication, add a One-Shot Target Application plugin to the One-Shot Applications list. Edit the plugin as follows:
  3. Application ID field: Create an Application ID plugin. Enter an ID for your one-shot flow in the ID field of the Application ID plugin, for example my-1shot-flow-id.
  4. Authentication Flow field: Create a One-Shot Authentication Flow plugin. Edit the plugin as follows:

  5. One-Shot Authentication Flow plugin configuration

    1. In section Basic Settings, in the Steps list, create an HTTP Basic Authentication Step plugin. In the plugin's Password Repository field, select the predefined Default Password Repository plugin from the drop-down list. Leave the settings in all other fields as they are.
    2. Still in the Steps list, add an Abort Step plugin below the HTTP Basic Authentication Step plugin. The abort step will terminate the flow if the client has no operator role. Edit the Abort Step plugin as described below in Configuring the Abort Step plugin.
    3. Leave the default settings of the Processors property (Basic Settings) and the Enable Temporary Locking checkbox (Security Settings) as they are.
    4. Return to the One-Shot Target Application plugin dialog.
  6. The Airlock Gateway Roles list defines the client's Airlock Gateway roles set after the authentication flow has been completed successfully.
    1. Add a Role-based Gateway Role plugin to the list.
    2. In the User Role Name field of the Role-based Gateway Role plugin, enter the user role operator.
  8. Identity Propagation list: Select the predefined Generic ID Propagator - REST Identity Propagation plugin from the drop-down list.
  9. Username To Propagate Provider field: Select the predefined User Principal Name Provider - DEFAULT plugin from the drop-down list.
  10. Click Activate to activate your configuration.
  11. You have now configured and activated the new One-Shot Authentication Flow “1shot Flow Basic Auth”. This flow verifies one-shot authentication requests using HTTP basic authentication. The flow will be terminated if the client does not have an operator role.

Configuring the Abort Step plugin

The following instructions describe the configuration of the Abort Step.

Configuring the Abort Step plugin

  1. Basic Settings section, Error Code field: Defines the error code to be included in the response in the case of a flow abortion. Enter a meaningful code, in this case for example ROLE_MISSING.
  2. Tags/Guards section, Skip Condition field: An abort step will always terminate the current flow. If you do not want this, you must define a skip condition. If the skip condition is fulfilled, the abort step is ignored (skipped) and the flow continues with the subsequent step.
    In our use case, the flow must only be terminated if the client does not have the operator role. If the client does have this role, the flow must continue. To achieve this, create a Has Matching Role plugin in the Skip Condition field. Edit the plugin as follows:
    1. Role Providers field: Select the predefined All User Roles plugin from the drop-down list.
    2. Role Pattern field: Defines the pattern that will be checked against the client's assigned roles. Enter operator in the field. If the client has the operator role, the pattern matches and the condition to skip the abort step is fulfilled.
  4. You have now configured an Abort Step that will terminate the flow if the client has no operator role.

Visual representation of instruction steps

The diagram below visually represents the steps described above. It shows all required plugins, along with display names and property values, in the order they must be created (from left to right).