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

Requirements

Component

Requirement

Comments

Airlock IAM

  • Airlock IAM 7.3 or newer.
  • An Airlock 2FA subscription is required.

For licensing:
Contact order@airlock.com.

Intended solution environment

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.

Goal

  • 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.

Prerequisites

  • 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.

Configuration

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

    2. 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.

Step 1 - Check username and password

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"
        }
    }
}

Step 2 - Get selectable devices

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"
            }
        }
    ]
}

Step 3 - Select the device (hardware token)

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"
        }
    }
}

Step 4 - Get QR code challenge

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..."
        }
    }
}

Step 5 - Check OTP (response to challenge)

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": {}
    }
}