Public User Registration module

Magnolia Public User Registration (PUR) module allows registered users of a public Magnolia site to register and access restricted content. You can use the module to register users for the Forum module and other custom modules that support personalization and user specific handling. For example, collect e-mail addresses of subscribers to a newsletter and allowing them to manage subscription details after login.

Download

The Public User Registration module is bundled with Magnolia and typically already installed. Download the module from our Nexus repository.

Installing

Public User Registration is a Community Edition module. It is typically already installed. Launch the Configuration app and go to /modules/public-user-registration to check.

Uninstalling

User management

Public users are stored and managed in the Security app on the public instance. The system registers the account automatically when a user registers. Whether the user can use the account immediately or not depends on the configured registration strategy.

The PUR Module uses the HierarchicalUserManager to create user accounts. In the JCR, the account is stored in a folder hierarchy according to the realmName and the first two letters of the username.

Prerequisites

The PUR module relies on other modules and system settings. Understanding the module requires a working knowledge of:

• Form module : Many of the PUR components are configurable forms.
• Mail module : The PUR module uses the Mail module to send emails. You need to configure SMTP to send mail to registering users. If you don't do this, a public user profile is created when a user registers, but an email to verify the account cannot be sent.
• Default base URL: This URL is set in /server/defaultBaseUrl and needs to be set to your actual context path. It is used by the registration and password retrieval strategy classes to create email links. If the context path is set to magnolia instead of the actual context path, the default base URL is not configured properly.

Configuration

The PUR module is configured at /modules/public-user-registration.

Multisite

You can create different public user configurations for each site at /modules/public-user-registration/config/configurations. An example demo-project configuration is provided. You can also use the extends feature as shown in the demo-features example below. The configuration extends the default configuration but provides a custom password retrieval strategy.

Configuration resolver

Configuration resolver is a class that decides which configuration the PUR module should use. The  DefaultConfigurationResolver  finds the correct configuration based on the request URI.

Example:

The configuration resolver is registered at /modules/public-user-registration/config/configurationResolver/class.

Default roles and groups

The defaultRoles and defaultGroups nodes configured at /modules/public-user-registration/config/configurations/<configuration name>/defaultRoles and /defaultGroups define which users are managed by the module. Only users assigned the defined roles or to the defined groups are managed. Here are the default and demo-project configurations.

By default, the anonymous systems user and the demo-project-members group are assigned the public-user-registration-base role. The user requires permission to access the register, validation and password recovery URLs. The public-user-registration-base role provides these permissions. Here are the Web access permissions for the role.

Pages

The PUR pages that the public-user-registration-base role gives permission to access are configured at /modules/public-user-registration/pages. When using the Mail registration strategy you need to define a path to an existing page in the Pages app in the /user-validation/targetPage node for the email verification link to work.

Registration strategies

Registration strategies define how users are registered and are configured at /modules/public-user-registration/config/configurations/<configuration name>/registrationStragegy. Three registration strategy classes are provided

• Mail : Sends the registered public user an email that contains a verification link. When the user clicks the link, the system enables the user. This is the default strategy and is used on the demo-features site.
• Always : Enables the registered public user immediately. No verification is required.
• Never : Registers, but does not enable the user. An administration needs to enable the user manually by selecting the Enabled checkbox in Users in the Security app. This strategy is used on the demo-project site.
  

Here are the configurations for the default and demo-project registration strategies.

Mail registration strategy properties:

• class: Class that implements the registration strategy
• emailTemplate: Relative path to the template used for the outgoing email message.
• fromEmail: Email address to use as the sender.
• fromName: Name to use as the sender.
• pagePath: Relative path to the registration success page.
• subject: Subject line of the message.

Email message template

The content of the registration mail is created with the email.html (GIT) script registered in the default emailTemplate property. See Message templates on how to write and test a message template.

    <p>Dear ${user.name},</p> 
    <p>Please follow this link in order to validate your account: <a href="${defaultBaseUrl}${pagePath}">${defaultBaseUrl}${pagePath}</a></p> 
    <p>Thank you !</p> 

The Mail class adds the userid UUID and regStamp parameters to the URL to verify identity. The verification link is similar to  http://localhost:8080/magnoliaPublic/.magnolia/pages/user-validation.html?userId=fd28e57c-c263-45ca-a51f-c129fc46fbed®Stamp=1404821630904 and redirects to the  targetPage configured in the /pages/user-validation node, for example,  http://localhost:8080/magnoliaPublic/demo-features .

Testing the mail registration strategy

You can test the mail registration strategy on the demo-features site on the public instance:

1. Make sure your:
   
   1. SMTP settings are working
   2. Default base URL set in /server/defaultBaseURL is valid.
   3. targetPage in /pages/user-validation points to an existing page in the demo-features site.
2. Go to the the /demo-features/modules/public-user-registration/PURRegistration.html . If you are logged in add the ?mgnlLogout=true as a URL parameter to log out. This parameter is executed by the logout filter.
3. Register an account.
4. Click the validation link in the email that redirects to the targetPage.
5. Log in to Magnolia and go to Security > Public users to verify that the new account is enabled.

