Use case

Hardware token management for Airlock 2FA

This article shows an example of how to assign and manage Airlock 2FA hardware tokens for a user.

Please refer to Token management (Airlock 2FA) for general Airlock 2FA token management examples.


  • Understand how Airlock 2FA hardware tokens can be assigned and shipped to a user.
  • Understand how to manage Airlock 2FA hardware tokens.

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

Initial thoughts

The following examples use the Airlock IAM Adminapp. A REST API for all administrative actions of the Airlock IAM Adminapp is available.

  • All admin actions shown below are subject to access control.
  • Review the access control configuration in the Adminapp.
  • In the following, we assume, that the administrator has all the necessary privileges.


  • The IAM Adminapp is configured, so users and authentication tokens can be managed.
  • The Airlock 2FA Token Controller is configured in the IAM Adminapp.
  • The administrator has enough privileges (roles) to perform all shown actions.
  • All examples are given on an existing user account.
  • Hardware tokens are available for the configured Airlock 2FA service.

Assign Airlock 2FA hardware token to a user

To assign a hardware token to a user, the following steps must be performed in the Airlock 2FA tab of the selected user.

  1. Click on the button Assign hardware token.
  2. Take a hardware token from the stock of assignable hardware tokens and enter the tokens serial number into the dialog shown on the screen.
  3. Adminapp - Airlock 2FA, Assign available hardware token, Serial number
    • For faster lookup, just enter the last three or four digits of the serial number.
    • You may also use a barcode scanner to select the token.

    The Airlock IAM Token Controller plugin may be configured to allow assigning a hardware token to multiple users of the same service. If configured to allow that, even hardware tokens that are already assigned to a user will be listed.

  4. Click on the Assign button.
  5. The hardware token is now assigned and ready to use.

If the token at hand cannot be found in the list of assignable tokens, this may have one of the following reasons:

  • The token is not assigned to your organization in the Futurae cloud. A hardware token can be used across services but only be within one organization.
  • The token is assigned to another user and the configuration forbids assigning it to multiple users (the default). Either find the assigned user and unassign the token or allow assigning hardware tokens to multiple users (in the Airlock 2FA Token Controller configuration). Hardware tokens can only be assigned to multiple users within one service.
  • The token has been assigned to another user in the past and has then been archived (instead of being unassigned).
    • -Archived tokens cannot be assigned again.
    • -Unarchiving hardware tokens requires contacting Airlock support.

Hardware tokens are ready to use directly after the assignment process. In other words: Assigned hardware tokens can be used as the second authentication factor by the legitimate user or even on behalf of a user immediately after the assignment.

  • Make sure that the token is only accessible by the legitimate user.
  • Choose a secure shipment or handover method.
  • Depending on the ordered hardware tokens, the user must enter an activation code as a legitimation step before the first usage.

Printing a shipment letter for hardware tokens

There are several ways to hand over the device to a user. The IAM Adminapp directly supports printing shipment letters.

Hardware token shipment letters can be directly generated from the IAM Adminapp by pressing the Create shipment letter button. Shipment letters typically contain a text, the recipient address, the token serial number, and optionally the activation code.

  • Shipment letter support is configured in the Airlock 2FA Token Controller plugin.
  • How the letter is generated (and printed) is defined by the renderer configuration.

A hardware token may be assigned to multiple users (this requires special configuration of the Airlock 2FA Token Controller). If this is the case, the shipment letter may only contain information about the one user that the letter was printed or generated for.

Airlock 2FA hardware token management

The following screenshot shows two hardware tokens in the Airlock 2FA tab on the user detail page: a QR code token and an OTP token:

Adminapp - Airlock 2FA Hardware Device, list of devices

Possible actions:


Unassigns the hardware token from the user in a way that it can be reassigned again. It will show up again when selecting hardware tokens for assignment. This is the right thing to do if a token has been assigned by accident or if the token has been returned to the administrator.

Unassigned hardware tokens can no longer be used by the end-user and reassigning requires knowledge of the serial number.

This action cannot be undone.


Archives the hardware token, i.e. permanently removes the hardware token from usage. It will not be among the set of assignable tokens after archiving. Take this action if the token was stolen, has been lost, or is damaged.

The token will no longer be usable by the end-user and reassigning will not be possible. Unarchiving hardware tokens involves contacting Airlock support.

This action cannot be undone.

Create shipment letter

Creates a shipment letter to send the token to the user.


Synchronize OTP hardware tokens: use this if the internal clock of the OTP hardware token is out of synch with the current time and therefore OTP tokens are no more accepted.

This may be necessary for OTP hardware tokens that have not been used for a long time.


  • Modification of Airlock 2FA accounts directly in Futurae's management web application should be avoided. This is because data regarding activation letters are stored in the Airlock IAM database only and because Airlock IAM does not support all features that can be managed in the Futurae cloud.
  • PIN protection of hardware tokens is currently not supported by Airlock IAM. Please contact Airlock staff if you are interested in this feature:
  • Whether a hardware token requires an activation code before first usage or not needs to be specified before ordering the tokens. Already delivered tokens cannot be changed.
  • Assigning hardware tokens to multiple users is only possible if enabled in the configuration and within the same service.