Package eu.webtoolkit.jwt.auth

Class AuthWidget

java.lang.Object
eu.webtoolkit.jwt.WObject
eu.webtoolkit.jwt.WWidget
eu.webtoolkit.jwt.WWebWidget
eu.webtoolkit.jwt.WInteractWidget
eu.webtoolkit.jwt.WTemplate
eu.webtoolkit.jwt.WTemplateFormView
eu.webtoolkit.jwt.auth.AuthWidget
public class AuthWidget extends WTemplateFormView
An authentication widget.

The authentication widget is a widget that provides a login or logout function (depending on whether the user is currently logged in). You can use it for either or both purposes.

Login or logout events are signalled to a Login object on which this widget acts.

The widget also processes environmental information related to authentication:

  • email tokens, which are indicated in an internal path. The widget uses dialogs (by default) to interact with the user to act on the token.
  • authentication tokens, which are stored in browser cookies, to implement remember-me functionality.

The processEnvironment() method initiates this process, and should typically be called only at application startup time.

The authentication widget is implemented as a View for an AuthModel, which can be set using setModel(). The login logic (at this moment only for password-based authentication) is handled by this model.

It is very likely that the off-the shelf authentication widget does not satisfy entirely to your taste or functional requirements. The widget uses three methods to allow customization:

  • as a WTemplateFormView, you may change the layout and styling of to your liking.
  • the authentication logic is delegated to an AuthModel and can can be specialized or can be used with a custom view altogether.
  • the views are created using virtual methods, which may be specialized to create a customized view or to apply changes to the default view.

  • Constructor Details

  • Method Details

    • remove

      public void remove()
      Description copied from class: WWidget
      Destructor.

      Deletes a widget and all contained contents.

      Overrides:
      remove in class WTemplate
      See Also:

    • setModel

      public void setModel(AuthModel model)
      Sets a model.

      This sets a model to be used for authentication.

    • getModel

      public AuthModel getModel()
      Returns the model.

      The model is used only for the login function.

      See Also:

    • getLogin

      public Login getLogin()
      Returns the login object.

      This login object is used to keep track of the user currently authenticated.

    • setInternalBasePath

      public void setInternalBasePath(String basePath)
      Sets an internal path for authentication services.

      Only the registration function is made available through an internal path (so that one can redirect a user to the registration page). Other internal paths involved in authentication are configured in the service classes:

    • getInternalBasePath

      public String getInternalBasePath()
      Returns the internal path.

      See Also:

    • setRegistrationEnabled

      public void setRegistrationEnabled(boolean enabled)
      Configures registration capabilities.

      Although the AuthWidget itself does not implement a registration view, it may offer a button/link to do so, and calls registerNewUser() when a user wishes to register.

      Even if registration is not enabled, the result of an OAuthService login process may be that a new user is identified. Then the createRegistrationView() is also used to present this new user with a registration view, passing the information obtained through OAuth.

    • registerNewUser

      public void registerNewUser()
      Starts a new registration process.

      This calls registerNewUser(0).

    • registerNewUser

      public void registerNewUser(Identity oauth)
      Starts a new registration process.

      This starts a new registration process, and may be called in response to a user action, an internal path change, or an OAuthService login procedure which identified a new user. In the latter case, the OAuth-provided information is passed as parameter oauth.

      The default implementation creates a view using createRegistrationView(), and shows it in a dialog using showDialog().

    • processEnvironment

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

      This method process environmental information that may be relevant to authentication:

      • email tokens, which are indicated through an internal path. The widget uses dialogs (by default) to interact with the user to act on the token.
      • authentication tokens, which are stored in browser cookies, to implement remember-me functionality. When logging in using an authentication token, the login is considered "weak" (since a user may have inadvertently forgotten to logout from a public computer). You should let the user authenticate using another, primary method before doing sensitive operations. The createPasswordPromptDialog() method may be useful for this. This token denotes a regular username/password login. If the "remember-me" functionality is enabled for it, and selected, a token will be produced, named according to AuthService.getAuthTokenCookieName(), and valid for AuthService.getAuthTokenValidity() (in minutes). Both can be set by enabling authentication tokens with AuthService::setAuthTokenaEnabled(). By default the cookie will be called "wtauth" and will be valid for two weeks.

      See Also:

    • letUpdatePassword

      public void letUpdatePassword(User user, boolean promptPassword)
      Lets the user update his password.

      This creates a view to let the user enter his new password.

      The default implementation creates a new view using createUpdatePasswordView() and shows it in a dialog using showDialog().

    • handleLostPassword

      public void handleLostPassword()
      Lets the user "recover" a lost password.

      This creates a view to let the user enter his email address, used to send an email containing instructions to enter a new password.

      The default implementation creates a new view using getCreateLostPasswordView() and shows it in a dialog using showDialog().

    • getCreateLostPasswordView

      public WWidget getCreateLostPasswordView()
      Creates a lost password view.

      When email verification has been enabled, the user may indicate that he has lost his password – then proof of controlling the same email address that had associated with his account is sufficient to allow him to enter a new password.

      This creates the widget used to let the user enter his email address. The default implementation creates a new LostPasswordWidget.

      See Also:

    • createRegistrationView

      public WWidget createRegistrationView(Identity id)
      Creates a registration view.

      This creates a registration view, optionally using information already obtained from a third party identification service (such as an OAuth provider).

      The default implementation creates a new RegistrationWidget with a model created using getCreateRegistrationModel().

      See Also:

    • letResendEmailVerification

      public void letResendEmailVerification()
      Lets the user resend the verification email.

      This creates a view to let the user resend the email to verify their email address.

      The default implementation creates a new view using getCreateResendEmailVerificationView() and shows it in a dialog using showDialog().

    • getCreateResendEmailVerificationView

      public WWidget getCreateResendEmailVerificationView()
      Creates a view to resend the email verification email.

      If AuthService.isEmailVerificationRequired() is true, a button will be shown next to the user name field to resend the verification email (if the email was not yet verified). This button will show a dialog containing the widget returned by this method. The default implementation instantiates a ResendEmailVerificationWidget.

      This creates the widget used to let the user chose a new password. The default implementation instantiates an UpdatePasswordWidget.

      Note that if email verification is optional, the application should provide its own mechanism to resend the verification email (e.g. in a user settings widget).

    • createUpdatePasswordView

      public WWidget createUpdatePasswordView(User user, boolean promptPassword)
      Creates a view to update a user's password.

      If promptPassword is true, the user has to enter his current password in addition to a new password.

      This creates the widget used to let the user chose a new password. The default implementation instantiates an UpdatePasswordWidget.

      See Also:

    • createPasswordPromptDialog

      public WDialog createPasswordPromptDialog(Login login)
      Creates a password prompt dialog.

      This creates a dialog password. The user is taken from the login object, which also signals an eventual success using its Login.changed() signal.

      The default implementation instantiates a PasswordPromptDialog.

    • createMfaProcess

      public AbstractMfaProcess createMfaProcess()
      Create the MFA process.

      When MFA is enabled (AuthService#setMfaProvider() is set), this will be called to create a specific MFA process. This can be used by developers to provide their own implementation, and ensure that the right widgets are shown to the user.

      By default this will generate a TotpProcess.

    • createMfaView

      public void createMfaView()
      Shows the MFA process in the UI.

      This functionality manages how the MFA step is shown to the user. Developers can override this to show the step in any way they see fit. This can be shown as part of the main view, as a pop-up, ...

      It will also need to decide whether the setup view (AbstractMfaProcess.createSetupView()) or input view (AbstractMfaProcess.createInputView()) is shown to the user.

      By default this will show the process in the main view, replacing the normal login widget with the right view on the MFA process.

    • displayError

      public void displayError(CharSequence m)
      Displays the error message.

      This method display an dialog showing the error

    • displayInfo

      public void displayInfo(CharSequence m)
      Displays the info message.

      This method display an dialog showing the info

    • create

      protected void create()
      Creates the user-interface.

      This method is called just before an initial rendering, and creates the initial view.

      The default implementation calls createLoginView() or createLoggedInView() depending on whether a user is currently logged in.

      If MFA is enabled (AuthService.isMfaEnabled()), this may call createMfaView(). This will be called if the user that is logging in has this step enabled (AuthModel#hasMfaStep()).

    • createLoginView

      protected void createLoginView()
      Creates the login view.

      This creates a view that allows the user to login, and is shown when no user is current logged in.

      The default implementation renders the "Wt.Auth.template.login" template, and binds fields using createPasswordLoginView() and createOAuthLoginView().

    • createLoggedInView

      protected void createLoggedInView()
      Creates the view shown when the user is logged in.

      The default implementation renders the "Wt.Auth.template.logged-in" template.

    • createPasswordLoginView

      protected void createPasswordLoginView()
      Creates a password login view.

      This is used by the default implementation of createLoginView() to prompt for the information needed for logging in using a username and password. The default implementation implements a view guided by the getModel().

      See Also:

    • createOAuthLoginView

      protected void createOAuthLoginView()
      Creates a widget to login using OAuth.

      The default implementation adds an icon for each OAuth service provider available. The icon that will be used for each service is a PNG file with a path based on the OAuthService.getName() of the service. If the name is is "myService", then the icon path will be "css/oauth-myService.png". JWt does not bundle any icons by default, so you should make sure that the icon is in place.

      There's a lot to say about making a usable login mechanism for OAuth (and federated login services in general), see https://sites.google.com/site/oauthgoog/UXFedLogin.

      See Also:

    • showDialog

      protected WDialog showDialog(CharSequence title, WWidget contents)
      Shows a dialog.

      This shows a dialog. The default method creates a standard WDialog, with the given title and contents as central widget.

      When the central widget is deleted, it deletes the dialog.

    • getCreateRegistrationModel

      protected RegistrationModel getCreateRegistrationModel()
      Creates a registration model.

      This method creates a registration model. The default implementation creates a RegistrationModel() but you may want to reimplement this function to return a specialized registration model (complementing a specialized registration view).

      See Also:

    • createFormWidget

      protected WWidget createFormWidget(String field)
      Description copied from class: WTemplateFormView
      Creates a form widget.

      This method is called by updateViewField() when it needs to create a form widget for a field, and none was specified using setFormWidget().

      Overrides:
      createFormWidget in class WTemplateFormView

    • render

      protected void render(EnumSet<RenderFlag> flags)
      Description copied from class: WWidget
      Renders the widget.

      This function renders the widget (or an update for the widget), after this has been scheduled using scheduleRender().

      The default implementation will render the widget by serializing changes to JavaScript and HTML. You may want to reimplement this widget if you have been postponing some of the layout / rendering implementation until the latest moment possible. In that case you should make sure you call the base implementation however.

      Overrides:
      render in class WWebWidget