← Back to plugin index

Matrixcard Authenticator (TAN Challenge)
Description
Authenticator based on the tan service interface TanService.

This authenticator always authenticates in two steps:
In the first call a UserCredentail is expected. If the user exists and the account is active, a AuthenticationFailedChallenge or a AuthenticationFailedToken response is returned.
In the second step, the answer to the challenge is expected: The credential instance must be of type ChallengeResponseCredential.

This authenticator takes its authentication decisions by calling the configured tan service.

The plugin writes the canonical class name description of this plugin to the context data container. The class name is stored under the key authPluginClassName . A short description of this authentication method is stored under the key authMethodShortDesc. This information may be used by callers.

Type name
MatrixcardAuthenticator
Class
com.airlock.iam.core.misc.impl.authen.MatrixcardAuthenticator
May be used by
Administrators Configuration Meta Authenticator Meta Authenticator Meta Authenticator Persister Password Service Authenticator-based One-Shot Target Application User to Authenticator Mapping Authentication Method Identifier Mapping Fallback Authenticator Selection Authenticator Main Authenticator Auth Method-based Authenticator Selector Credential-based Authenticator Selector Credential to Authenticator Mapping Radius Authentication Service Roles-to-Authenticator Mapping Role-based Authenticator Selector User-based Authenticator Selector
License-Tags
Matrixcard
Properties
TAN Service (tanService)
Description
The TAN service to be used.
Attributes
Plugin-Link
Mandatory
Assignable plugins
Default TAN Service
TAN List Type (tanListType)
Description
The type of the TAN list to be used. It is one of the following:
  • INDEXED_LIST: A token list with an index next to each token. The tokens are queried in random order.
  • MATRIX_CARD: A matrix card with the tokens organized in rows and columns. The tokens are queried in random order.
  • TOKEN_LIST: (not recommended) A normal token list that is processed from left to right (or top to bottom, depending on used token list renderer). There are no indices on the list.
Attributes
Enum
Mandatory
Token List Renderer (tokenListRenderer)
Description
Tells the authenticator which token list renderer has been used for producing the matrix card. This is needed for the translation of internal indices to challenge coordinates.
This property is only required if TAN List Type is set to MATRIX_CARD.
Attributes
Plugin-Link
Optional
Assignable plugins
Dummy Token List Renderer Text File Token List Renderer Word Template Token List Renderer
Start Index (startIndex)
Description
If indexed token lists (see configuration property "TAN List Type") are used, this property defines the lowest index. Usually the start index is zero or one (default).
If the "TAN List Type" is not INDEXED_LIST, this property is ignored.
Attributes
Integer
Optional
Default value
1
Challenge Validity Millis (responseValidityMillis)
Description
The number of milliseconds a response or token is valid for. If the token is entered correctly but after its expiration, authentication will fail. (TOKEN_EXPIRED).

The value 0 (zero) disables this feature, i.e. tokens never expire (this is the default).

Attributes
Integer
Optional
Default value
0
Max Retries (maxRetries)
Description
The number of times the user may enter a wrong response or token before the authentication process is aborted (and the token gets useless). If set to zero (the default), only one attempt is possible.
Attributes
Integer
Optional
Default value
0
New Challenge On Retry (newChallengeOnRetry)
Description
If maxRetries is set to a value bigger than 0, this property specifies if a new challenge is generated for the retry.
Attributes
Boolean
Optional
Default value
true
Count Unanswered Challenges (countUnansweredChallenges)
Description

If enabled, any pending challenge that is abandoned will be counted as an unanswered challenge. After too many unanswered challenges (see the "Max Unanswered Challenges" property), further attempts will always fail. This prevents an attacker from being able to "wait" for a specific challenge that has been leaked.

Important: This feature requires the fields 'Challenge Open Since' and 'Unanswered Challenges' on the Token List Persister to be configured, otherwise it will not work properly.

Attributes
Boolean
Optional
Default value
true
Unanswered Challenge Timeout [in Hours] (unansweredChallengeTimeout)
Description
When "Count Unanswered Challenges" is enabled, this property sets the timeout for unanswered challenges. When an unanswered challenge times out, the unanswered challenges counter is reset. Make sure to also configure the 'Challenge Open Since' and 'Unanswered Challenges' fields on the Token List Persister, otherwise this feature will not work properly.
Attributes
Integer
Optional
Default value
12
Max Unanswered Challenges (maxUnansweredChallenges)
Description
When "Count Unanswered Challenges" is enabled, this property sets the maximum number of unanswered challenges. Once this limit is exceeded, authentication will always fail.
Attributes
Integer
Optional
Default value
3
YAML Template (with default values) 

type: MatrixcardAuthenticator
id: MatrixcardAuthenticator-xxxxxx
displayName: 
comment: 
properties:
  countUnansweredChallenges: true
  maxRetries: 0
  maxUnansweredChallenges: 3
  newChallengeOnRetry: true
  responseValidityMillis: 0
  startIndex: 1
  tanListType:
  tanService:
  tokenListRenderer:
  unansweredChallengeTimeout: 12