Transaction approval with mTAN (SMS)

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

Flow diagram

●
Authentication:

●
The user authenticates at Airlock IAM to access the e-banking system.
●
After successful authentication, the user ID is propagated to the e-banking system. This step may contain the AuthTokenId.

AuthTokenID

The "AuthTokenId" is string issued by the authentication process. It is used later during transaction approval in order to identify the token that has been used during authentication (relevant if a user has multiple tokens to authenticate with).
When using the "AuthTokenId", the authentication token used during the login process is automatically selected.

●
Transaction approval:

●
The e-banking decides that a transaction needs to be verified
●
Step 1: Start transaction approval by identifying the user to IAM
●
Step 2: Send transaction details to the IAM transaction approval REST API
●
IAM sends an SMS with transaction details and an OTP code to the user
●
e-banking asks the user to enter the OTP code to approve the transaction
●
Step 3: e-banking sends OTP code to IAM for verification

Configuration

The behavior and steps involved in the process can be configured as a "flow", similar to the authentication flows in the Loginapp.

As described above the transaction approval process usually consists of 3 steps:

●
Step 1: (identify the user to IAM)
●
Step 2: (send transaction details to IAM)
●
Step 3: Approval step (e.g. verify the OTP code)

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

Rest call sequence

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

To keep the example simple and readable:

●
authentication information (e.g. Basic Auth header) and other HTTP headers are not shown.
●
an AuthTokenId is not used in this example
●
the user has just one mobile phone number - therefore no number selection step is shown

Step 1 - HTTP Request - User identifying step

copy

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

Step 1 - HTTP Response - User identifying step

copy

HTTP/1.1 200 OK

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

Step 2 - HTTP Request - Send transaction details

copy

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

Step 2 - HTTP Response - Sendtransaction details

copy

HTTP/1.1 200 OK

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

Step 3 - HTTP Request - Check OTP

copy

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

Step 3 - HTTP Response - Check OTP

copy

HTTP/1.1 200 OK

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

Further information and links

●
Transaction Approval REST API Reference