Magnolia 5.3 reached end of life on June 30, 2017. This branch is no longer supported, see End-of-life policy.

Page tree
Skip to end of metadata
Go to start of metadata

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.

 Click for installation steps...

(warning) Create a backup of your system before you install a module. Uninstalling a module is not as simple as removing the .jar file. Modules add and change configurations and may change the content. Try new modules in a test environment first. A module consists of a JAR file and may include dependent JAR files. Modules are responsible for updating their own content and configurations across versions. Be sure to keep only one version of each module and its dependencies.

To install a module:

  1. Stop the application server.
  2. Copy the module JAR files into the WEB-INF/lib directory. The location of this directory depends on the application server.
    • Tomcat: /webapps/magnoliaAuthor/WEB-INF/lib
    • JBoss: /server/default/deploy/magnoliaAuthor/WEB-INF/lib
  3. Restart the server.
  4. Go to the AdminCentral URL.
  5. Start the Web update process.
  6. Click Start up Magnolia.

Repeat the steps for each author and public instance.

Uninstalling

 Click for uninstallation steps...

To uninstall a module, remove the module JAR file from the /WEB-INF/lib folder and restart Magnolia.

(warning) However, this is rarely enough. Modules add and modify configuration during installation. The use of a module also changes content. Removing all of these changes is difficult without knowing the installation tasks in detail.

To test a module, use the embedded Derby database and take a backup of your repositories folder. Install the module and try it. When you are done testing, remove the module JAR and restore the repositories folder from the backup. This way you can go back to square one.

We also recommend that you segregate the development and production environments. Take regular backups for disaster recovery so you can revert to a prior state in a routine fashion.

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.

The user account is only created on the public instance. Make sure to backup this data! When using several public instances, the instances or at least the users workspace needs to be clustered in order to share accounts between different instances. Another option is to implement observation based synchronization in order to replicate user accounts across instances.

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.

Node name

Value

 modules 

 public-user-registration

 

 config

 

 configurations

 

 default

 

 defaultRoles

 

 defaultGroups

 

 registrationStrategy

 

 passwordRetrievalStrategy

 

 userProfileConfiguration

 

 realmName

public

 demo-project

 

 demo-features

 

 passwordRetrievalStrategy

 

 class

info.magnolia.module.publicuserregistration.strategy.CustomStrategy

 extends

override

 extends

../default

This feature is available in both editions. Although not technically related to the EE Pro multisite feature, is only meaningful in an EE Pro multisite environment.

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:

Request URIResolved configuration
/demo-project/members-area/register.htmldemo-project

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

Node nameValue

 modules

 

 public-user-registration

 

 config

 

 configurationResolver

 

 class

info.magnolia.module.publicuserregistration.configuration.DefaultConfigurationResolver

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.

Node name

Value

 public-user-registration

 

 config

 

 configurations

 

 default

 

 defaultRoles

 

 anonymous

anonymous

 pur

public-user-registration-base

 defaultGroups

 

....

 

 demo-project

 

 defaultRoles

 

 anonymous

anonymous

 pur

public-user-registration-base

 defaultGroups

 

 demo-project-members

demo-project-members

....

 

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.

PermissionPath
Get & Post/.magnolia/pages/password-reminder*
Get & Post/.magnolia/pages/user-validation*
Get & Post/.magnolia/pages/register*

Pages

The PUR pages that the public-user-registration-base role gives permission to access are configured at /modules/public-user-registration/pages. (warning) 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.

Node name

Value

 public-user-registration

 

 pages

 

 register

 

 profile-update

 

 user-validation

 

 class

info.magnolia.module.publicuserregistration.frontend.EnableByUuid

 targetPage

/demo-features.html

 password-reminder

 

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.

Node name

Value

 public-user-registration

 

 config

 

 configurations

 

 default

 

 defaultRoles

 

 defaultGroups

 

 registrationStrategy

 

 class

info.magnolia.module.publicuserregistration.strategy.Mail

 emailTemplate

/info/magnolia/module/publicuserregistration/strategy/email.html

 fromEmail

test@test.com 

 fromName

mail.registration.from

 i18nBasename

info.magnolia.module.publicuserregistration.messages 

 pagePath

.magnolia/pages/user-validation.html 

 subject

mail.registration.subject 

......

 

 demo-project

 

 defaultRoles

 

 defaultGroups

 

 registrationStrategy

 

 class

info.magnolia.module.publicuserregistration.strategy.Never

......

 

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

email.html
    <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.

Although demo-project uses the Never mail registration strategy, a verification link is sent to the user. This email is configured in the Confirmation Email tab of the stkPURRegistrationForm form component on the /demo-project/members-area/registration page.

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.

Node name

