Package eu.webtoolkit.jwt.auth.mfa

Class TotpProcess

java.lang.Object
eu.webtoolkit.jwt.WObject
eu.webtoolkit.jwt.auth.mfa.AbstractMfaProcess
eu.webtoolkit.jwt.auth.mfa.TotpProcess
public class TotpProcess extends AbstractMfaProcess
A process managing the TOTP setup and validation.

This process allows the User that is trying to log in an extra step to validate their identity. They will have to provide the TOTP code as an extra step to validate their log-in additionally.

This process' functionality is twofold. If a User does not have TOTP set-up yet, they will be shown the QR code and the secret key. They can then add this to an authenticator app or extension of their choice (createSetupView()).

If they have it enabled already, they will simply be asked to provide a TOTP code to verify their identity as a second factor (createInputView()).

This process will also look in the environment for cookies, so that the MFA step can also be remembered (processEnvironment()). If the user logs in using a device they use often, they can opt to remember the login, which creates a cookie (see AuthService#setMfaTokenCookieName(), and AuthService#setMfaTokenValidity()). If this cookie remains in the user's browser, and in the local database (in the "auth_token" table, by default), the user's TOTP step can be skipped for a certain time (see AbstractMfaProcess.getProcessMfaToken()).

If a developer wants to force all users to use this functionality, they can do so by enabling AuthService#setMfaRequired().

Whether or not this process is executed when logging in, is managed by AuthModel#hasMfaStep().

See Also:

  • Constructor Details

    • TotpProcess

      public TotpProcess(AuthService authService, AbstractUserDatabase users, Login login)
      Constructs the TotpProcess holding the TOTP "login".

      For the provided authentication service authService this will either request a TOTP code from the user as a second factor, or initiate the process to add the TOTP secret to their record, allowing for future TOTP code requests.

      Optionally, if authentication tokens are enabled (see AuthService#setAuthTokensEnabled()), this step can be temporarily bypassed, for as long as the token is valid (see AuthService.getMfaTokenValidity()).

  • Method Details

    • processEnvironment

      public void processEnvironment()
      Processes the (initial) environment.

      This can be called to tell the widget to look through the environment for the relevant cookies. It will handle the side-effect of finding such a cookie, and it still being valid. The user will be logged in, in a weak state (LoginState.Weak), and the authenticated() signal will be fired, with an AuthenticationStatus.Success.

      Overrides:
      processEnvironment in class AbstractMfaProcess

    • createSetupView

      public WWidget createSetupView()
      Creates the view to manage the TOTP code.

      This either adds a new code to the user, or expects a code to be entered based on their existing TOTP secret key.

      Specified by:
      createSetupView in class AbstractMfaProcess

    • createInputView

      public WWidget createInputView()
      Creates the view to input the TOTP code.
      Specified by:
      createInputView in class AbstractMfaProcess
      See Also:

    • authenticated

      public Signal1<AuthenticationResult> authenticated()
      Signal emitted upon an authentication event.

      This event can be a success, failure, or error.

      The additional string can provide more information on the attempt, indicating the type of error, or the reason for the failure. The status and message are both stored in an instance of the AuthenticationResult.

      This can be used to reliably check whether the user has logged in with MFA. Previously the Login.changed() signal had been fired, when the user logged in, but it could still be that the state was not LoginState.Weak or LoginState.Strong, but LoginState.RequiresMfa. This signal can be listened to, to ensure that, on success, the user will actually be logged in.

      Side-effects to the login can then be attached to this signal.

    • createBaseView

      protected WTemplate createBaseView()
      Creates the base of the UI.

      This retrieves the message Wt.Auth.template.totp from JWt's resource bundle. This is used as the main template to build the UI from, and bind all elements to it.

    • bindQRCode

      protected void bindQRCode(WTemplate view)
      Binds the QR Code to the UI.

      This binds both the rendered QR code, as well as the secret itself (to be copied over to a authenticator app).

      See Also:

    • bindCodeInput

      protected void bindCodeInput(WTemplate view, boolean throttle)
      Binds the code input field to the UI.

      This creates and binds the field where the generated TOTP code will be entered.

      The throttle parameter manages whether or not pressing "enter" on this field will result in the verification of the code being subject to throttling (see AuthThrottle).

      See Also:

    • bindRememberMe

      protected void bindRememberMe(WTemplate view)
      Binds "remember-me" checkbox to the UI.

      This creates and binds the checkbox which enables "remember-me" functionality, if this is enabled (see AuthService#setAuthTokensEnabled()).

      See Also:

    • bindLoginButton

      protected void bindLoginButton(WTemplate view, boolean throttle)
      Binds the "Login" button to the UI.

      This button will run the verification process on the entered TOTP code.

      The throttle parameter manages whether or not pressing the button will result in the verification of the code being subject to throttling (see AuthThrottle).

      See Also:

    • bindLogoutButton

      protected void bindLogoutButton(WTemplate view)
      Binds the "Back" button to the UI.

      This button can be pressed to return to the original login page. This may be handy in case the user isn't able to provide the TOTP code.

      See Also:

    • update

      protected void update(WTemplate view, boolean throttle)
      Updates the UI after a verification attempt.

      This updates the view with the effects of the verification attempt. Displaying a message in case it did not succeed, and updating the styling of the input field.

      The throttle parameter manages whether or not the attempt will result in the verification of the code being subject to throttling (see AuthThrottle).

      See Also:

    • verifyCode

      protected void verifyCode(WTemplate view, boolean throttle)
      Verifies the entered code.

      The code the user provided is verified, and the UI is updated accordingly (using update()).

      This also handles the actual authentication, in case the verification is successful. This logs in the user (see Login#login()), and fires the authenticated() signal.

      In case of the "remember-me" functionality being enabled, it will create the cookie.

    • getCurrentSecretKey

      protected String getCurrentSecretKey()
      The secret key of the user.

      Either this is a newly generated key, in case the user is setting up their TOTP access. Or this is the one stored in the database. In case of the latter being true, be careful not to display this in the browser.