Airlock 2FA passcode - REST flow example

This example shows how to configure and use the REST authentication flow for authentication with:

1. Username and password as the first factor.
2. Switch to Airlock 2FA offline mode
3. Check Passcode (time-based OTP)

• Understand how switching to the offline mode works using the Loginapp REST API
• Understand how to check an Airlock 2FA Passcode using the Loginapp REST API
• Understand how to configure Airlock IAM for the described use-cases.

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

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

• The user has Airlock 2FA enabled as a possible authentication method.

• One-Touch is enabled in the Airlock 2FA configuration.

• Passcode authentication is enabled in the Airlock 2FA configuration.

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

• The user's smartphone is connected to the internet and is able to connect to the Futurae cloud.

• The basic Airlock 2FA settings exist.

• The user has only one Airlock 2FA token (no device selection).

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

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 Airlock 2FA Step for Authentication as the second step.
4. Make sure the Airlock 2FA Settings are connected within the second step and that it is configured corresponding to the preconditions listed below.
5. Activate the configuration.
6. The REST authentication API is now ready to use.

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 username and password are checked:

POST /rest/public/authentication/password/check/
{
    "username" : "jdoe",
    "password" : "password1"
}

If the first authentication step succeeds, the second authentication step is initiated. The Airlock 2FA Step for Authentication starts with One-Touch authentication. This involves sending a push message to the user's smartphone and asking the user to approve. The REST client may now ask the REST API whether the user has decided yet and, if so, whether it approved or declined the authentication request.

In its response, the REST API, therefore, asks the client to continue with Airlock 2FA requests.

HTTP/1.1 200 OK
 
{
    "meta": {
        "type": "jsonapi.metadata.document",
        "timestamp": "2020-08-24T09:55:50.147+02:00"
    },
    "data": {
        "type": "authentication.session",
        "id": "481548987284754648",
        "attributes": {
            "nextAuthStep": "AIRLOCK_2FA_POLLING_OR_OFFLINE_REQUIRED"
        }
    }
}

Because One-Touch, as well as Passcode authentication, are both enabled in the IAM configuration (and supported by the used app), the REST client is given the option to continue with polling for the One-Touch result or with switching to the offline mode (enter Passcode).

In this example, we continue with switching to offline mode (Passcode authentication) by sending the following request:

POST /rest/public/authentication/airlock-2fa/offline/

The response indicates that a Passcode or QR code OTP is expected:

HTTP/1.1 200 OK

{
    "meta": {
        "type": "jsonapi.metadata.document",
        "timestamp": "2020-08-24T10:06:39.054+02:00"
    },
    "data": {
        "type": "authentication.session",
        "id": "481548987284754648",
        "attributes": {
            "nextAuthStep": "AIRLOCK_2FA_PASSCODE_OR_QR_CODE_OTP_REQUIRED"
        }
    }
}

In IAM version 7.3, the only supported offline factor in the Airlock 2FA app is Passcode. Offline QR code authentication is only supported for hardware tokens but may also be supported in the app in later releases.

To check the Passcode - a time-based OTP code - shown in the app, the following request is used:

POST /rest/public/authentication/airlock-2fa/passcode/check/

If correct, the authentication process successfully ends with

HTTP/1.1 200 OK

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

• Passcode authentication
• Basic configuration settings
• Airlock 2FA configuration hints