Migrating the Airlock 2FA app - Deleting all tokens

This article describes how to migrate from the Airlock 2FA app to either an alternative 2FA app, or to a new business app with a built-in two-factor authentication solution based on the Futurae Mobile SDK (a so-called One App solution). In both cases, all "old" tokens of the migrating user for the business application are deleted.

The use cases and configurations described in this article are recommendations. You can change, enhance or replace them according to your requirements.

• Prerequisites for configuring the migration:
• Your end-user database contains a "Migrated" column with value type Boolean. This DB column is required to prompt the end-user to migrate.

• Prerequisites for performing the migration (by the end-user):
• A service account for the Airlock 2FA app exists in the Futurae cloud.
• The end-user account exists in IAM.
• The end-user has Airlock 2FA enabled as a possible authentication method.
• The end-user has installed the Airlock 2FA app on the mobile phone.
• The end-user's mobile phone is connected to the Internet and can connect to the Airlock 2FA service in the Futurae cloud.

0. Configuring the migration process includes the following steps:
1. Preparing for migration
2. Adding a migrated flag to the user accounts
3. Configuring the migration flow
4. Adapting the text in the login UI

Detailed descriptions of each step follow below.

Usually, one Airlock 2FA app corresponds with one service account in the Futurae cloud. However, it is possible to use multiple apps at the same time with the same Airlock 2FA service. This is a useful feature when migrating from the Airlock 2FA app to another 2FA app or One App solution. Thus, migrated and new users can already use the new app, whereas non-migrated users can still work with the old app (see also Using multiple apps in one service).

0. Proceed as follows to plan the migration process:
1. Contact the Airlock staff (order@airlock.com) and provide information on the following:
• Request to temporarily have two 2FA apps in your Airlock service account.
• Required account details for the new 2FA app or One App.


Never share API keys.

• The time schedule: When to make the new app available in the service and the app stores; when and how to inform the users; when to remove the old app from the service; and so on.
2. Upload the new 2FA app or One App to the prevalent app stores.
3. Inform the end-users about the introduction of and migration to the new 2FA app/One App. Start the information process in time.

This section explains how to add a migrated flag to the IAM user accounts. This flag is set to true as soon as the end-user migrated to the new 2FA app/One App. The false flag is used to prompt an end-user to migrate.

0. Proceed as follows:
1. Go to:
   MAIN SETTINGS >> Data Sources >> User Data Source >> Database User Persister
2. In section Context Data in the list Context Data Columns, create and edit a new Boolean Context Data Item plugin, with the Boolean Context Data Item Name plugin as Context Data Name.
3. In property Context Data Name of the Boolean Context Data Item Name plugin, enter migrated as name for the new Boolean context data item. Ensure that this name equals the name of the corresponding column in your user database.


You can in fact choose any name you like for the new Boolean Context Data Item. The only requirement is that the name equals the name of the corresponding column in your user database.

4. Activate your configuration.
5. The IAM user accounts now contain a new Boolean context data item/flag. Additionally, the user Profile page in the Adminapp contains a corresponding checkbox.

• In this use case:
• An end-user will be prompted upon login to migrate to the new 2FA app / One App, in the case the user is not migrated yet. The prompt does no longer appear when the migrated flag in the user's IAM account is set to true.
• All previous tokens of the user will be deleted after migration.

The instructions below guide you through the setup of the corresponding migration flow.

0. Proceed as follows:
1. Go to:
   Loginapp >> Applications and Authentication >> <Your business application> >> Authentication Flow
2. In section Basic Settings in the Steps list, create or edit the Migration Selection Step plugin.
3. In section Basic Settings of the Migration Selection Step plugin, create and edit a new Advanced Migration Selection Option plugin, as follows:
4. In property Option Name, enter a relevant option name for the plugin, such as MIGRATE_NOW.
5. In property Steps, create and edit the following Step plugins. Together, these plugins build the migration flow.
0. Create and edit the following plugins:
1. Airlock 2FA Activation Step (with additional Activation) plugin, with default settings. This plugin migrates to and activates the new 2FA app / One App.
2. Airlock 2FA Delete Old Devices Step plugin, with default settings. This plugin deletes all tokens of the migrated user (except the new token for the new 2FA app / One App).
3. Set Context Data Step plugin. This plugin automatically sets the migrated flag to true in the user's IAM account upon completion of the previous step. Thus, the user will no longer be prompted to migrate the next time they log in.
• Specifying the Set Context Data Step plugin
• In section Basic Settings and property User Data Items, create and edit a Boolean Context Data plugin, as follows:
• In property Context Data Item Name Config, select the Boolean Context Data Item Name plugin you created in Adding a migrated flag to the user accounts.
• In property Value Provider Config, create a Boolean Context Data Value Provider plugin, enter a meaningful name for the plugin in the Identifier field and connect it in property Context Data Field with the Boolean Context Data Item Name plugin you created in Adding a migrated flag to the user accounts. Additionally, enable the property Mandatory.
6. Return to the Advanced Migration Selection Option plugin dialog. The plugin's property Condition defines the condition to start the authentication flow defined above. This is when the end-user has not migrated yet. That is, when the migrated flag is not set and has value null (or false).
   To define this condition, create and edit the Boolean Condition plugin in the Condition property field, as follows:
1. In property Value Provider, select the Boolean Context Data Value Provider plugin you created in the previous step.
2. Enable the checkbox Is Fulfilled If Value Is Null.
7. Activate your configuration.
8. You have now configured an authentication flow that migrates an end-user from the Airlock 2FA app to a new 2FA app or to the One App. This use case deletes all previous tokens of the user.

In this use case, each not-yet-migrated end-user is prompted to migrate to and activate the new 2FA app/One App solution upon login to the (old) business app. The prompt text appears in a separate window during the login process. This text is specified in the language property files provided with Airlock IAM. For more information on how to add and/or customize UI texts, see Customizing Loginapp UI texts and changing translations with the Loginapp Design Kit.

• The corresponding keys are:
• authentication.migration.methods.migrate-to-new-airlock2fa.title.caption
• authentication.migration.methods.migrate-to-new-airlock2fa.migration-instructions
• authentication.migration.methods.migrate-to-new-airlock2fa.next-steps-instructions

• Internal links:
• Using multiple apps in one service
• Customizing Loginapp UI texts and changing translations with the Loginapp Design Kit