Due to security implications an authentication factor should not be validated on the client side (the smart-device). The Authentication factors are evaluated on the XignIn-Manager and an appropriate response is returned. If an invalid factor is supplied during a process of the XignIn technology a lockout will occur. The duration of the lockout period can be configured freely on the XignIn-Manager. For self-managed XignIn-Manager (on-premise installation) please refer to the documentation of the manager on the topic of how to configure the lockout periods. However, note that the lockout cannot be deactivated entirely. The duration can only be set to an unobtrusive value, although this is not recommended as it significantly reduces the security.
Lockouts are individual for each activation of an account. Meaning, assuming that a user has an account with two activations A and B and activation A has a lockout of two days, activation B can still be used for authentication or managing the account. Besides the lockout duration, there is also an option to permanently lockout an activation after a certain number of failed attempts. If this option is activated and the threshold of available attempts is exceeded, the activation becomes permanently deactivated and can not be unlocked simply by waiting long enough. As for the XignSys SDK lockouts can occur in the personalization and authentication processes. They are divided in the following two categories: pending and attempt.
A pending lockout describes the state in which a lockout is still active but another request is made during this
time. This state is returned via a XignSdkLockoutError (XignSdkLockoutException). This is a subclass of
the XignSdkError (XignSdkException). This error can occur in every function of the Personalizerand Authenticator
that is needed for the process. The current process is terminated upon receiving this error and has to be completely
restarted from the beginning, e.g. new personalization initialization data have to be acquired.
The XignSdkLockoutError (XignSdkLockoutException) contains a property named information
of the type PendingLockoutInformation. This object carries the following data about the current lockout:
currentDate - The point in time from which lockedUntil has been calculated.firstFailedAttemptAt - The point in time when the first failed attempt occurred and after which no successful
authentication has been performed anymore.lockedSince - The point in time the activation was locked.lockedUntil - The point in time until the activation is locked.isPermanent - Indicates whether the activation has been locked permanently.These data can be used to build a UI for the user which shows the current lockout. However, most important are the
properties isPermanent and lockedUntil. If isPermanent returns true this means the current activation is locked
out permanently. This state can only be reversed when the user logs on to the XignIn-Managers profile page with another
activation and reactivates the permanently locked activation.
Note: A permanently locked activation cannot always be reactivated by the user alone. If the accounts are managed by a third party application, the XignIn-Managers profile page may not be reachable directly. In this case, the recovery process of the third party application must be used.
If isPermanent returns false the property lockedUntil determines the time until which the lockout is active. After
that point a new attempt can be made. Retrying the process before this point, as well as trying another locked process,
will result in another XignSdkLockoutError (XignSdkLockoutException).
Note: Retrying a process or starting a new one during an active lockout does not increase the lockout duration but will, as stated above, always fail.
In case an activation is currently not locked but during a process a (new) lockout is produced (e.g., a user enters a wrong PIN for the first time), a lockout attempt will be received.
It still means, that the activation is locked and the process failed to complete at this point in time, but in contrast to the pending lockout, this result allows retrying the step which failed without restarting the whole process. For example, if an authentication process failed due to the user entering a wrong PIN, there is no need to scan a new QR Code or to follow a Deep-Link in general.
For this purpose, the lockout information is not encapsulated in a XignSdkLockoutError (XignSdkLockoutException) but
returned as a case named lockout—with a concrete implementation named Lockout—which is contained by both
the PersonalizationResult and the AuthenticationResult. This case contains an instance
of LockoutAttemptInformation and the object needed to repeat the process from the previous step.
The LockoutAttemptInformation contains similar data to the PendingLockoutInformation about the current lockout:
firstFailedAttemptAt - The point in time when the first failed attempt occurred and after which no successful
authentication has been performed anymore.lockedSince - The point in time the activation was locked.lockedUntil - The point in time until the activation is locked.currentFailedAttempts - The amount of failed attempts since firstFailedAttemptAt. The value starts with 1.maxFailedAttempts - The maximum amount of failed attempts that are possible until the activation is locked
permanently. A non-positive value indicates that the server is not configured to permanently lock an activation at
all.isPermanent - Indicates whether the activation has been locked permanently.These data can also be used to build a UI for the user which shows the current lockout. The isPermanent
and lockedUntil can be handled as described in the previous chapter Pending lockout. After the
lockout duration has passed, the previous step of the process can be repeated with either
the PersonalizationInitializationData for a personalization or AuthenticationUserInformation for an authentication.
Note: All signatures of the
AuthenticationUserInformationare cleared in case of a lockout. Therefore, all required factors must be supplied again toAuthenticationUserInformation.sign(factor:)before the step can be repeated.