Airlock 2FA hardware token and device selection - REST flow example

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

1. Username and password as the first factor.
2. Airlock 2FA device selection
3. Hardware token (offline QR code) authentication

It shows both device selection and hardware token login.

• Understand how to configure and use the Loginapp REST API for hardware token login.
• Understand how to configure and use the Loginapp REST API for the device selection.

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.

• Offline QR code login is enabled in the Airlock 2FA configuration.

• The user has a QR code reader (hardware token).

• The basic Airlock 2FA settings exist.

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

1. Go to:

Loginapp >> Applications and Authentication >> 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. Since the user has more than one device, the Airlock 2FA Step for Authentication asks to select the device in the response:

HTTP/1.1 200 OK

 {
    "meta": {
        "type": "jsonapi.metadata.document",
        "timestamp": "2020-08-24T17:14:13.100+02:00"
    },
    "data": {
        "type": "authentication.session",
        "id": "108266430294427818",
        "attributes": {
            "nextAuthStep": "AIRLOCK_2FA_DEVICE_CHOICE_REQUIRED"
        }
    }
}

To get information about available devices, the following request can be used:

POST /rest/public/authentication/airlock-2fa/devices/retrieve/

In our example, it's response lists the user's smartphone and a hardware token:

HTTP/1.1 200 OK

{
    "meta": {
        "type": "jsonapi.metadata.document",
        "timestamp": "2020-08-24T09:54:34.742+02:00"
    },
    "data": [
        {
            "type": "authentication.airlock-2fa.device",
            "id": "86cb1f74-5f1d-43e3-8937-d41e0dbacabd",
            "attributes": {
                "displayName": "Joe's iPhone",
                "deviceType": "IOS"
            }
        },
        {
            "type": "authentication.airlock-2fa.device",
            "id": "6652400b-598b-442f-b90e-990295a78d9c",
            "attributes": {
                "displayName": "GAQT12345678",
                "deviceType": "HWTOKEN"
            }
        }
    ]
} 

To select the hardware token, use its token id with the following request:

POST /rest/public/authentication/airlock-2fa/devices/6652400b-598b-442f-b90e-990295a78d9c/select/

Since a hardware token has been selected, the REST API asks for a QR code OTP code:

HTTP/1.1 200 OK

{
    "meta": {
        "type": "jsonapi.metadata.document",
        "timestamp": "2020-08-24T09:55:50.147+02:00"
    },
    "data": {
        "type": "authentication.session",
        "id": "108266430294427818",
        "attributes": {
            "nextAuthStep": "AIRLOCK_2FA_QR_CODE_OTP_REQUIRED"
        }
    }
}
 

In the next step, the REST client gets a QR code challenge from the REST API by sending the following request:

POST /rest/public/authentication/airlock-2fa/offline-qr-code/challenge/retrieve/

The response bears a QR code image (base-64 encoded PNG) that has to be scanned by the user using the hardware token (the base-64 image string has been truncated in the example response).

HTTP/1.1 200 OK

{
    "meta": {
        "type": "jsonapi.metadata.document",
        "timestamp": "2020-08-24T09:57:08.515+02:00"
    },
    "data": {
        "type": "authentication.airlock-2fa.offline-qr-code.challenge",
        "id": "2727441580",
        "attributes": {
            "challengeImage": "iVBORw0KGgoAAAANSUhEUgAAAl..."
        }
    }
}

The hardware token computes an OTP code from the QR code challenge and the user enters the OTP code in the browser or app. To check the OTP code using the REST API, use the following request:

POST /rest/public/authentication/airlock-2fa/offline-qr-code/otp/check/
{
    "otp" : "123456" 
}  

If the code is correct, 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": {}
    }
}

• Offline QR code authentication
• Airlock 2FA Settings plugin – global shared Airlock 2FA configuration
• Airlock 2FA configuration hints