Password retrieval strategies

Password retrieval strategies are configured in /modules/public-user-registration/config/configurations/<configuration name>/passwordRetrievalStrategy. Two classes are provided

• MailChangePasswordLinkStrategy : This strategy sends the user a link to a password reset form. This is common practice on the Web and is secure because the mail does not contain a password. The default and demo-project configurations use this strategy.
• NOPStrategy : This strategy does nothing leaving you the option to code your own strategy in the Confirmation Email tab of the stkPURPasswordForm form component.

Here's the configuration for the demo-project password retrieval strategy.

Strategy properties:

• class: Class that implements a password retrieval strategy
• emailTemplate: Relative path to the template used for the outgoing email message.
• fromEmail: Email address to use as the sender.
• fromName: Name to use as the sender.
• subject: Subject line of the message.
• targetPage: Relative path to the page where the password change form is.
• tokenExpirationTime: Duration (in minutes) that the password change link remains valid.

Email message template

The content of the password reminder mail is created with the password-reset-email.ftl (GIT) script registered in the default emailTemplate property. See Message templates on how to write and test a message template.

    <p>Dear ${user.name!},</p>
    <p>Follow this link where you can set your new password: <a href="${defaultBaseUrl!}${pagePath!}">CLICK HERE</a></p>
    <p>If you did not ask for password change, ignore this email.</p>

The MailChangePasswordLinkStrategy class adds the userid UUID and token parameters to the URL to verify identity, and directs the user to the page set in the targetPage property that contains the password reset form. The link is similar to  http://localhost:8080/magnoliaPublic/demo-project/members-area/password-reset/password-change?userId=1f117c47-b55c-49d2-a7fb-37727f5272d6&token=39806536e5882f36101e9eff45336190420cbcc7 .  

Testing the password retrieval strategy

You can test the password retrieval strategy on the demo-project site on the public instance:

1. Make sure your:
   
   1. SMTP settings are working
   2. Default base URL set in /server/defaultBaseURL is valid.
2. Open demo-project on the public instance and log out, if necessary. You can click the Logout link in the header or add ?mgnlLogout=true as a URL parameter. This parameter is executed by the logout filter.
3. Go to /members-area, click Request New Account and create a new account.
4. Verify the new account in the email.
5. Using the header link, log out and then log in. 
6. Click Forgotten password on the login form.
7. Enter the username.
8. Click the link in the email.
9. Reset the password and log in.

User profiles

User profiles are configured in /modules/public-user-registration/config/configurations/<configuration name>/userProfileConfiguration. The UserProfile class is a basic profile bean that supports the default username, password, email and fullName properties. You can extend this class and register a custom class in the configuration if you need to store more information.

UserProfileConfiguration allows you to add custom user profile properties under the autopopulatedProperties node in the configuration. The default properties are always populated. You also need to write a custom class that sets the custom properties in the profile. 

In this example the demo-features configuration extends the default configuration. The extending configuration provides a hypothetical custom user profile class info.magnolia.module.publicuserregistration.CustomUserProfile and a custom parameter phoneNumber. When users register on the site, the registration form asks them to fill in a phone number. The custom class then sets the phone number in the user's profile.

In your custom user profile class:

1. Extend UserProfile .
2. Define the custom property.
3. Add setters and getters for the property.

Example: Custom user profile class for handling a phone number

public class CustomUserProfile extends UserProfile {
    private String phoneNumber = "";
    public String getPhoneNumber() {
        return phoneNumber;
    }
    public void setPhoneNumber(String phoneNumber) {
        this.phoneNumber = phoneNumber;
    }
}

To test the new property:

1. Add a new field named after the custom property on the registration form, for example phoneNumber.
2. Publish the form page to the public instance.
3. Register a new user.
4. In Tools > Export export the user profile to XML (Set Repository=users, Base path=/public) .
5. Check that the new property is in the exported XML.

Disabling the cache

For logged-in users and anonymous users to see different content on PUR pages, you need to disable the cache for logged-in users. By default the cache is disabled for authenticated (logged in) users in the Cache module at /modules/cache/config/configurations/default/cachePolicy/voters/deny/authenticated. AuthenticatedVoter checks if the current user is authenticated.

As an alternative, you can also disable the cache by excluding the page URLs. Use this options if you only have a small, contained members area.

1. Go to Configuration > /modules/cache/config/configurations/default/cachePolicy/voters/urls/excludes.
2. Duplicate the dotMagnolia node.
3. Rename the node to something like purPages and change the pattern to your PUR parent page, example, /demo-project/members-area or /demo-features/modules/public-user-registration.

STK Availability

PUR functionality is available directly on the STK demo pages.

Page template

The stkPublicUserRegistration templates makes the form and intranet components available in content area. The configuration is at STK > Template Definitions /pages/stkPublicUserRegistration/areas/main/areas/content.

