TAN Batch Task
Description
This plug-in implements a task that is used in the TAN authentication server. It performs tasks, which are not triggered by user a user action (e.g. by a user attempting to log in) but must be done by a batch job regularly.
In order to understand the following task description, it is important to understand, that a user can have zero, one, or two token lists or matrix cards at the same time: The active token list is the one being used for authentication. The next token list is a new token list waiting to become active. It is generated some time before the current active token list expires so it can be sent to the user. The new token list becomes active, if the current token list expires or is removed. Depending on configuration, just using the new token list will also activate it.
When executed, this task looks at all users with the configured token list iterator plug-in and does the following tasks. The process is done only for active users returned by the token list iterator:
- Remove expired token lists or matrix cards.
- Remove empty token lists.
- If the user has no active list but a valid new token list, the new token list is made the active token list.
- Generate new token lists or new matrix cards where necessary. This is the case if at least one of the following conditions is true:
- If the current token list or matrix card of the user is about to expire and there is no "next token list".
- If there is no token list at all.
- If there is no "next token list" and the corresponding flag ("order new list flag") is set. - Newly generated token lists are rendered by calling the configured token list renderer.
May be used by
Properties
Token List Persister (
tokenListPersister) Description
The token list persister plugin used to read and store token list structures.
Attributes
Plugin-Link
Mandatory
Assignable plugins
Token List Iterator (
tokenListIterator) Description
The token list iterator plugin used to iterate over all token users. Usually this is the same as the token list persister.
Attributes
Plugin-Link
Mandatory
Assignable plugins
Maximum Validity Days (
maximumValidityDays) Description
Specifies the number of days a token list is valid after its generation. After the period has elapsed, the list can no longer be used and is replaced by the new token list (if there is any). If there is no new list, the list is deleted. If the value -1 is used, the token list does not expire.
Attributes
Integer
Optional
Default value
-1
Remaining Days Threshold (
remainingDaysThreshold) Description
If a list is about to expire, generates an event and/or sets the flag to generate a new list. This property specifies the number of remaining validity days that trigger this event.
The value is only relevant when the property maximum-validity-days is not -1.
The value is only relevant when the property maximum-validity-days is not -1.
Attributes
Integer
Optional
Delivery Security Gap (
deliverySecurityGap) Description
In order to avoid sending more than one credential to a user at the same time, this task inspects the delivery times of other credentials of the same user. The value of this property indicates the minimum number of days between the latest delivery of another token and the generation of a token list.
Setting this property to zero (0) disables this feature.
Setting this property to zero (0) disables this feature.
Attributes
Integer
Optional
Default value
0
Token Type Name (
tokenTypeName) Description
This property is used when new token lists are generated. The type of tokens (for new token list generation).
Attributes
String
Mandatory
Allowed values
DIGITS, DIGITS_CAPITAL_LETTERS, DIGITS_LETTERS
Token Length (
tokenLength) Description
This property is used when new token lists are generated. The length of each generated token (number of characters).
Attributes
Integer
Mandatory
Tokens Per List (
tokensPerList) Description
This property is used when new token lists are generated. The number of tokens in each generated list. Setting for standard matrix card (credit-card-format)
Attributes
Integer
Mandatory
Hash Function Plugin (
hashFunctionPlugin) Description
This property is used when new token lists are generated.
The hash function used to hash the generated tokens. It must be the same (or hash value compatible) as used when generating the token lists.
The hash function used to hash the generated tokens. It must be the same (or hash value compatible) as used when generating the token lists.
Attributes
Plugin-Link
Mandatory
Assignable plugins
AWS KMS Password Hash Argon2id Password Hash Bcrypt Password Hash Combined Password Hash Encrypted Password Hash History Password Hash Identity Password Hash LDAP Password Hash MD5 Base64 Password Hash MD5 Hex Password Hash Multi Password Hash (LDAP-style) Password Hash Configuration SHA1 Base64 Password Hash SHA1 Hex Password Hash SHA1 Password Hash SHA256 Base64 Password Hash SHA256 Hex Password Hash SHA256 Password Hash Scrypt Password Hash
Token List Renderer (
tokenListRenderer) Description
Tells the tan batch task which token list renderer to use for the rendering of newly generated token lists.
Attributes
Plugin-Link
Mandatory
Assignable plugins
Language Attribute Name (
languageAttributeName) Description
Tells the TAN batch task which attribute in the context data container contains the language to be used for rendering the password. If this property is configured and if the context data container of the user has a value for this attribute, it is used when calling the password renderer plugin.
If this property is not defined, the user's language is not taken into account when rendering token lists!
Attributes
String
Optional
Suggested values
language
Delete Old Token Lists (
deleteOldTokenLists) Description
Deletes old rendered token lists of a user from the file system when a new one is rendered. Setting this to TRUE results in at most one rendered token list per user.
If this property is set to TRUE, the plugin must have permission to delete files from the directory.
If this property is set to TRUE, the plugin must have permission to delete files from the directory.
Attributes
Boolean
Optional
Default value
false
Working Directory (
workingDirectory) Description
A writable directory used to store partial reports.
If this property is defined, the token lists are not directly generated into the output directory (see other property) but they are generated into this working directory and are moved to the output directory once they are done.
This helps to solve problems with processes automatically reading the rendered token lists and reading partial token lists during the generation process. Make sure that the working directory and the output directory reside in the same file system (if not the moving of the generated file will not be atomic).
The directory is either absolute or relative to the JVMs current directory.
If this property is defined, the token lists are not directly generated into the output directory (see other property) but they are generated into this working directory and are moved to the output directory once they are done.
This helps to solve problems with processes automatically reading the rendered token lists and reading partial token lists during the generation process. Make sure that the working directory and the output directory reside in the same file system (if not the moving of the generated file will not be atomic).
The directory is either absolute or relative to the JVMs current directory.
Attributes
File/Path
Optional
Output Directory (
outputDirectory) Description
Directory in the file system to put the rendered token lists in. The directory is either absolute or relative to the JVMs current directory.
This property is not required if the renderer plugin (see separate property) does not write on the outputstream (e.g. sends it somewhere else). It is required otherwise.
Note: If this property is not defined and the used renderer plugin writes on the output stream, then the result (e.g. a PDF file) is lost.
Attributes
File/Path
Optional
File Name Prefix (
fileNamePrefix) Description
Filename prefix for rendered report files. It is important to set this to a unique value for the kind of reports generated by this task. When this task deletes old reports, it looks at this prefix (and the user id) in order to find out what files to delete. Thus, if this prefix is the same as for other reports and the reside in the same directory, other reports may be deleted.
Do not use the prefix "pwd-" if password- reports are stored in the same directory. This prefix is the default for password letters (and not configurable in older plugin versions).
This property is optional to be backwards compatible. It is strongly recommended to define a prefix.
Attributes
String
Optional
Suggested values
matrix-, gridcard-
File Name Suffix (
fileNameSuffix) Description
Filename suffix for rendered token list files.
Attributes
String
Optional
Suggested values
.pdf, .docx, .txt
Generation Date Export Property (
generationDateExportProperty) Description
Name of a context property (make sure it is persisted in the used token list persister plugin) used to store the generation date of the current token list.
The generation date of the current token list is extracted from the token list data during the task and stored as date object (date and time) using the configured persister.
Attributes
String
Optional
Example
tok_list_inf_gen
Validity Date Export Property (
validityDateExportProperty) Description
Name of a context property (make sure it is persisted in the used token list persister plugin) used to store the validity date of the current token list.
The validity date of the current token list is computed using the generation date and the configured validity of the token list and stored as date object (date and time) using the configured persister.
Attributes
String
Optional
Example
tok_list_inf_val
Serial Number Export Property (
serialNumberExportProperty) Description
Name of a context property (make sure it is persisted in the used token list persister plugin) used to store serial number of the current token list.
The serial number of the current token list is extracted from the token list data during the task and stored as string using the configured persister.
Attributes
String
Optional
Example
tok_list_inf_val
Remaining Tokens Export Property (
remainingTokensExportProperty) Description
Name of a context property (make sure it is persisted in the used token list persister plugin) used to store remaining number of tokens on the current token list.
The remaining number of tokens on the current token list is extracted from the token list data during the task and stored as integer number using the configured persister.
Attributes
String
Optional
Example
tok_list_inf_val
Aggregate Report (
aggregateReport) Description
Optional property to describe an aggregate report over all generated reports in a batch. If none is configured, no aggregate report will be generated.
Attributes
Plugin-Link
Optional
Assignable plugins
Max No Of Cards To Print Per Day (
maxNoOfCardsToPrintPerDay) Description
When set, this property limits the number of matrix cards that are printed per day by shifting their generation date at creation time. The property can only be set, if a 'maximumValidityDays' has been configured.
Example: if the property is set to 500 but 1000 new cards are to be produced, the generation dates of the cards are set in a way, that the cards expire in blocks of 500 on 2 different days.
Example: if the property is set to 500 but 1000 new cards are to be produced, the generation dates of the cards are set in a way, that the cards expire in blocks of 500 on 2 different days.
Please note:
- Setting this property doubles the runtime of the task. Consider to only set it before bulk generation of matrix cards.
- The actual amount of cards to be printed on a given day could exceed the value of this property due to: 'delivery security gap' configuration, explicitly (manually) ordered cards or used up cards.
- The mechanism does not work retroactive, i.e. the expiration or print date of existing cards will not be altered.
Attributes
Integer
Optional
Shift Direction (
shiftDirection) Description
This property determines whether the generation date should be shifted into the future or past when 'maxNoOfCardsToPrintPerDay' is exceeded for the prospective print date.
Shifting into the past reduces the validity period, shifting into the future extends the validity period.
Attributes
Enum
Optional
Default value
PAST
YAML Template (with default values)
type: TanBatchTask
id: TanBatchTask-xxxxxx
displayName:
comment:
properties:
aggregateReport:
deleteOldTokenLists: false
deliverySecurityGap: 0
fileNamePrefix:
fileNameSuffix:
generationDateExportProperty:
hashFunctionPlugin:
languageAttributeName:
maxNoOfCardsToPrintPerDay:
maximumValidityDays: -1
outputDirectory:
remainingDaysThreshold:
remainingTokensExportProperty:
serialNumberExportProperty:
shiftDirection: PAST
tokenLength:
tokenListIterator:
tokenListPersister:
tokenListRenderer:
tokenTypeName:
tokensPerList:
validityDateExportProperty:
workingDirectory: