UserRegistrationService (interface)

Provides the ability for users to sign-up to access an application by providing a valid email address. Also provides the capability for users to reset their password if forgotten.

API

UserRegistrationService.java
interface UserRegistrationService {
  boolean usernameExists(String username)     (1)
  boolean emailExists(String emailAddress)     (2)
  void registerUser(UserDetails userDetails)     (3)
  boolean updatePasswordByEmail(String emailAddress, String password)     (4)
}
1 usernameExists(String)

Checks if there is already a user with the specified username

2 emailExists(String)

Checks if there is already a user with the specified email address.

3 registerUser(UserDetails)

Creates the user, with specified password and email address.

4 updatePasswordByEmail(String, String)

Allows the user to reset their password.

Members

usernameExists(String)

Checks if there is already a user with the specified username

emailExists(String)

Checks if there is already a user with the specified email address.

registerUser(UserDetails)

Creates the user, with specified password and email address.

The username and email address must both be unique (not being used by an existing user).

updatePasswordByEmail(String, String)

Allows the user to reset their password.

Implementation

The core framework itself defines only an SPI for this service; there is no default implementation. Rather, the implementation will depend on the security mechanism being used.

SecMan

If you have configured your app to use the SecMan extension then note that it does provide an abstract implementation (SecurityModuleAppUserRegistrationServiceAbstract) of the UserRegistrationService. You will need to extend that service and provide implementation for the two abstract methods: getInitialRole() and getAdditionalInitialRoles(). This is needed so that the self-registered users are assigned automatically to your application role(s) and be able to use the application. Without any role such user will be able only to see/use the logout link of the application.

For example:

@Service
public class AppUserRegistrationService
        extends SecurityModuleAppUserRegistrationServiceAbstract {

    protected ApplicationRole getInitialRole() {
        return applicationRoles.findRoleByName("regular-user");
    }
    protected Set<ApplicationRole> getAdditionalInitialRoles() {
        return Collections.singleton(
            applicationRoles.findRoleByName("self-registered-user"));
    }

    @Inject ApplicationRoles applicationRoles;
}

Usage by the framework

The Web UI (Wicket viewer) supports user registration, relying on both the EmailNotificationService and EmailService.

The framework provides default implementations of both of these services. The notification service requires no further configuration. The email service (EmailServiceDefault) does require a couple of configuration properties to be set (specifying the SMTP mail server/accounts/password).

User sign-up

For user sign-up, the Web UI (Wicket viewer) will check whether an implementation of this service (and also the EmailNotificationService) is available, and if so will render a sign-up page where the user enters their email address. A verification email is sent (using the aforementioned EmailNotificationService) which includes a link back to the running application; this allows the user then to complete their registration process (choose user name, password and so on). When the user has provided the additional details, the Wicket viewer calls this service in order to create an account for them, and then logs the user on.

Password reset

For the password reset feature, the Wicket viewer will render a password reset page, and use the EmailNotificationService to send a "password forgotten" email. This service provides the ability to reset a password based on the user’s email address.

Further details on the user registration feature (as supported by the Wicket viewer) are discussed here.

Other usages

It is of course possible for domain objects to use this service; it will be injected into domain object or other domain services in the usual way. That said, we expect that such use cases will be comparatively rare; the primary use case is for the Wicket viewer’s sign-up page.