Selection of authentication token and authTokenId usage

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:

  1. A user may have both an MTAN/SMS token and a Cronto token
  2. A user may have multiple MTAN/SMS tokens or multiple Cronto tokens

There are two strategies to determine which token to use: selection-based and authTokenId-based.

Selection-based token choice

In this strategy, the delegating entity (e.g., the 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.

Technically, the token choice may have two origins:

  1. Within a step implementation (e.g., the mTAN Authentication step may ask which phone number to use).
  2. 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:

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

 
Terminal box
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 not want to select the correct token itself nor let the user choose it. Instead, it expects IAM to reuse the same token for transaction approval that was used during login.

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 back-ends (e.g., the e-banking system) via identity propagation.
  • The authTokenId must be retained for the entire session, until the end-user logs out. How you choose to store the token is up to you.
    • Note that the authTokenId will never exceed 500 characters.
  • 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 the case for Airlock 2FA, mTAN, Cronto tokens, and Email OTP.
 
Notice

Using the authTokenID in identity propagation

To send the authTokenId to the protected applications in the back-end after login, configure the identity propagator plugin as follows:

  • Select the Authentication Data Map value provider. Use auth-token-id as the key to reference the authTokenId.
  • Store the authTokenId in the identity propagation token under a name of your choice (e.g., authTokenId). The receiving system (e.g., the e-banking-system) must be configured to recognize this name in order to extract the authTokenId.

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

 
Terminal box
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:

 
Info

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).