Airlock 2FA Mobile-only (single device) authentication - 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 mobile-only (single device) authentication:

  1. Username and password as the first factor.
  2. Airlock 2FA mobile-only step as the second factor.

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

Goal

  • Understand how to configure the Loginapp REST API for mobile-only authentication.
  • Understand how to use the Loginapp REST API for mobile-only authentication.

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.
  • The REST authentication flow is configured to support mobile-only 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.
  • The Airlock 2FA app has been enrolled for the user's account.

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 Mobile Only Authentication Step as the second step.
  4. Activate the configuration.
  5. 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 API Settings. Therefore, no application selection REST calls are shown.

Step 1 - Check username and password

First, the username and password are checked:

Request:

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

If the first authentication step succeeds, the second authentication step - in our example the Airlock 2FA Mobile Only Authentication Step - is initiated. In its response, it asks the REST client to get a mobile-only challenge.

HTTP/1.1 200 OK

{
    "meta": {
        "type": "jsonapi.metadata.document",
        "timestamp": "2020-08-25T15:17:12.463+02:00"
    },
    "data": {
        "type": "authentication.session",
        "id": "722111127646085506",
        "attributes": {
            "nextAuthStep": "AIRLOCK_2FA_MOBILE_ONLY_CHALLENGE_RETRIEVAL_REQUIRED"
        }
    }
}

Step 2 - Get authentication challenge

The following request gets the challenge:

POST /rest/public/authentication/airlock-2fa/mobile-only/challenge/retrieve/

It returns a challenge as in response:

HTTP/1.1 200 OK

{
    "meta": {
        "type": "jsonapi.metadata.document",
        "timestamp": "2020-08-25T15:19:53.782+02:00"
    },
    "data": {
        "type": "authentication.airlock-2fa.mobile-only.challenge",
        "id": "534562829",
        "attributes": {
            "mobileAuthUri": "airlock2fa://auth?session_token=RClVS1rViqAmBrr0CYog-9gDAcZe2CDXG9bXAyovPOSk&user_id=f88d7cc1-d34d-4978-87f7-a038a9d4d5af"
        }
    }
}

The mobileAuthUri is a URI containing an authentication session token and a user ID. Both are either passed to the Airlock 2FA app using app-to-app communication or to the Futurae app SDK.

In both cases, the app directly communicates with the Futurae cloud to perform authentication.

Step 3 - Poll for authentication status

The REST client may repeatedly ask IAM whether the authentication has finished and whether it was successful.

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

As long as the authentication request is still pending, IAM will return:

HTTP/1.1 200 OK

{
    "meta": {
        "type": "jsonapi.metadata.document",
        "timestamp": "2020-08-25T15:38:02.070+02:00"
    },
    "data": {
        "type": "authentication.session",
        "id": "201723161354420478",
        "attributes": {
            "nextAuthStep": "AIRLOCK_2FA_POLLING_REQUIRED"
        }
    }
}

If the user approves the authentication request, the authentication flow 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": "201723161354420478",
        "attributes": {}
    }
}