Airlock 2FA Activation Step
Step to add a new Airlock 2FA device. This step will generate a QR code (and an Airlock 2FA account if necessary) that needs to be scanned by the device to be added.
Depending on the use-case, this step should be configured as an 'Authentication Flow Step', 'Protected Self-Service Flow Step' or 'User-Self-Registration Flow Step'.
- Migration to Airlock 2FA (Authentication Flow)
- In this case, the user does not yet have any Airlock 2FA device, but already has a different second authentication factor (see Security note) that needs to be migrated to Airlock 2FA. This step needs to be configured as an 'Authentication Flow Step' inside a 'Migration Selection Step'. Upon successful migration, the user will have an Airlock 2FA account and a newly registered Airlock 2FA device that can be used for strong authentication. The user's default authentication method will have been changed to Airlock 2FA.
- Activation of an Airlock 2FA device (Protected Self-Service Flow)
- In this case, the user already has a second authentication factor (see Security note) and needs to activate an Airlock 2FA device. This typically happens when the user already has Airlock 2FA as a second authentication factor and needs to activate an additional device. This step needs to be configured as a 'Protected Self-Service Flow Step'. Upon successful activation, the user will have an Airlock 2FA account and a newly registered Airlock 2FA device that can be used for strong authentication. In contrast to the migration scenario above, the user's default authentication method will remain unchanged.
- Activation of an Airlock 2FA device (User-Self-Registration Flow)
- In this case, the flow step will register a futurae user account with the device, that was used to scan the activation code. It is required to add an 'Airlock 2FA Token Persisting Handler' in the 'User Persisting Step' to persist the linked futurae user account with the IAM user.
In the migration and self-service scenarios, an optional 'Airlock 2FA Device Edit Step' can be configured afterwards, to allow the user to edit the newly registered device, e.g., changing its display name.
Note: This step can only register one device in one flow execution. The flow has to be started multiple times when more devices are needed.
Security note: For migration and self-service flows this step should be restricted to strongly authenticated users. To do so, a 'Pre-Condition Tag' should be used to ensure that the user is strongly authenticated (using at least one of his pre-existing second authentication factors). In particular, this step should not be used for a user authenticated with username and password only. In the password only use-case, the (physical) generation of an 'Airlock 2FA Device Activation Letter' is necessary.
airlock2faSettings) enrollmentTimeoutSeconds) Note: This value is not used when generating activation letters.
provideActivationCodeShort) 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.
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: Airlock2FAActivationStep
id: Airlock2FAActivationStep-xxxxxx
displayName:
comment:
properties:
airlock2faSettings:
customFailureResponseAttributes:
customResponseAttributes:
dynamicStepActivations:
enableShortLivedOnlineQrCodes: false
enrollmentTimeoutSeconds: 300
interactiveGotoTargets:
onFailureGotos:
preCondition:
provideActivationCodeShort: false
requiresActivation: false
shortLivedQrCodeValidity: 10
shortLivedQrCodeValidityOverlap: 3
skipCondition:
stepId:
tagsOnSuccess: