Transaction approval with mTAN (SMS)

The following example illustrates the transaction approval of an e-banking system that uses Airlock IAM for authentication and transaction approval with mTAN (SMS).

Flow diagram

mTAN-TransactionApproval
(1)
  • User authentication and identity propagation:
  • The end-user authenticates over Airlock IAM.
  • 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 2nd factor (here: mTAN) during transaction approval.
(2)
  • Transaction approval decision by e-banking application:
  • The end-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 Airlock 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 end-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.
  • Airlock IAM verifies the transaction data and asks the e-banking system to send the OTP code.
(6)
  • Approval step:
  • Airlock IAM formats the transaction data using the configured message provider.
  • Airlock IAM sends the transaction data via SMS provider to the end-user's mobile/SMS receiver.
  • The end-user verifies the transaction data on the mobile/SMS receiver and enters the mTAN OTP into the browser of the e-banking application, to approve the transaction.
  • Airlock IAM verifies the OTP for the e-banking application.

Configuration

The behavior and steps involved in the process are configured in an Airlock IAM transaction approval flow, similar to the authentication flows in the Loginapp.

81008211.png
  1. As described above the transaction approval process usually consists of the following steps:
  2. REST selection request of the back-end application – this has to be configured on the corresponding back-end.
  3. The User Identification Step, to identify the end-user in IAM.
  4. The Transaction Approval Parameter Step, in which the back-end sends transaction details to IAM.
  5. The mTAN Transaction Approval Step, to verify the OTP code towards the corresponding back-end.

The configuration of this example (using MTAN/SMS) is as follows:

81008216.png

Rest call sequence

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

  • In this simplified example:
  • Authentication information (e.g. Basic Auth header) and other HTTP headers are not shown.
  • An AuthTokenId is not used in this example.
  • The end-user has just one mobile phone number - therefore no number selection step is shown.
Transaction-Approval-mTAN-Simple

According to the flow diagram above, the HTTP REST requests and responses are as follows:

Step

Request/response type

HTTP request/response

Step 1

HTTP request – Flow selection

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

HTTP response - Flow selection

HTTP/1.1 200 OK
  {
    "meta": {
        "type": "jsonapi.metadata.document",
        "timestamp": "2021-11-09T16:29:14.484+01:00"
    },
    "data": {
        "type": "transaction-approval.session",
        "id": "627374595",
        "attributes": {
            "nextStep": "USERNAME_REQUIRED"
        }
    }
}

Step 2

HTTP request – User identifying step

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

HTTP response – User identifying step

HTTP/1.1 200 OK

{
    "meta": {
        "type": "jsonapi.metadata.document",
        "timestamp": "2021-11-09T16:29:24.484+01:00"
    },
    "data": {
        "type": "transaction-approval.session",
        "id": "627374595",
        "attributes": {
            "nextStep": "PARAMETERS_REQUIRED"
        }
    }
}

Step 3

HTTP request – Send transaction details

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

HTTP response – Send transaction details

HTTP/1.1 200 OK

{
    "meta": {
        "type": "jsonapi.metadata.document",
        "timestamp": "2021-11-09T16:37:48.747+01:00"
    },
    "data": {
        "type": "transaction-approval.session",
        "id": "627374595",
        "attributes": {
            "nextStep": "MTAN_OTP_REQUIRED"
        }
    }
}

Step 4

HTTP Request - Check OTP

POST https://internal-iam-host.com/auth-transaction-approval/rest/transaction-approval/mtan/otp/check
{
    "otp" : "123456"
}

HTTP Response - Check OTP

HTTP/1.1 200 OK

{
    "meta": {
        "type": "jsonapi.metadata.document",
        "timestamp": "2021-11-09T16:41:29.829+01:00"
    },
    "data": {
        "type": "transaction-approval.session",
        "id": "202408261",
        "attributes": {}
    }
}