Self-unlock flow example

Requirements

Component

Requirement

Comments

Airlock IAM

  • Airlock IAM 7.5 or newer.
  • An Airlock 2FA subscription is required.

If no Airlock 2FA subscription is available, a similar example can be set up using mTAN instead of Airlock 2FA.

Intended solution environment

This example shows how to configure and use the public self-service REST API as unlock self-service using Airlock 2FA as 2nd factor.

Goal

  • Understand how public self-services can be used to unlock user accounts.
  • Be able to configure and try out the unlock flow.
  • Understand how to use the 2nd factor to approve the unlock operation.

All following procedures are exemplary and will vary according to your setup or needs.

Initial thoughts

With the shown unlock self-service flow, locked users are able to unlock their user account using Airlock 2FA as 2nd authentication factor.

The unlock self-service is only available for users that locked themselves by too many login attempts with the wrong password (or failed password change attempts).

The number of possible self-unlock attempts must be limited by the configuration.

The flow is similar for other 2nd factors and may be configured to work with multiple 2nd factors using a corresponding selection (as in the authentication flow). The flow may additionally be extended to allow the user to order a password letter instead of only unlocking the account.

Once the maximum amount of unlocking attempts has been reached, the account can only be unlocked by the helpdesk or user administrator. No information is provided to the end-user about the number of remaining unlock attempts.

No user enumeration protection

The described configuration does not provide protection against user name enumeration because the used Airlock 2FA Factor Step is not username enumeration safe.

To make the flow safe against username enumeration, an identity verification step can be used (e.g. Email Identity Verification Step, SMS Identity Verification Step, or Secret Questions Identity Verification Step).

Prerequisites

  • The user account used in the example exists in the IAM database.
  • The Loginapp REST API is configured.
  • The user is able to approve a transaction or operation using Airlock 2FA. The user has a corresponding smartphone app or a suitable hardware token.

Configuration and REST calls

The flow is configured as public self-service flow:
Loginapp >> Public Self-Service Flows >> a flow implementing self-unlock.

The flow steps configured for this example and a high-level view of the REST calls is shown in the diagram below.

Public-Self-Service-Unlock-Flow

Step

Purpose

Comment

A

Provide the name of the user for which the flow should be executed.

This step is required to start the flow and to select the user.

By default, this step will complete with 200 OK, even if the user cannot be found, the account is locked or invalid. This is done to provide protection against user enumeration attacks.

To change this, adapt the configuration of the Default Self-Unlock Restrictions plugin or define your own restriction settings using the plugin Custom Public Self-Service Restrictions.

  • Examples of LockReason:
  • LockReason.TooManyLoginFailed
  • LockReason.MaxWrongOldPassword
  • LockReason.FraudReportedByUser

B

Approve the unlock operation using Airlock 2FA as the 2nd factor.

To authenticate the end-user in the flow, the operation has to be approved using the Airlock 2FA authentication factor (push or Offline QR-Code).

C

Unlock the account.

This step unlocks the account and resets the configured Failed Attempts Counters to Reset.

The ID of the Failed Attempts Counters to Reset is identical to the Authentication Method ID of the locked factor's authentication step.

Failing to effectively limit the number of unlocking operations may result in a severe security risk (brute force attack on the password).

  • Limit the number of unlock attempts with property Loginapp >> Public Self-Service Flows >> Max Number of Unlocks.
  • If using the Custom Public Self-Service Restrictions plugin (instead of the Default Self-Unlock Restrictions plugin), make sure to limit the number of unlock attempts.

The described flow lacks (on purpose) an identity verification step. It can therefore not protect against username enumeration. For the flow to function correctly, the Restriction property must be set such that feedback about unknown (locked, invalid, etc.) users is allowed.

The Default Self-Unlock Restrictions plugin has safe defaults. If using it you must therefore enable its checkboxes to make it work with the above flow:

  • Nonexistent User Feedback
  • Invalid User Feedback
  • Locked User Feedback
  • Too Many Unlock Feedback