Value

 public-user-registration

 

 config

 

 configurations

 

 default

 

 demo-project

 

 defaultRoles

 

 defaultGroups

 

 registrationStrategy

 

 passwordRetrievalStrategy

 

 class

info.magnolia.module.publicuserregistration.password.MailChangePasswordLinkStrategy

 emailTemplate

publicuserregistration/components/password-reset-email.ftl

 fromEmail

password@magnolia-cms.com

 fromName

Magnolia

 subject

Magnolia password update

 targetPage

demo-project/members-area/password-reset/password-change

 tokenExpirationTime

30

 userProfileConfiguration

 

 realmName

public

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.

password-reset-email.ftl
    <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>

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.

Node name

Value

 public-user-registration

 

 config

 

 configurations

 

 default

 

 defaultRoles

 

 defaultGroups

 

 registrationStrategy

 

 passwordRetrievalStrategy

 

 userProfileConfiguration

 

 userProfileClass

info.magnolia.module.publicuserregistration.UserProfile

 realmName

public

 demo-features

 

 userProfileConfiguration

 

 autopopulatedProperties

 

 phoneNumber

phoneNumber

 extends

override

 userProfileClass

info.magnolia.module.publicuserregistratiob.CustomUserProfile

 extends

../default

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

CustomUserProfile.java
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.

Node name

Value

 cache

 

 config

 

 configurations

 

 default

 

 cachePolicy

 

 voters

 

 urls

 

 deny

 

 parameters

 

 onAuthor

 

 authenticated

 

 class

info.magnolia.voting.voters.AuthenticatedVoter

 enabled

true

 level

2


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.

Node name

 pages

 stkPublicUserRegistration

 areas

 main

 areas

 content

 availableComponents

 stkPURRegistrationForm

 stkPURUpdateForm

 stkPURLoginForm

 stkPURPasswordForm

 stkPURPasswordChangeForm

 stkPURIntranet

 stkTextImage

 stkLinkList

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).

Node name

Value

 components

 

 pur

 

 stkPURRegistrationForm

 

 stkPURUpdateForm

 

 stkPURLoginForm

 

 stkPURPasswordForm

 

 stkPURPasswordChangeForm

 

 groupFields

 

 stkPUREdit

 

 stkPURAuthSubmit

 

 stkPURNotAuthSubmit

 

 stkPURIntranet

 

 stkPURLink

 

Form components

Node name

Value

 components

 

 pur

 

 stkPURRegistrationForm

 

 formProcessors

 

 registrationProcessor

 

 class

info.magnolia.module.publicuserregistration.processors.RegistrationProcessor

 enabled

true

 sendConfirmationEmail

 

 cookiesProcessor

 

 areas

 

 fieldsets

 

 availableComponents

 

 groupFields

 

 id

standard-templating-kit:components/pur/groupFields

 class

info.magnolia.module.form.templates.components.FormParagraph

 description

pur.paragraph.stkPURRegistrationForm.description

 dialog

standard-templating-kit:components/pur/stkPURFormWithEMail

 i18nBasename

info.magnolia.module.templatingkit.messages 

 modelClass

info.magnolia.module.publicuserregistration.frontend.action.RegistrationModel 

 renderType

 stk

 templateScript

/form/components/form.ftl 

 title

pur.paragraph.stkPURRegistrationForm.title 

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.
  • dialogstkPURLoginForm 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.

Node name

Value

 components

 

 pur

 

 stkPURLoginForm

 

 description

pur.paragraph.stkPURLoginForm.description

 dialog

standard-templating-kit:components/pur/stkPURLoginForm

 i18nBasename

info.magnolia.module.templatingkit.messages

 modelClass

info.magnolia.module.publicuserregistration.frontend.action.AuthenticationModel

 renderType

stk

 templateScript

/templating-kit/components/pur/login.ftl

 title

pur.paragraph.stkPURLoginForm.title 

 The stkPURRegistrationForm, stkPURPasswordForm and stkPURPasswordChangeForm components components allow you to configure an email in the Confirmation Email tab of the dialog. Bear in mind that emails may also be sent by the registration or password retrieval strategy configured in the module.

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.

Node name

Value

 components

 

 pur

 

 groupFields

 

 areas

 

 fields

 

 availableComponents

 

 formEdit

 

 stkPUREdit

 

 formPassword

 

 stkPURAuthSubmit

 

 stkPurNotAuthSubmit

 

 extends

override

 description

areas.components.pur.fields.description

 enabled

true

 title

areas.components.pur.fields.title 

 type

 list

 extends

/modules/form/templates/components/formGroupFields

Form fields need to have specific names for PUR to work. When you add form fields on a page name them username, fullName, password, passwordConfirmation and email.

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.