Transaction approval with Airlock 2FA

The following example illustrates the transaction approval of an e-banking system that uses Airlock IAM for authentication and transaction approval with Airlock 2FA.

The offline QR code and the mobile-only variants are not shown in this example.

Flow diagram

Airlock2FA-TransactionApproval
(1)
  • User authentication and identity propagation:
  • The user authenticates with Airlock 2FA.
  • The AuthTokenID is sent to the e-banking application as part of the identity propagation.
  • The e-banking application stores the AuthTokenID in its session. It is used to select the appropriate Airlock 2FA token during transaction approval.
(2)
  • Transaction approval decision:
  • The user interacts with the e-banking application and starts a transaction (e.g. enters a payment).
  • The e-banking application decides that approval is necessary for the transaction and thus starts the transaction approval process.
(3)
  • Selection of transaction approval flow
  • The e-banking application decides which IAM transaction approval flow to use.
(4)
  • User identifying step:
  • The e-banking application calls the Airlock IAM transaction approval REST API and identifies the end-user.
  • If the user is valid and not locked, Airlock IAM asks the e-banking application to provide transaction data to be verified.
(5)
  • Parameter Step:
  • The e-banking application sends transaction data to Airlock IAM. It also sends the AuthTokenID (optional).
  • If no AuthTokenID is sent, Airlock IAM will ask the e-banking application to select one of several available Airlock 2FA tokens (not shown in the diagram).
  • IAM verifies the transaction data and asks the e-banking application to poll for the result.
(6)
  • Approval step:
  • Airlock IAM formats the transaction data using the configured message provider.
  • Airlock IAM sends the transaction data via the Futurae cloud to the user's smartphone (Airlock 2FA app).
  • The e-banking application starts polling for the result.
  • The user verifies the transaction data on the smartphone and presses the Approve button.
  • Airlock IAM gets the result from the Futurae cloud and returns the OK to the e-banking application.

During step (5), the e-banking application may choose to show a QR code and accept an OTP code entered by the user (offline scenario). For simplicity, this is not shown in the diagram.

Configuration

The configuration is the same as in mTAN example except that the last step is an Airlock 2FA step:

TransactionApprovalConigScreenshot

REST call sequence

The following REST call sequence shows how to use the transaction approval API from a REST client's point of view.

  • For simplicity, in this example:
  • authentication information (e.g. Basic Auth header) and other HTTP headers are not shown.
  • the user's Airlock 2FA app is online and therefore capable to do One-Touch.

REST interaction 1 – Step 3 in the above diagram:

HTTP Request - Flow selection

POST https://internal-iam-host.com/auth-transaction-approval/rest/transaction-approval/flows/my-flow-1/select

HTTP Response - User identification required after flow selection

HTTP/1.1 200 OK

{
    "meta": {
        "type": "jsonapi.metadata.document",
        "timestamp": "2022-07-17T11:05:10.408+01:00"
    },
    "data": {
        "type": "transaction-approval.session",
        "id": "121849797510425576",
        "attributes": {
            "nextStep": "USERNAME_REQUIRED"
        }
    }
}

REST interaction 2 - Step 4 in the above diagram:

HTTP Request - User identifying step

POST https://internal-iam-host.com/auth-transaction-approval/rest/transaction-approval/user/identify/
{
    "username" : "jdoe"
}

HTTP Response - User identifying step

HTTP/1.1 200 OK

{
    "meta": {
        "type": "jsonapi.metadata.document",
        "timestamp": "2020-03-17T11:05:12.408+01:00"
    },
    "data": {
        "type": "transaction-approval.session",
        "id": "121849797510425576",
        "attributes": {
            "nextStep": "PARAMETERS_REQUIRED"
        }
    }
}

REST interaction 3 - Step 5 in the above diagram:

HTTP Request - Send transaction details

POST https://internal-iam-host.com/auth-transaction-approval/rest/transaction-approval/parameters/
{
    "authTokenId" : "123456abcdef", 
    "messageParameters" : 
    {
    	"accountNumber" : "0123456",
    	"amount" : "9999",
    	"currency" : "CHF"
    }
}

HTTP Response - Send transaction details

HTTP/1.1 200 OK

{
    "meta": {
        "type": "jsonapi.metadata.document",
        "timestamp": "2020-03-17T11:05:15.185+01:00"
    },
    "data": {
        "type": "transaction-approval.session",
        "id": "121849797510425576",
        "attributes": {
            "nextStep": "AIRLOCK_2FA_POLLING_OR_OTP_REQUIRED"
        }
    }
}

At this point, polling for the result (approval or denying) starts.

REST interaction 4 - Step 6 in the above diagram:

HTTP Request - Polling in approval step

POST https://internal-iam-host.com/auth-transaction-approval/rest/transaction-approval/airlock-2fa/status/poll/

HTTP Response - Polling in approval step

HTTP/1.1 200 OK

{
    "meta": {
        "type": "jsonapi.metadata.document",
        "timestamp": "2020-03-17T11:05:19.251+01:00"
    },
    "data": {
        "type": "transaction-approval.session",
        "id": "121849797510425576",
        "attributes": {
            "nextStep": "AIRLOCK_2FA_POLLING_OR_OTP_REQUIRED"
        }
    }
}

The system keeps polling until approved or denied.