Airlock 2FA Usernameless QR code login - REST flow example

Requirements

Component

Requirement

Comments

Airlock IAM

  • Airlock IAM 8.2 or newer.
  • Airlock 2FA app or other authenticator supporting usernameless QR login.
  • 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 the Usernameless QR code login as the first and only authentication factor.

Note that the app used to authenticate needs to be able to handle usernameless QR code login.

The Airlock 2FA App will be updated to support the feature. The release is expected in summer 2024.

If using a custom or white label app, ensure the used Futurae SDK supports usernameless QR login.

Note that usernameless QR code login always involves displaying and scanning a QR code. Therefore, two devices - one displaying the QR code and one scanning the QR code - are required.

Goal

  • Understand how to configure the Loginapp REST API for usernameless QR code authentication.
  • Understand how to use the Loginapp REST API for usernameless QR code authentication using an example.

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

Prerequisites

  • User account exists in IAM.
  • The user has Airlock 2FA enabled as a possible authentication method.
  • The authenticator app supports Usernameless QR code login.
  • The user has installed an authenticator app supporting usernameless QR code authentication.
  • The user's smartphone is connected to the internet and is able to connect to the Futurae cloud.
  • The basic Airlock 2FA settings exist.

Configuration

  1. Go to:

    2. Loginapp >> Applications and Authentication >> Default Application >> Authentication Flow

  2. Add the plugin Airlock 2FA Usernameless QR Code Authentication Step as the first step.
  3. Ensure the Airlock 2FA Settings are connected in the step and configured corresponding to the preconditions listed above.
  4. Activate the configuration.
  5. The REST authentication API is now ready to use.

QR code validity, QR code renewal, and internal goto target

Note that further configuration options exist in the Airlock 2FA Usernameless QR Code Authentication Step.

The QR code shown in the web browser is refreshed for security reasons from time to time. It is possible to configure an overall timeout by specifying the maximum number of QR code refreshes to display.

After the overall timeout, the browser can be redirected to another step by configuring an internal goto target. Like this, a message or an alternative way to authenticate may be displayed to the user.

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 – Start the authentication flow

The following request starts the authentication flow:

POST /auth/rest/public/authentication/applications/default-application/access

The response tells the client to poll for the usernameless login result. The response also contains a QR code image (base-64 encoded).

HTTP/1.1 401 Unauthorized
{
    "meta": {
        "type": "jsonapi.metadata.document",
        "timestamp": "2024-02-22T17:20:01.541+01:00",
        "challengeImage": "iVBORw0KGgoAAAANS...YII=",
        "nextAuthStep": "AIRLOCK_2FA_USERNAMELESS_POLLING_REQUIRED"
    },
    "errors": [
        {
            "id": "5569:6715",
            "status": 401,
            "code": "NOT_AUTHORIZED"
        }
    ]
}

Step 2 – Poll for Airlock 2FA authentication status

Next, the client starts polling for the authentication status. We expect the user to scan the QR code with the mobile app (e.g. Airlock 2FA app) and just wait for the result.

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": "2024-02-22T17:20:03.866+01:00"
    },
    "data": {
        "type": "authentication.session",
        "id": "af49663eb80882999d7b8c600e928808",
        "attributes": {
            "nextAuthStep": "AIRLOCK_2FA_USERNAMELESS_POLLING_REQUIRED",
            "challengeImage": "iVBORw0KGgoA...CYII="
        }
    }
}

Note that the QR code image may have changed.

If the user accepts the login request on the mobile app, the session is authenticated:

HTTP/1.1 200 OK
{
    "meta": {
        "type": "jsonapi.metadata.document",
        "timestamp": "2024-02-23T15:06:03.914+01:00"
    },
    "data": {
        "type": "authentication.session",
        "id": "544903050646076858",
        "attributes": {}
    }
}

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

HTTP/1.1. 403 Forbidden
{
    "meta": {
        "type": "jsonapi.metadata.document",
        "timestamp": "2024-02-23T15:13:12.106+01:00",
        "temporaryLockExpiry": "2024-02-23T15:13:18.102+01:00"
    },
    "errors": [
        {
            "id": "2106:5870",
            "status": 403,
            "code": "AUTHENTICATION_FAILED"
        }
    ]
}