Airlock 2FA Authentication Step
The identifier of the authentication method for this step is 'AIRLOCK_2FA' and is also the identifier for failed authentication attempts.
Note that for mobile-only authentication scenarios, the other authentication plugin "Airlock 2FA Mobile Only Authentication Step" should be used.
factors) Priority list of all enabled factors. Only factors that are in this list can be used for authentication. The factors are offered in the configured order.
Online factors (One-Touch and Online QR Code) must come before all other factors. It is recommended to include at least one offline factor.
Available factors:
- One-Touch: a push message is sent to the user's mobile app, where it must be approved. This is an online factor and will require device selection if the user has multiple devices.
- Online QR Code: a QR code is displayed in the browser, which has to be scanned by a mobile app and approved there. This is an online factor. No prior device selection is required.
- Passcode: the device (mobile app or hardware token) generates a time-dependent code (OTP) that has to be entered manually in the browser. This is an offline factor. No prior device selection is required.
- Offline QR Code: a QR code is displayed in the browser which has to be scanned by a mobile app or hardware token. The device displays a code (OTP) that must be entered manually in the browser. This is an offline factor and will require device selection if the user has multiple devices.
maxFailedPasscodeCheckAttempts) enforceDeviceSelection) enablePushToAll) If Push-to-All is enabled for One-Touch, device selection is never required for One-Touch. Push notifications are sent to all of a user's devices and authentication can be approved on any of the devices.
The combination of Push-to-All and "Cooldown Period" can result in push notifications being sent to devices that are currently still in cooldown. However, those devices can not be used for successfully completing the authentication.
The combination of Push-to-All and "Lock User on Fraud" could have undesired effects, because users might report fraud in legitimate use-cases.
includeDeviceUsageInformation) If enabled, the device choices provided for device selection include usage information for each device: the time of enrollment ("enrolledAt") and the time of last use ("lastUsedAt").
The information is revealed to anyone completing the flow steps preceding the device selection. Enabling this property in flows accessible without prior strong authentication may lead to unwanted information disclosure.
messageProvider) Creates the message that will be displayed on the user's device when using One-Touch. If no message provider is configured, only a title with the fixed translation key "airlock2fa.one-touch.authentication-title" or its fallback value "Login" is used.
Using a custom Message Provider could prevent authentication with a smartwatch: Because additional information is included, the app forces the user to scroll through the message (which might not be supported by the watch).
qrCodeMessageProvider) Creates the message that will be displayed on the user's device when using Online QR Code or Offline QR Code factors. If no message provider is configured, the default title of Futurae will be shown (without any additional information items).
Note that the Login ID cannot be included because it is only available in the One-Touch Message Provider.
Also, because of technical limitations, the title of Offline QR Codes is always the default title from Futurae, the configuration is ignored.
enableShortLivedOnlineQrCodes) Whether to enable short-lived Online QR Codes. Unlike regular Online QR Codes, these are refreshed regularly, allowing for shorter individual validities.
Shorter validities enhance security, since forwarding a QR code to victims and tricking them to scan the QR code becomes more difficult if the available time window is small.
shortLivedQrCodeValidity) The maximum amount of time in seconds for which an Online QR Code is valid after it is first displayed to the end user (ignoring latency). This duration includes the time defined for the validity overlap. It only limits the time for scanning the QR code, not for the confirmation or approval afterwards.
Security Notice: The validity duration represents the attack window. Choosing a small validity makes attacks more difficult, in cases where an attacker attempts to forward a QR code to a victim for scanning.
This setting is only active if short-lived Online QR Codes are enabled.
shortLivedQrCodeValidityOverlap) Defines the duration in seconds during which the previously displayed QR Code is still valid after being replaced by the next QR code in sequence.
This provides time for pending requests to complete and ensures that a valid QR code is displayed at every moment in time, provided that there are no network or performance issues.
The validity overlap must meet the following criteria:
- It must be smaller than half the overall validity of the QR code.
- It must be larger than the Loginapp UI polling interval (1s) plus the network latency (IAM backend → Loginapp UI plus Mobile Device → Futurae Backend).
Note that the polling interval may differ for custom user interfaces.
This setting is only active if short-lived Online QR Codes are enabled.
shortLivedSessionTimeout) Maximum duration in seconds during which short-lived Online QR Codes are displayed until a session timeout occurs.
This setting is used exclusively for short-lived Online QR Codes. It has no effect if short-lived Online QR Codes are disabled.
generateLoginId) If enabled, a random ID is generated and shown to the user during One-Touch authentication.
The ID is generated according to the pattern configured below.
The ID is shown on the Airlock 2FA device and on the login page, allowing the user to correlate the session.
The "One-Touch Message Provider" property must be configured for the Login ID to be displayed on the device. The message provider can use the Login ID by configuring a dedicated value provider.
If the multi-numbered challenge feature is enabled on the Futurae service, "Generate One-Touch Login ID" should be disabled. In that case, the Login ID does not provide any security enhancement but severely impacts usability.
loginIdPattern) Pattern syntax:
pattern = fix_part | random_part [fix_part | random_part]*
random_part = {alphabet_name:number_of_characters}
fix_part = any_string_without_'{'
The alphabet_name refers either to a built-in alphabet (see below) or to a custom alphabet defined in the separate Alphabets property below.
Examples:
{digits:6} → 482913
OTP-{digits:4} → OTP-4821
{HEX:8} (with HEX defined in the custom Alphabets property below) → A9F03C1B
Built-in and ready-to-use alphabets are:
- "
digits" all decimal digits (i.e. the characters 0123456790) - "
lower26" standard alphabet with 26 lowercase letters (i.e. the characters abcdefghijklmnopqrstuvwxyz) - "
upper26" standard alphabet with 26 uppercase letters (i.e. the characters ABCDEFGHIJKLMNOPQRSTUVWXYZ) - "
alpha52" standard alphabet with 26 upper- and 26 lowercase letters (i.e. the characters ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz) - "
distinct" distinct standard characters: digits, upper- and lowercase letter without the hard to distinguish '0,O,1,l,I' (i.e. the characters 23456789abcdefghijkmnopqrstuvwxyzABCDEFGHJKLMNPQRSTUVWXYZ) - "
DISTINCT" distinct standard characters (with uppercase letters): digits and uppercase letter without the hard to distinguish '0,O,1,I' (i.e. the characters 23456789ABCDEFGHJKLMNPQRSTUVWXYZ) - "
extended" contains most of the characters visible on a computer keyboard without the hard to distinguish '0,O,1,l,I' (i.e. the characters +-.,:;$<>()[]{}%&!?/*@#=_23456789abcdefghijkmnopqrstuvwxyzABCDEFGHJKLMNPQRSTUVWXYZ)
NOTE: Characters in this pattern do not pass the input filter for tokens (OTP, SMS, and alike). Choose a different pattern for tokens or relax the corresponding pattern (in the Loginapp's security settings). Characters may be blocked by a WAF deny rule.
Using custom alphabets:
1. Define an alphabet in the Alphabets property below.
2. Reference it in the pattern using {alphabet_name:number_of_characters} where the is the key of the alphabet in the Alphabets property.
NOTE: A pattern that results in a very long Login ID may negatively impact usability. It may also cause issues when generating the push message, as push messages are limited in length. To avoid rejection by Futurae during authentication, do not use special characters (e.g. from the 'extended' alphabet).
loginIdAlphabets) How it works:
The map key defines the alphabet_name:number_of_characters.
The plugin (alphabet) defines the characters used for sampling during random generation.
The alphabet can then be referenced in the Pattern property above using {alphabet_name:number_of_characters}.
Example configuration:
Key (alphabet_name): HEX
Plugin: Alphabet with the following characters 0123456789ABCDEF
Example usage in the Pattern property above:
{HEX:8} → A9F03C1B
OTP-{HEX:6} → OTP-4F9A2C
tagsOnSuccessfulOneTouch) tagsOnSuccessfulOnlineQrCode) tagsOnSuccessfulPasscodeCheck) tagsOnSuccessfulOfflineQrCode) tagsOnSuccessfulBypass) airlock2faSettings) respectCooldownPeriod) If enabled, devices in cooldown cannot be used for authentication.
If disabled, the step ignores the "Cooldown Period" for new devices configured in the "Airlock 2FA Settings". This is typically used for authentication steps that protect low-risk applications, such as a portal page, which can also be accessed using devices in cooldown.
If no "Cooldown Period" is defined, enabling this property has no effect.
interactiveGotoTargets) dynamicStepActivations) skipCondition) If this condition is configured and fulfilled, the step is skipped and the flow execution continues with the subsequent step.
preCondition) requiresActivation) tagsOnSuccess) stepId) onFailureGotos) If the step fails (no retry) and a goto target for the error code is defined here, the flow does not fail and instead a "goto" to the specified target step is executed. Note that even when the "goto" is executed, any error codes that are considered a failed factor attempt will still increment the "failed attempts" counter, and may lead to the user being locked. Therefore, this may still result in a failed flow.
A typical application of this feature is switching to an alternative authentication factor step, if an external service (e.g. Futurae server, SMS gateway) is not available (error code EXTERNAL_SERVICE_UNAVAILABLE with "Strict Counting" disabled, which will not increment the "failed attempts" counter). Other error codes can be found in the IAM REST documentation, in both the general "Error Codes" section and in the documentation of specific endpoints.
customResponseAttributes) A list of custom attributes that are returned in the REST response in addition to the standard attributes the step already returns. The custom attributes defined here are only returned if the step result does not lead to an error response.
Custom attributes are added to the response when a step is initialized and when actions are executed on the step. They will therefore be available in the response leading to this step, and in any responses from endpoints specific to this step. For non-interactive steps, custom attributes are accumulated and added to the response leading to the next interactive step.
Custom attributes are not returned for 'retrieve' endpoints.
customFailureResponseAttributes)
type: Airlock2FAUserFactorAuthenticationStep
id: Airlock2FAUserFactorAuthenticationStep-xxxxxx
displayName:
comment:
properties:
airlock2faSettings:
customFailureResponseAttributes:
customResponseAttributes:
dynamicStepActivations:
enablePushToAll: false
enableShortLivedOnlineQrCodes: false
enforceDeviceSelection: false
factors: [One-Touch, Passcode, Offline QR Code]
generateLoginId: true
includeDeviceUsageInformation: false
interactiveGotoTargets:
loginIdAlphabets:
loginIdPattern: {digits:6}
maxFailedPasscodeCheckAttempts: 3
messageProvider:
onFailureGotos:
preCondition:
qrCodeMessageProvider:
requiresActivation: false
respectCooldownPeriod: true
shortLivedQrCodeValidity: 10
shortLivedQrCodeValidityOverlap: 3
shortLivedSessionTimeout: 60
skipCondition:
stepId:
tagsOnSuccess:
tagsOnSuccessfulBypass:
tagsOnSuccessfulOfflineQrCode:
tagsOnSuccessfulOneTouch:
tagsOnSuccessfulOnlineQrCode:
tagsOnSuccessfulPasscodeCheck: