Magnolia 4.5 reached end of life on June 30, 2016. This branch is no longer supported, see End-of-life policy.
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.
The Public User Registration module is bundled with Magnolia and typically already installed. Download the module from the Magnolia Store or Nexus repository.
Public User Registration is a Community Edition module. It is typically already installed.Go to Magnolia Store > Installed modules in AdminCentral to check. To install the module individually, see the general module installation instructions.
See the general module uninstalling instructions and advice.
Public users are stored and managed in Security > Public Users 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 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.
The PUR module relies on other modules and system settings. Understanding the module requires a working knowledge of:
/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.The PUR module is configured at /modules/public-user-registration
.
You can create different public user configurations for each site in /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.
This feature is available in both editions. Although not technically related to the EE multisite feature, is only meaningful in an EE multisite environment.
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 URI | Resolved configuration |
---|---|
/demo-project/members-area/register.html | demo-project |
The configuration resolver is registered in /modules/public-user-registration/config/configurationResolver/class
.
The defaultRoles
and defaultGroups
nodes configured in /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.
Permission | Path |
---|---|
Get & Post | /.magnolia/pages/password-reminder* |
Get & Post | /.magnolia/pages/user-validation* |
Get & Post | /.magnolia/pages/register* |
The PUR pages that the public-user-registration-base
role gives permission to access are configured in /modules/public-user-registration/pages
. When using the
Mail
registration strategy you need to define a path to an existing page in Website in the /user-validation/targetPage
node for the email verification link to work.
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
demo-features
site.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 strategyemailTemplate
: 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.The content of the registration mail is created with the email.html
(GIT) script registered in the default emailTemplate
property. See Templates configuration 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
.
You can test the mail registration strategy on the demo-features
site on the public instance:
/server/defaultBaseURL
is valid.targetPage
in /pages/user-validation
points to an existing page in the demo-features site./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.targetPage
.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 are configured in /modules/public-user-registration/config/configurations/<configuration name>/passwordRetrievalStrategy
. Two classes are provided
default
and demo-project
configurations use this strategy.stkPURPasswordForm
form component.Here's the configuration for the demo-project
password retrieval strategy.
Strategy properties:
class
: Class that implements a password retrieval strategyemailTemplate
: 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.The content of the password reminder mail is created with the password-reset-email.ftl
(GIT) script registered in the default emailTemplate
property. See Templates configuration 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
.
You can test the password retrieval strategy on the demo-project
site on the public instance:
/server/defaultBaseURL
is valid.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./members-area
, click Request New Account and create a new account.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:
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:
phoneNumber
.users
, Base path=/public
) .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.
/modules/cache/config/configurations/default/cachePolicy/voters/urls/excludes
.dotMagnolia
node.purPages
and change the pattern to your PUR parent page, example, /demo-project/members-area
or /demo-features/modules/public-user-registration
.
The PUR module is fully integrated with the STK that provides PUR functionality directly on the demo pages.
The stkPublicUserRegistration
templates makes the form and intranet components available in content
area. The configuration is in Templating Kit > Template Definitions /pages/stkPublicUserRegistration/areas/main/areas/content
.
The STK PUR components are configured in Templating Kit > Template Definitions /components/pur
. The components fall into four categories:
stkPURRegistrationForm
, stkPURUpdateForm
, stkPURLoginForm
, stkPURPasswordForm
and stkPURPasswordChangeForm
).groupFields
, stkPUREdit
, stkPURAuthSubmit
, stkPURNotAuthSubmit
). These components are made available in the form components.stkPURIntranet
).stkPURLink
).The STK PUR form components are built on the Form component provided by the Form module. The PUR module adds:
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.stkPURRegistrationForm
stkPURUpdateForm
stkPURPasswordForm
component.stkPURPasswordChangeForm
component.
With one exception, stkPURLoginForm
(see below), the PUR form components are configured similarly. They are:
form.ftl
template script provided by the Form module. areas
node. 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 in Templating Kit > 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 Templating Kit > 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 in Templating Kit > Dialog Definitions/components/pur/stkLoginForm
. 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.
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.There are three custom PUR form field components configured in Templating Kit > 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:
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.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.
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
.
The stkPURIntranet
component configured in Templating Kit > 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.
The stkPURLink
component configured in Templating Kit > 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.