Airlock 2FA One-Touch login - 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 authentication with:

  1. Username and password as the first factor.
  2. Airlock 2FA One-Touch as second factor.

Goal

  • Understand how to configure the Loginapp REST API for One-Touch authentication.
  • Understand how to use the Loginapp REST API for One-Touch authentication using an example.

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

Configuration

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

Step 2 - Poll for Airlock 2FA authentication status

In this example, we continue with polling (One-Touch). Polling is done with the following request:

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

If the user has not yet approved or declined on the smartphone app, the response is (again).

HTTP/1.1 200 OK

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

If the user approves the authentication request, the authentication flow successfully ends.

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

If the user declines the request, the result would instead be:

HTTP/1.1. 403 Forbidden
 
{
    "meta": {
        "type": "jsonapi.metadata.document",
        "timestamp": "2020-08-28T12:11:54.608+02:00",
        "temporaryLockExpiry": "2020-08-28T12:12:00.422+02:00"
    },
    "errors": [
        {
            "id": "4608:0198",
            "status": 403,
            "code": "AUTHENTICATION_FAILED"
        }
    ]
}