[NCN-440] Update validation for one-click access

[jsperhac]

Dependencies

This work is part of Epic NCN-434, whose PRs are as follows:

• 1693, NCN-633 plgUserHubzero (on user login, ensure user has a secret in the DB)

• 1683 NCN-439 com_members (manage user secret)

• 1676 NCN-437 com_newsletter (manage campaign secret)

• 1675 NCN-438 com_config (manage hub secret)

• 1704 NCN-702, NCN-440: com_newsletter (The current PR: update verification, after porting functionality from custom com_reply)

Summary

Move and adapt custom code from Nanohub (com_reply) into the core CMS component, com_newsletter.

Then, update access validation for one-click links to use the secrets (hub, user, and campaign) created in the Epic mentioned above, NCN-434.

NOTE that all PRs mentioned above are already merged into this branch. All of them have been reviewed and tested.

Jira cards (for this PR):

• NCN-440 Update validation for one-click access
• NCN-702 Move com_reply functionality into CMS core com_newsletter
• NCN-733 Add CSRF tokens and checks

What's the point again?

Nanohub team wants to be able to send emails to their users with secure, unique links that enable users one-click access to their editable profile details or to a survey. This work ensures that we can selectively reset or expire codes for individual users or for a campaign. In order to provide access we maintain unique secret codes for each user; for each "campaign"; and for the Hub. The three of these must be hashed together and the expiration date validated for access to be granted.

If this solution seems weirdly incomplete, it is. The Nanohub team uses a Salesforce instance to do their mailings. This requires only that they hit a replica of the Nanohub database to query for the needed campaign id, username, and hashed access code. Those are pulled into Salesforce, which handles the mailing part.

However, it was thought that this functionality might be generally useful so this work moves it into core.

Previous PRs provide admin user interfaces for Hub-side management of:

• individual user secret codes
• creation of user secrets for new members
• management of new campaigns (which are secrets with expiration dates)
• management of Hub secret

Use

The one-click access code is generated by a call to stored procedure hash_access_code as follows:

SELECT hash_access_code(campaignId, username);

Here's a partial example of what that looks like:

Page access

Example format of the secure page-access URLs provided to users:

https://hub.hubzero.org/newsletter/pages/2?campaign=CAMPAIGNID&user=USERNAME&code=CODE_FROM_hash_access_code

Subscription access

https://hub.hubzero.org/newsletter/email-subscriptions?campaign=CAMPAIGNID&user=USERNAME&code=CODE_FROM_hash_access_code

Management of the one-click pages, subscriptions, and related tables is no different than it was on nanoHUB, except that any hardcoding of the Hub name was replaced. Management of pages is largely manual and no change to that was scoped in this work (see README section below).

This is an example of the one-click "email subscription" page following successful validation:

Testing

This work was tested on a developer AWS instance. At the stage of this PR, testing concentrated on behavior when different URLs were provided. In particular:

• sensible messages on failure to validate
• sensible messages on success
• failure to validate on encountering an expired campaign or nonexistent user
• navigation to correct page
• submission of correct page or emailsubscription and update of database entry
• no privileged access of other pages or Hub locations is enabled

Generation of codes via the stored procedure was also tested.

The README

The following is the updated README taken from the custom com_reply component. I reproduce it here to provide context on the work that was done.

Reply functionality: single-click validation

Use Case

"Reply" functionality allows users to submit survey responses or update their preferences without first completing the primary hub authentication procedure.

This feature provides user authentication via hashes of randomly-generated codes that are associated with the user's CMS record, the campaign, and the Hub.

This functionality is now part of the com_newsletter core component. It was originally found in custom component com_reply.

Related features:

All management of these features is found under the Hub's administrator interface.

• Per-user randomly generated codes are managed under Member password management.
• Per-campaign randomly generated codes are managed under the Newsletter component's Campaign tab, on the administrative interface.
• The Hub's randomly generated code is managed under Global Configuration on the administrative interface.

Install

1. Run the migrations e.g. via muse migration run ...

Adding a Page

It is assumed that all users providing correct credentials will have access to all pages.

To add a form-based page:

1. Add a record to jos_reply_pages
2. Create a view for the page in site/views/pages

Adding an Email Subscription Option

1. Create or confirm name of the corresponding profile field
2. Add a record to jos_email_subscriptions
3. Create a view (content to appear beneath label) if desired
4. Set the email page ID in secrets/code.php, using secrets/code_example.php as a model.
   • The page ID key is referenced in CodeHelper.php validateEmailSubscriptionsCode().

Gotchas

• jos_email_subscriptions.profile_field_name must correspond with a jos_user_profile_fields.name
• jos_user_profile_options must be populated for the user profile fields. jos_user_profile_options.field_id must correspond with id from jos_user_profile_fields.id
• jos_users user codes are provided at login time by the core Hubzero members plugin.
• Hashed access codes are provided by the stored procedure, which can be accessed from the database. It takes two arguments, campaign.id and jos_users.username

Component-Specific Tables

• jos_reply_pages - pages for collecting data
• jos_reply_replies - user-submitted responses
• jos_email_subscriptions - email subscription options

Access-Related Tables

• jos_users - contains a secret for each user
• campaign - contains a secret for each campaign, with expiration date
• jos_config - the value column for scope='hub' and key='secret' contains the overall secret for the Hub

Integrations

The email subscription update functionality integrates with the core user profile data.

• jos_user_profile_fields - profile fields
• jos_user_profile_options - profile field response options
• jos_user_profiles - associates user data with profile fields

Generating Access Codes

The stored procedure hash_access_code is used to generate and verify codes for page access. Codes are used in URLs as shown below.

Example URLs

Here:

• USERNAME is the user's jos_user.username
• CAMPAIGNID is campaign.id

pages

Format of links for page access:

https://jsperhac.aws.hubzero.org/newsletter/pages/2?campaign=CAMPAIGNID&user=USERNAME&code=CODE_FROM_hash_access_code

subscriptions

Format of links for so-called subscription access:

https://jsperhac.aws.hubzero.org/newsletter/email-subscriptions?campaign=CAMPAIGNID&user=USERNAME&code=CODE_FROM_hash_access_code

[jsperhac]

I've addressed your blocking change requests:

• updated table name from 'campaign' to 'jos_campaign' (commit 57035c7)
• renamed any com_reply migration files that had dates prior to 2023 in their names (commit b1b0538)

While doing this I saw a couple of things that needed to be addressed:

1. Three migration files create and/or modify tables that are not in use in the code. These have been removed and the README.md (documentation) updated. (commit b850c84)
2. Display campaign id in admin UI, so admin user can easily determine it (commit acf60c7)

I've tested all this stuff on my AWS instance.