Components

The STK PUR components are configured at STK > Template Definitions /components/pur. The components fall into four categories:

• Forms: Registration, profile update, login, password retrieval and password change form components. (stkPURRegistrationForm, stkPURUpdateForm, stkPURLoginForm, stkPURPasswordForm and stkPURPasswordChangeForm).
• Form fields: Edit and submit button form field components adapted for PUR use (groupFields, stkPUREdit, stkPURAuthSubmit, stkPURNotAuthSubmit). These components are made available in the form components.
• Intranet:: Text and Image component visible only to logged in users (stkPURIntranet).
• Link: Login and logout link component (stkPURLink).

Form components

The STK PUR form components are built on the   Form component provided by the Form module. The PUR module adds:

• Model classes:
  
  • RegistrationModel : RenderingModel for a single page registration form. This class extends FormModel . Used by the stkPURRegistrationForm, stkPURUpdateForm, stkPURPasswordForm and stkPURPasswordChangeForm components.
  • AuthenticationModel : RenderingModel for the login component that issues a redirect upon successful login. Used by the stkPURLoginForm component.
• Form processors: These form processors are executed when the appropriate form is submitted.
  
  • RegistrationProcessor : For user registration. Used by stkPURRegistrationForm
  • UpdateProcessor : For user account update. Used by stkPURUpdateForm
  • PasswordProcessor : For password retrieval and change. Used by the stkPURPasswordForm component.
  • TokenPasswordProcessor : For password change. It takes token from URL and checks whether the token is valid, and if so the user password is changed. Used by the stkPURPasswordChangeForm component.
  • CookiesFormProcessor : Form processor for adding cookies (provided by the Personalization module). Used by the stkPURRegistrationForm component.

With one exception, stkPURLoginForm (see below), the PUR form components are configured similarly. They are:

• Rendered by the form.ftl template script provided by the Form module. 
• Make the individual field components available within a field set in the areas node.  Only add fields that are supported by the registered user profile class.
• Use either the stkPURForm or stkPURFormWithEmail dialogs configured at STK > Dialog Definitions /components/pur. Both dialogs extend relevant tabs of the form dialog configured in the Form module.

Here's the configuration of the stkPURRegistrationForm component.

The stkPURLoginForm component is provided as a "ready-made" form. Here's the component definition at STK > Template Definitions /components/pur/stkLoginForm.

• modelClass: AuthenticationModel authenticates the username and password and issues a redirect on successful login. It is early execution aware.
• templateScript: The form is rendered by login.ftl that you can view in STK > Templates /components/pur.
• dialog: stkPURLoginForm allows the user to define a targetPage to redirect to after login, a realmName,and field and button labels. The definition is at STK > Dialog Definitions /components/pur/stkLoginForm.

Here are the form components on the demo-project site.

• stkPURRegistrationForm (demo-project/members-area/registration page).
  

  

• stkPURUpdateForm (demo-project/members-area/profile-update page).
  

  

• stkPURPasswordForm (demo-project/members-area/password-reset page)
  

  

• stkPURPasswordChangeForm ( demo-project/members-area/password-reset/password-change page).
  

  

• stkPURLoginForm (demo-project/members-area/login page) in logged out and logged in view.
   

Form field components

There are three custom PUR form field components configured at STK > Template Definitions /components/pur:

• stkPUREdit: Adds a text field that is hidden when a user is logged in.
• stkPURAuthSubmit: Adds a submit button for logged in users. Used for profile update and log out.
• stkPURNotAuthSubmit: Adds a submit button for logged out users. Used for registration, log in and password retrieval.

 The submit buttons are created on the component level to achieve different rendering, depending on whether the user is logged in or not.

For form fields, the PUR module adds:

• Validator: UsernameValidator verifies that the entered username does not exist in the system. This validator is registered in the Form module at /modules/form/config/validators/username. The validator is available for selection in the form component dialogs.
• Model class: RegistrationFieldModel is the RenderingModel for sub components in PUR forms. It is used by the stkPURAuthSubmit and stkPURSubmit components to check if the user isAuthenticated.

The PUR form fields and, standard text and password fields, are made available in the groupFields component that extends the formGroupFields component. The extends=override property makes the PUR form fields available instead of the standard form fields. The groupFields component is in turn available in the /<component name>/areas/fieldset/availableComponents/groupFields node of the form components. This is efficient configuration.

Intranet component

The stkPURIntranet component configured at STK > Template definitions /components/pur/stkPURIntranet is a Text and Image component that only renders if the user is logged in. The component uses the intranet.ftl template script and RegistrationFieldModel model class.

Here's and example of what logged in and logged out users see.

Link component

The stkPURLink component configured at STK > Template definitions /components/pur/stkPURLink provides a login/logout link.When a user is logged out, a login link displays, and when logged in the user's full name and a logout link display. Editors can define a target login, logout and profile update page in the dialog. In the demo sites the component is made available in the template prototype in the metaNavigation area.