Airlock 2FA token migration - REST flow example

This example shows how to configure and use the REST authentication flow to activate a new Airlock 2FA token during the login process. The main use case is token migration, i.e. migrating from another second factor to Airlock 2FA by the end-user.

The flow shown in this example is as follows:

1. Strong user authentication (e.g. using mTAN or Cronto)
2. Ask end-user to migrate to Airlock 2FA
3. Airlock 2FA activation / enrollment step
4. Change device display name

• Understand how to configure and use token migration in the Loginapp REST API
• Understand how to activate an Airlock 2FA token during authentication in the Loginapp REST API
• Understand how to use the Loginapp REST API to change the device name of an Airlock 2FA device.

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

Note that the token migration flow can be tailored by configuration: it offers various options to force users to migrate, to let users skip migration, and to grant users a migration grace period. Please refer to the plugin's documentation in the Config Editor for further information.

In the following example, the user is both allowed to skip and reject migration.

• User account exists in IAM and users can be authenticated (e.g. username, password, and mTAN).

• The user has installed the Airlock 2FA app on the smartphone.

• The Airlock 2FA app has access to the smartphone's microphone.

• The basic Airlock 2FA settings exist.

• There is no enrolled Airlock 2FA token on the smartphone for used Futurae service.
• The user's current authentication method is mTAN/SMS.
• The user's next authentication method is Airlock 2FA.

1. Go to:

Loginapp >> Authentication Flows >> Default Application >> Authentication Flow

2. Add the plugin Username Password Authentication Step as the first step.
3. Add the plugin mTAN Authentication Step as the second step
4. Add the plugin Migration Selection Step as the third step and configure it as follows.
5. To the list of Available Options, add the plugin Default Migration Selection Option and configure it with the two steps Airlock 2FA Activation Step and Airlock 2FA Device Edit Step


Make sure, that the user has been authenticated in a strong way before activating Airlock 2FA. To do so make sure that the Airlock 2FA Activation Step ensures this by requiring a corresponding tag in the list of Pre Condition Tags (e.g. require the mTAN verified tag).

6. The REST authentication API is now ready to use.

• User account exists in IAM and has a first factor (e.g. username and password).

For simplicity, the configuration instructions and usage examples are given for the default application within the Loginapp REST API's Authentication Flows settings. Therefore, no application selection REST calls are shown.

First, the user is authenticated with username, password, and mTAN/SMS. The REST call sequence is as in the mTAN example given on Usage examples of REST authentication API.

In this case, instead of the final response of the mTAN example, the REST API asks the user to migrate by returning the following response:

HTTP/1.1 200 OK

{
    "meta": {
        "type": "jsonapi.metadata.document",
        "timestamp": "2020-08-24T10:09:49.190+02:00"
    },
    "data": {
        "type": "authentication.session",
        "id": "486984513816256656",
        "attributes": {
            "nextAuthStep": "MIGRATION_SELECTION_REQUIRED"
        }
    }
}

The REST client can then retrieve the possible migration options using the following request.

POST /rest/public/authentication/migration/options/retrieve/

In our example, there is only one option: migration to Airlock 2FA. The response also informs about migration modalities (skippable, rejectable, due-date, etc.).

HTTP/1.1 200 OK

{
    "meta": {
        "type": "jsonapi.metadata.document",
        "timestamp": "2020-08-24T10:11:21.235+02:00",
        "migrationInfo": {
            "rejectPossible": true,
            "skipPossible": true
        }
    },
    "data": [
        {
            "type": "authentication.migration.option",
            "id": "AIRLOCK_2FA",
            "attributes": {}
        }
    ]
}

With the last response, IAM also informs the client how token migration is configured and if skipping or rejecting the migration is permitted or not. In our example, IAM allows skipping and rejecting the migration and the client could present these options to the user. Depending on the user's decision the client uses one of the following calls to the REST API:

In this example, we continue with the migration. To initiate it the client sends the select request as follows:

POST /rest/public/authentication/migration/options/AIRLOCK_2FA/select/

The response informs the client on how to proceed with migration. It is the first response of the Airlock 2FA Activation Step.

HTTP/1.1 200 OK

