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.

Goal

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

Notice

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

Initial thoughts

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

All administrative actions shown below are subject to access control.
We assume that the administrator working with the Adminapp has the necessary privileges to perform the actions. To verify this, review both your access control configuration in the Config Editor and the roles assigned to the respective administrator in the Adminapp (administrator's details view)
Info
The access control configuration is defined in the Role-based Access Control dialog in the Config Editor (Adminapp >> Access Control). You assign administrator roles to administrative actions in this dialog.

Prerequisites

The IAM Adminapp is configured and working.
The Airlock 2FA Token Controller plugin is configured in the Config Editor. This plugin allows the management of an end-user's Airlock 2FA account in the Adminapp.

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.

Click on the button Assign hardware token.
Take a hardware token from the stock of assignable hardware tokens and enter the tokens serial number into the dialog shown on the screen.
Info
- 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.
Info
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.
Click on the Assign button.
The hardware token is now assigned and ready to use.

Info

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.

Risk

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.

Info

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:

Possible actions:
Unassign	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.
	Notice 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.

Archive	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.
	Notice 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	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.

Limitations

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: order@airlock.com.
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.