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.
- ●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
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.
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
POST https://internal-iam-host.com/auth-transaction-approval/rest/transaction-approval/user/identify/ { "username" : "jdoe" }
Step 1 - HTTP Response - User identifying step
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
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
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
POST https://internal-iam-host.com/auth-transaction-approval/rest/transaction-approval/mtan/otp/check { "otp" : "123456" }
Step 3 - HTTP Response - Check OTP
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": {} } }