Two-factor authentication (Concept)
For user logins, a two-factor authentication (2FA) can be implemented. In addition to the user name and password, a further security query is issued, which must be answered successfully in order to log in.
An own process (e.g. security token via e-mail) can be implemented, or an external TOTP provider can be connected (e.g. authentication via the Microsoft Authenticator App). A prerequisite for TOTP is _data 4.5 or higher.
The 2FA itself is implemented via event handling. The following events are available for this purpose:
In order to implement TOTP 2FA, the following elements can be used:
Important notice
Two-factor authentication approaches in _pro are configured via event handlers, which cannot be overridden via safe mode for security reasons.
Therefore, errors in the configuration can lead to the permanent lockout of users. Should this happen, the security check can only be unhooked once via the following steps:
A file named "skip_tfa_for_USERNAME" must be placed in the 'backup' directory of the data wizard (by default 'datawizard/backup'). This file will be removed automatically when the login was successful.
Login in safe mode (URL parameter safeMode=true), with the user mentioned in the backup file name
2FA with TOTP
Two-factor authentication using TOTP takes place in two steps. In the first step, a secret key is generated and shared between the authenticator app and the respective provider.
This step can be started by the element Register device and can also be undone by Deregister device.
Whether a device is already authorized for a certain user can be checked by means of Two factor device registered? This means that in the login process it can first be checked whether a device is registered and then, depending on the result, either start the registration process or start a 2FA authentication.
This first step only needs to be run through once for each user.
In the second step, a code is requested for each login, which is then checked for correctness. The basic process is shown in the following figure:
After the user logs in, the event Two-factor authentication: Prepare is triggered. In principle, this can be reacted to in any way in the event action (see examples below); in the case of TOTP, the code is queried with the Prepare action. Subsequently, the 'Verify' event is triggered. In this event handling, the 'Verify' action can be used to check for correctness.
All actions can still be applied to a user other than the owner of the current session with a 'For User' parameter.
Example
For 2FA using TOTP, the appropriate activation must be entered in the configuration file $HUB_HOME/etc/auth.xml (as an example, the authenticator from Google, other permitted authenticators can be found in the _data help):
<Call name="addTFAHandler"> <Arg>com.ebd.hub.services.auth.tfa.otpauth.TOTPHandler</Arg> <Call name="addDeviceTemplate"> <Arg>GoogleAuthenticator</Arg> <Arg>HmacSHA1</Arg> </Call></Call>For 2FA without TOTP, nothing needs to be changed in configuration files.
The following is a simplified example of a 2FA with a Google Authenticator (this example is not transferable, in the case of a missing device registration, appropriate action would have to be taken):
|
|
The left image shows the 2FA preparation: The type check checks for a 2FA request and whether a device is registered for the user. If both are fulfilled, the Prepare action is executed. It will ask for the code that is displayed in the authenticator.
|
|
2FA with selfmade verification
In principle, any second factor for authentication can be created with the provided actions (for example, a token which is sent by e-mail and then queried, see also the examples below). It is important that the corresponding value is passed via storage.
Example
Analogous to TOTP authentication, custom methods can also be implemented with the events Two-factor authentication: Prepare (event) and Two-factor authentication: Verify (event).
As mentioned above, these events pass a two-factor authentication request to the rules and actions. In its 'storage' (accessible via data field), arbitrary values can be written and read with the object field value resolver.
These are retained across the two-factor events.
The concept is therefore simple: determine a secret at Two-factor authentication: Prepare (event), store it in the storage of the input object and communicate it to the user in any way. Then check the secret at the Two-factor authentication: Verify event.
Below are two extremely simple example event handlers that illustrate this workflow:
|
|
|
|
The user should be presented with the message 'Name the secret!'. The secret 'Sherbet Lemon' is noted in the invented storage field 'secret'. In practice, the secret is usually generated randomly and sent to the user via e.g. via e-mail or SMS to the user. |
During verification (after the user has entered the secret), the system checks whether the secret from the storage field 'secret' corresponds to the user's response. The return value of the check (true/false) is then written to the 'verified' field, which decides, whether the login is allowed (true) or denied (false). |
The configured example in action:
After correctly entering the user name and password, the user is confronted with the following message:
If the user enters the secret 'Sherbet Lemon' correctly, they will be logged in successfully.