{
    "meta": {
        "type": "jsonapi.metadata.document",
        "timestamp": "2020-08-24T10:12:43.367+02:00"
    },
    "data": {
        "type": "authentication.session",
        "id": "486984513816256656",
        "attributes": {
            "nextAuthStep": "AIRLOCK_2FA_DEVICE_ACTIVATION_REQUIRED"
        }
    }
}

To enroll the Airlock 2FA app, an activation challenge needs to be retrieved using the following request:

POST /rest/public/authentication/airlock-2fa/activation/challenge/retrieve/

The response contains the challenge in two formats as shown in the response example (both the device activation URLvand the activation QR code are truncated):

HTTP/1.1 200 OK

{
    "meta": {
        "type": "jsonapi.metadata.document",
        "timestamp": "2020-08-24T10:16:40.979+02:00"
    },
    "data": {
        "type": "authentication.airlock-2fa.activation.challenge",
        "id": "3480926142",
        "attributes": {
            "appDeviceActivationUrl": "airlock2fa://enroll?activation_code=cWgzRmNpaXQxZm...",
            "activationQrCode": "iVBORw0KGgoAAAANSUhEUgAA..."
        }
    }
}

Either the activationQrCode is scanned by the user with the Airlock 2FA app or the activation_code from the appDeviceActivationUrl is processed by the app or the SDK. In both cases, the app directly communicates with the Futurae cloud in order to enroll the device.

The REST client may ask IAM whether the activation has finished and whether it was successful by repeatedly using the following request:

POST /rest/public/authentication/airlock-2fa/activation/status/poll/

After successful device activation, the response is:

HTTP/1.1 200 OK

{
    "meta": {
        "type": "jsonapi.metadata.document",
        "timestamp": "2020-08-24T10:23:18.441+02:00"
    },
    "data": {
        "type": "authentication.session",
        "id": "486984513816256656",
        "attributes": {
            "nextAuthStep": "AIRLOCK_2FA_DEVICE_EDIT_POSSIBLE"
        }
    }
}

Because we added the Airlock 2FA Device Edit Step to the activation flow, the response informs the client that device display name change is possible.

To get the current device display name, use the following request:

POST /rest/public/authentication/airlock-2fa/activation/device-edit/data/retrieve/

The response in our example is:

HTTP/1.1 200 OK

{
    "meta": {
        "type": "jsonapi.metadata.document",
        "timestamp": "2020-08-24T10:23:57.401+02:00"
    },
    "data": {
        "type": "authentication.airlock-2fa.device.data",
        "id": "2437b657-57fd-4c5c-8334-9c515421701f",
        "attributes": {
            "displayName": "John Doe's iPhone X"
        }
    }
} 

The display name is shown in the IAM user management and to the user during device selection and helps the user to select the correct device.

Assuming that the user wishes to change the device display name, the following REST API interaction is required. If no device display name change is required, directly go to the continue call.

POST /rest/public/authentication/airlock-2fa/activation/device-edit/data/
{
    "displayName" : "Joe's private phone"
}

IAM responds with:

HTTP/1.1 200 OK

{
    "meta": {
        "type": "jsonapi.metadata.document",
        "timestamp": "2020-08-24T10:25:20.591+02:00"
    },
    "data": {
        "type": "authentication.session",
        "id": "486984513816256656",
        "attributes": {
            "nextAuthStep": "AIRLOCK_2FA_DEVICE_EDIT_POSSIBLE"
        }
    }
}
 

It means that IAM accepted the change and is ready for more changes. In general, configuration might allow for more changes (other steps) or validation steps.

In our example, the device name is the only attribute that can be edited. The REST client, therefore, tells IAM to continue by sending the following request:

POST /rest/public/authentication/airlock-2fa/activation/device-edit/continue/

If the new device name could be processed and stored, the authentication flow successfully ends with the response:

HTTP/1.1 200 OK

{
    "meta": {
        "type": "jsonapi.metadata.document",
        "timestamp": "2020-08-24T10:08:25.196+02:00"
    },
    "data": {
        "type": "authentication.session",
        "id": "108266430294427818",
        "attributes": {}
    }
}

• Token migration self-service
• Basic configuration settings
• Airlock 2FA configuration hints