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:
- A user may have both an MTAN/SMS token and a Cronto token
- 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:
- Within a step implementation (e.g., the mTAN Authentication step may ask which phone number to use).
- 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):
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.
- Note that the
- 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.
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 theauthTokenId
. - 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 theauthTokenId
.
The authTokenId
is subsequently sent to the transaction approval interface in the parameter step as shown in the following example:
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:
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).