Migrating the Airlock 2FA app - Deleting only the migrated token

This article describes how to migrate from the Airlock 2FA app to a new business app with a built-in two-factor authentication solution based on the Futurae Mobile SDK (the so-called One App solution). In this use case, only the token used for the migration is deleted.

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

• In this use case:
• Three separate authentication flows are set up, to enable the use of the old business application and the new One App simultaneously (but on different devices). For more details, see Configuring the migration flows.
• Upon successful activation of the new One App, the migrated flag on the user's account is set to true. Additionally, the token used for the migration is deleted. The user can no longer use this token and the old business app/Airlock 2FA app on the device where the migration took place. However, the user can still use the old business app/Airlock 2FA app on other devices.
• The end-user is prompted to migrate when they access the business application via the browser. This prompt stops as soon as the user has installed and activated the new One App on one of their mobile devices.
• There is no prompt when users access the business application via the old business app in combination with the old Airlock 2FA app. It is up to you to decide whether and how to include migration prompts when using the old business app. For more details, see section Adapting the text in the login UI (prompts).
• If the end-user simultaneously employs the old business app/Airlock 2FA and the new One App, they can no longer use the "Open in App" button on devices that are not yet migrated. This is because the 2FA app service will try to open the new One App. However, this new app is not available yet on a non-migrated device.
• In this setup, an end-user may still access the business application in combination with the Airlock 2FA app for a long time after the new One App solution is released. This only stops when the old Airlock 2FA app is no longer supported in the 2FA app service. It is up to you to set this moment in time and to communicate this to your customers.

• 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.
• The One App solution is set up such, that it can facilitate the configuration options described further below in this article.

• 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 flows
4. Adapting the text in the login UI (prompts)

Detailed descriptions of each step follow below.

