Selection of authentication token and authTokenId usage

  1. Depending on the user and the authentication tokens used for transaction approval, there may be more than one token to choose from the following examples:
  2. A user may have both an MTAN/SMS token and a Cronto token
  3. A user may have multiple MTAN/SMS tokens or multiple Cronto tokens

There are two strategies for how the token to be used can be determined: selection-based and authTokenId-based.

Selection-based token choice

In this strategy, the delegating entity (e.g. e-banking system) chooses the token. It may do so on its own or have the user choose the token. The latter requires that the delegating entity is interacting with the user at the time of transaction approval.

  1. Technically, the token choice may have two origins:
  2. Within a step implementation (e.g. the "mTAN Authentication" step may ask which phone number to use).
  3. Explicitly configured "Selection" Step (used to choose among several steps such as mTAN and Cronto).

The following configuration example shows the explicitly configured selection step:

81010237.png
81011502.png

Example REST response indicating that a selection is required (as a response to the parameter step):

copy
HTTP 200 OK
{
    "meta": {
        "type": "jsonapi.metadata.document",
        "timestamp": "2022-04-13T11:04:46.588+01:00"
    },
    "data": {
        "type": "transaction-approval.session",
        "id": "799681179",
        "attributes": {
            "nextStep": "SELECTION_REQUIRED"
        }
    }
}

authTokenId token choice

In most situations, the delegating entity (e.g. e-banking system) does neither want to choose the correct token nor have it chosen by the user. It expects IAM to use the same token for transaction approval that has been used during the login process.

  • In order to achieve this, the authTokenId must be passed to the transaction approval interface in the parameter step:
  • The authTokenId is produced during the login process (user authentication) in the IAM loginapp.
  • The authTokenId may be passed to the protected backends (e.g. e-banking system) in identity propagation
  • The delegating entity must have access to the authTokenId and pass it to the transaction approval interface
  • The authentication token (used during login) and the transaction approval step must both support the authTokenId. This is currently the case for Airlock 2FA, mTAN and Cronto tokens for Airlock IAM 7.7.

authTokenID in identity propagation

  • To send the authTokenId to the protected applications after login, the used identity propagator plugin must be configured accordingly:
  • As value reference use "AUTH_TOKEN_ID"
  • Store it in the ID propagation token using a name of your choice (e.g. "authTokenId"). The receiving system (e.g. e-banking-system) must know this name to extract the AuthTokenId.

The authTokenId is subsequently sent to the transaction approval interface in the parameter step 3 as in the following example:

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

In the transaction approval interface, the selection options must include a selection condition respecting the auth token ID parameter:

81010335.png

In a more realistic scenario, you might want to configure a logical AND condition that additionally checks whether or not the user has an mTAN token (as shown in the demo configuration).