Token enrollment

After downloading the Airlock 2FA app from the app store, it does not contain any cryptographic key material required for authentication. The end-user must first enroll an Airlock 2FA token with the app. Enrollment is the process of activating a new Airlock 2FA token on the app and linking the token to an end-user account. During this process, the Airlock 2FA app generates the necessary cryptographic keys and stores them securely in the smartphone's secure storage.

 
Notice

In addition to the Airlock 2FA app, Airlock 2FA also supports hardware tokens for authentication and transaction approval. Note that hardware tokens are not enrolled but assigned to an end-user by the administrator. For more information, see Hardware token management for Airlock 2FA.

End-users can enroll an Airlock 2FA device by either scanning a QR code or manually entering a 16-digit activation code in the app. Both codes are provided via a printed activation letter or displayed in the browser when the end-user enrolls the device.

Enrollment by QR code is the default. The 16-digit activation code provides an alternative method if an end-user's smartphone does not have a working camera or the user prefers to not give the app camera access.

 
Notice

Activation via the digit code is disabled by default. To enable this option, see the section “Enabling the 16-digit activation code” further below.

The following screenshot shows both codes in the browser:

An Airlock 2FA device can be enrolled on different occasions. The table below describes the possible moments of enrollment.

Enrollment occasion

Description

Activation letter

The enrollment QR code and the 16-digit activation code (if enabled) are printed on a letter and sent to the user. The user scans the QR code or manually enters the 16 activation digits to enroll the Airlock 2FA device.

 
Risk

Using an activation letter provides a high level of security, but only if you trust the delivery method (e.g., postal service). If the activation letter is lost or stolen, an unintended third party may be able to illegally enroll their device. To prevent this, you can invalidate the letter. See also Airlock 2FA token management.

Authentication (migration to 2FA token)

During the authentication flow, the end-user is prompted to migrate to Airlock 2FA and activate an Airlock 2FA device. They can enroll by scanning the enrollment QR code (default) or, if enabled, by entering the 16-digit activation code. Both codes appear in the browser.

Self-registration

During the self-registration flow, the end-user is prompted to select an additional authentication method. If the end-user chooses Airlock 2FA, they are asked to activate their Airlock 2FA device by scanning the enrollment QR code (default) or, if enabled, by entering the 16-digit activation code. Both codes appear in the browser.

Protected self-service

In the protected token management self-service, logged-in end-users can add a new 2FA device/token with the Airlock 2FA Device Management feature. After clicking the Activate Airlock 2FA device button, the end-user either scans the displayed QR code or enters the displayed activation code (if enabled) to enroll the new device.

Call the helpdesk or visit the counter

An end user requires support to enroll their device and contacts the help desk or visits your counter. Your staff can provide the end-user with a new 16-digit code, which is obtained from the end-user's details view in the Adminapp. For more information, see Airlock 2FA token management.

 
Risk

Because the 16-digit activation code could be given to an unintended third party, your organization's representative should verify the end-user's identity before providing the code.

Enabling the 16-digit activation code

The 16-digit activation code is an additional method to enroll an Airlock 2FA device, other than via QR code. It provides an alternative if an end-user's smartphone does not have a working camera or the user prefers to not give the app camera access.

Enrollment by QR code is the standard setting. Activation using the digit code is disabled by default. To enable it, follow these steps:

  • Set the property Provide Short Activation Code of the Airlock 2FA Activation Step to “true”.
  • Update the template for printed activation letters to include the 16-digit code. This step is only necessary if your organization supports enrolling new 2FA devices with printed activation letters.

1. Setting the Provide Short Activation Code property to “true”

The Provide Short Activation Code property is part of the Airlock 2FA Activation Step. This step appears in all flows where end-users can enroll a new Airlock 2FA device: During migration to Airlock 2FA in the authentication flow, the self-registration flow, and the 2FA flow for protected self-services. Enable the property in every flow where enrollment with the 16-digit activation code should be allowed.

Proceed as follows:

  1. In the Config Editor, navigate to the flow that includes the Airlock 2FA Activation Step plugin.
  2. Open the plugin dialog and go to the Basic Settings section.
  3. Check the Provide Short Activation Code option to enable the property.
  4. Repeat the above steps for all relevant flows.
  5. Activate your configuration.
  6. End-users will now be able to enroll an Airlock 2FA device with the 16-digit activation code.

2. Updating the template for printed activation letters to include the 16-digit code

IAM provides standard templates for printed activations letters named airlock-2fa-letter-<de/en>.docx. They are located in the local directory /home/airlock/iam/instances/common/report-templates after installing Airlock IAM (see Configuration files).

To include the 16-digit code:

  1. Open the appropriate airlock-2fa-letter-*.docx in your report-templates directory.
  2. Insert the placeholder ${activationCodeShort} where you want the activation code to appear.
  3. Add an instructional sentence, such as:
    If you cannot scan the QR code, select Enter Code in the app and manually enter the following code: ${activationCodeShort}

  4. When you generate an activation letter for an end-user, ${activationCodeShort} will be replaced automatically with the 16-digit code.

  5. Save the updated template.