Usually, one Airlock 2FA app corresponds with one Airlock 2FA 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 the One App solution. Thus, the old 2FA app and the new One App can be used in parallel, by different end-users and on different devices (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 One App solution.


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 (e.g., via prompts, via e-mail, ...); when to remove the old app from the service; and so on.
2. Upload the new One App to the prevalent app stores.
3. Ensure that new users will only enroll and use the new One App.
4. Inform the existing end-users about the introduction of and migration to the new 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 One App solution.

The migrated flag is used to prompt an end-user to migrate to the new One App when accessing the business application via the browser. As soon as an end-user migrated to the new One App on one of their devices, the prompt disappears.

However, you may want this prompt to appear every time a user uses the browser to access the business application. Or maybe you do not want to prompt your end-users at all. In these two cases, you do not need the migrated flag. You can skip the instructions in this section and proceed with the configuration of the migration flows (see section Configuring the migration flows below).

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 the name of 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.

• In this use case, the following three separate authentication flows are set up:
• One flow for the use case where an end-user has installed the new One App on their mobile phone, and is going to use/uses it in mobile-only mode. In the mobile-only mode, both the business app and the 2FA authentication functions run on the same mobile device. This first flow has two sub-flows: One sub-flow will migrate the user to and activate the One App, the other triggers the regular mobile-only authentication for the new One App, when migration and activation is completed.



• One flow for the use case where an end-user wants to use the old business app/2FA app in mobile-only mode on a specific device, after they activated the new One App on another device. In this situation, the 2FA app service will always try to open the new One App for authentication. To still allow the use of the old apps, you must configure an authentication flow dedicated specifically to this use case.



• The third flow represents the use case where the end-user logs in to the business application via the browser.

The instructions below explain how to set up each authentication flow. There is one instruction section per authentication flow.

Flow 1A: Migration to the new One App - Mobile-only authentication

The flow described here migrates the end-user to and activates the new One App on a specific device. The flow is triggered when the end-user logs in to the new One App for the first time after downloading the app.

0. To configure the flow, proceed as follows:
1. Go to:
   Loginapp >> Applications and Authentication
2. Create a new application for mobile-only authentication with the new One App, to be used to migrate to and activate the One App. This flow is automatically triggered, if the end-user tries to log in to the One App, and the app is not activated yet.
3. Next, create the authentication flow for the just created application. For this, go to:
   Loginapp >> Applications and Authentication >> <Your mobile-only One App business application used for migration> >> Authentication Flow
4. In section Basic Settings in the Steps list, create and edit an Airlock 2FA Mobile Only Authentication Step plugin, as follows:
• In a mobile-only situation, the 2FA app service will try to open the new One App for authentication. However, as the One App is not activated yet, the end-user can at this point only authenticate via the old Airlock 2FA app. The Scheme Override feature allows replacing the One App URI returned by the app service with the URI of the "old" Airlock 2FA app. For this, go to property Scheme Override in section Advanced Settings of the Airlock 2FA Mobile Only Authentication Step plugin, and enter the URI scheme of the old 2FA app, which is airlock2fa.


A URI or Uniform Resource Identifier helps identify a resource or location without ambiguity. A URI scheme refers to a specific URI format, used to specifically identify a group of resources or locations. Some examples of URI schemes are the https URI scheme or the file URI scheme.
In the context here, the URI scheme refers to the scheme of the mobile authentication URI. It determines which app to open on the mobile device for authentication. For example, the URI scheme airlock2fa refers to the Airlock 2FA app.

5. The end-user can still use the old app to log in and authenticate.
6. Next, configure the actual migration flow. The flow will activate the new One App.
0. Proceed as follows:
1. Go to:
   Loginapp >> Applications and Authentication >> <Your mobile-only One App business application used for migration> >> Authentication Flow
2. In section Basic Settings in the Steps list, create or edit the Migration Selection Step plugin. This plugin should come after the Airlock 2FA Mobile Only Authentication 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 of the Advanced Migration Selection Option plugin, create and edit the following Step plugins. Together, these plugins build the migration flow.
• Airlock 2FA Activation Step plugin, with default settings. This step will activate the new One App on the currently used device.
• Airlock 2FA Delete Devices Step plugin, as follows: In section Basic Settings, in property Devices to Delete, create the plugin App Device Used For Login Unless Last App Device, with default settings. This plugin deletes the token used to authenticate the user in the current flow.
• Set Context Data Step plugin. This plugin sets the migrated flag to true in the user's IAM account upon completion of the previous steps.


Users who log in to the business application via the browser are prompted to migrate as long as the migrated flag is not set. However, you do not need the flag, nor the Set Context Data Step plugin, if the end-user should be prompted to migrate every time they log in with the browser, or if they should not be prompted at all. In these two cases, you can skip the rest of the instructions and activate your configuration.

• Specifying the Set Context Data Step plugin
• In section Basic Settings and in 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 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 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, if 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:
• In property Value Provider, select the Boolean Context Data Value Provider plugin you created in the previous step.
• 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 old business app/Airlock 2FA to the new business app with built-in 2FA authentication. This use case only deletes the token used for authentication in the migration flow.

Flow 1B: Regular use of the One App - Mobile-only authentication

As soon as the end-user has migrated to and activated the new One App, they can use the app for regular mobile-only authentication. The flow described here enables the regular mobile-only authentication flow with the new One App solution.

0. To configure the flow, proceed as follows:
1. Go to:
   Loginapp >> Applications and Authentication
2. Create a new application for mobile-only authentication with the new One App. This flow is automatically triggered when the end-user has migrated to and activated the One App.
3. Next, create the authentication flow for the just created application. For this, go to:
   Loginapp >> Applications and Authentication >> <Your mobile-only One App application> >> Authentication Flow
4. In section Basic Settings in the Steps list, create and edit an Airlock 2FA Mobile Only Authentication Step plugin. Use the default settings.
5. Activate your configuration.
6. You have now created the regular mobile-only authentication flow for the new One App.

Flow 2: Mobile-only authentication with the old business app

This flow represents the use case where an end-user wants to use the old business app/2FA app in mobile-only mode on a specific device, after they activated the new One App on another device. In this situation, the 2FA app service will always try to open the new One App for authentication. To still allow the use of the old apps, IAM introduced the Scheme Override feature. This feature allows replacing the One App URI (scheme) returned by the app service with the URI (scheme) of the "old" Airlock 2FA.

A URI or Uniform Resource Identifier helps identify a resource or location without ambiguity. A URI scheme refers to a specific URI format, used to specifically identify a group of resources or locations. Some examples of URI schemes are the https URI scheme or the file URI scheme.
In the context here, the URI scheme refers to the scheme of the mobile authentication URI. It determines which app to open on the mobile device for authentication. For example, the URI scheme airlock2fa refers to the Airlock 2FA app.

0. To configure the flow, proceed as follows:
1. Go to:
   Loginapp >> Applications and Authentication >> <Your old business app> >> Authentication Flow
2. In section Basic Settings in the Steps list, edit the Airlock 2FA Mobile Only Authentication Step plugin:
1. Go to the property Scheme Override in section Advanced Settings.
2. Enter airlock2fa, the URI scheme of the old 2FA app in the property field. This is necessary to replace the One App URI scheme, which is returned by the app service by default.
3. Activate your configuration.
4. The end-user can still use the old business app/2FA app to log in and authenticate.

Flow 3: Login via browser to the business application

This flow represents the use case where the end-user logs in to the business application via the browser and decides to migrate to the new One App, as a reaction to a prompt during login.

To facilitate a smooth migration process, the prompt to migrate should also include a hint to download the app.

In this browser-login use case, the user is prompted to migrate as long as they have not activated the new One App on any of their mobile devices, and the migrated flag is not set. If the flag is set or if the user decides to ignore the prompt, the current browser-login procedure will be completed - no migration to the new One App will take place.

Instead of only prompting the user when the migrated flag is not set, you may want to prompt the user every time they log in with the browser. Or you may not want to prompt the users at all. It is up to you how to configure this.

• Possible options
• Prompt upon each browser login:
• Use the flow described here, but without the migrated flag and corresponding Set Context Data Step plugin. To configure this use case, follow the instructions below.
• Use the current, "old" authentication flow, but add a prompt upon login to download and activate the new One App.
• For details on configuring the prompt itself, see Adapting the text in the login UI (prompts).
• No prompt at all:
  In this case, you can continue using the current, "old" authentication flow without any modifications. If you still want to inform the end-users about the new One App, use any other form of communication (email, activation letter with QR code).

0. To configure the flow, proceed as follows:
1. Go to:
   Loginapp >> Applications and Authentication >> <Your browser-login application> >> Authentication Flow
2. In section Basic Settings in the Steps list, create or edit the Migration Selection Step plugin. This plugin should come after the Airlock 2FA Authentication Step plugin.
3. In section Basic Settings of the Migration Selection Step plugin, create and edit a new Advanced Migration Selection Option plugin. For a detailed description of the plugin's configuration, see steps 5d, 5e, and 5f of section Flow 1A: Migration to the new One App - Mobile-only authentication above. Important: In step 5e, add the Airlock 2FA Activation (with additional activation) Step plugin (instead of the Airlock 2FA Activation Step plugin)!
4. Activate your configuration.
5. You have now configured an authentication flow that migrates an end-user during the browser login procedure to the new business app with built-in 2FA authentication. This use case deletes the token used for authentication when logging in to the browser.

The flows described above include several prompts to migrate to and activate the new One App solution. The prompt text appears in a separate window during the login processes. The 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.

• Internal links:
• Using multiple apps in one service
• Mobile-only authentication (app-to-app or SDK)
• Customizing Loginapp UI texts and changing translations with the Loginapp Design Kit