Password Reset

Overview

m-Power’s built in Dictionary Security is a commonly used feature by developers who need to put security in front of their runtime application. Offered within m-Power’s dictionary security option is the ability to include a built-in Password Reset feature, which allows application users to manage their own passwords in the event they cannot login due to a forgotten password.

This documentation will apply to any developers sswho met the following two requirements:

• You are validating end-user sign on against a database table (using validation_type = 5).
• You are not using Single Sign On (SSO) for end-user authentication.

m-Power’s Password Reset functionality cannot be utilized in data dictionaries which utilize SSO (including Oauth2 and SAML) for user authentication.

For more on m-Power’s Dictionary Security, please see here.

Implementation

Initial Setup

Your m-Power environment must be on the July 2023 update or later to utilize the Password Reset feature. To update your m-Power environment, please see here.

The Password Reset feature may be implemented in existing or new data dictionaries. To begin, navigate to Admin -> Menu & Security -> Edit Security Settings and click on the ‘Password Reset’ section to bring up the following options:

If this “Password Reset” section does not show in your security settings screen for an existing data dictionary (as shown in Figure 1), they must be manually added to this file. Any of the password reset screens will also need to be moved into the dictionary folder.

Please follow the next section “Update an Existing Dictionary“, if these properties were not listed. Otherwise, please continue further on with the implementation instructions.

Updating an Existing Dictionary

To manually add these properties, select the Property Options -> Text Mode option to open the mrcSignon2.xml file.

Copy and paste the entire block of code below before the <applications> tag in the mrcSignon2.xml file.

<password_reset>
<!-- Set enabled="true" to enable password reset functionality in this data dictionary. -->
<!-- Certain conditions must be satisfied before the reset functionality is allowed: -->
<!-- 1. SSO is not being used. -->
<!-- 2. The Validation Type 5 is being used. -->
  <enabled value="false" />
  <reset_link_text value="Forgot Password?" />
  <email_subject value="You requested a password reset" />    
  <email_address_column value="USEREMAIL" /> 
  <token_expiry_duration value="20" />
<!-- Used to check password strength on the reset password pages. -->
  <requires_min_length value="5"/>
  <requires_special_chars value="false"/> 
  <requires_digits value="false" />
  <requires_mixed_case value="false"/>
  <allows_spaces value="true" />
</password_reset>

Example:

Ensure to press the ‘Save’ option once added and restart Tomcat.

Additionally, please copy the following HTML files from …/m-power/mrcjava/mrcclasses/ into …/m-power/mrcjava/WEB-INF/classes/DICTIONARY, where ‘DICTIONARY’ is the name of your data dictionary.

• mrcSignon2.html (Signon Page)
• mrcSignonPasswordReset.html (Password Reset Page)
• mrcSignonPasswordResetEmail.html (Password Reset Email Body)
• mrcSignonPasswordResetRequest.html (Password Reset Request Page)

Property Configuration

By default, the Password Reset feature is disabled. To enable it, set the ‘Enable password reset?’ property to True.

The other properties shown in Figure 3 will be discussed in-depth here.

• Enable Password Reset? – Enables or disables the password reset functionality. This property will appropriately show or hide the reset link on the end-user sign on page depending if it’s set to true or false.
• Password reset link text – On the login page a password reset link appears that can be clicked on to initiate the password reset process. This property sets the text of that link.
• Password reset email subject – The text here will be the subject line of the password reset email sent to the end-user.
• Email address database column name – Specify the column in your database table that contains the users’ email addresses. Note this can be the userid/username column of your table, if users’ usernames are their email addresses.
• Token expiry duration (minutes) – Once a user has requested their password reset, the value here indicates how long (in minutes) the password reset token is good for. Default value is 20.
• Password minimum length – The minimum length of the password. Enter 0 if there is no minimum length requirement.
• Password requires special character – If set to True, the password is required to have at least one special character. If set to False, a special character is not required. Characters include, but are not limited to !@#$%*.
• Password requires upper and lowercase letters – Control whether or not passwords are required to have at least one upper case and one lower case letter. If set to True, one of each is required. If set to False, there are no specific case requirements.
• Spaces allowed? – Whether or not to allow spaces in passwords
  

Once any property changes have been made, please save the security settings and restart Tomcat.

Runtime Usage

At runtime, when enabled the password reset option will be on the end-user sign on screen:

Once submitted, a user will receive an email with a link to reset their password. This link will only be valid for as long as the Token expiry duration was set for.

Clicking on the “Reset Password” link in Figure 6 will return the user to browser, in which the new password will be specified. All requirements, as setup during the property configuration step above, will be listed visibly for the user to see.

Any requirements, if not met with be indicated on the screen when a user attempts to validate their new password. Once the password has been reset, the user will be prompted to go back to the dictionary login screen.

Customizations

Appearance

Developers who want to customize the screens of their password reset feature may do so by navigating to Admin -> Menu & Security -> Edit sign on screen HTML.

Pressing the ‘Switch’ option at the top of the editor will allow developers to customize the look and feel of the following pages:

• mrcSignon2.html (Signon Page)
• mrcSignonPasswordReset.html (Password Reset Page)
• mrcSignonPasswordResetEmail.html (Password Reset Email Body)
• mrcSignonPasswordResetRequest.html (Password Reset Request Page)

Encryption

The password reset feature supports using a non-encrypted or encrypted (ex. SHA-256) password column. The password reset feature will automatically encrypt reset passwords, granted the encryption_type="xxxx" attribute is present on the <validateby_table> tag within the mrcSignon2.xml.

For more information on setting up encryption, please see here.

Utilizing your own security table

The Password Reset feature is designed to work with m-Power’s innate application users table, the MRCSEC1 table. If wanting to use the password reset feature against your own database table with users and passwords, please contact mrc for more information.

Promoting to Production

To promote to production, the following files will need to be promoted. All of these files can be found in ../m-power/mrcjava/WEB-INF/classes/DICTIONARY, where ‘DICTIONARY‘ is the name of the data dictionary.

• mrcSignon2.xml (Security Settings)
• mrcSignon2.html (Signon Page)
• mrcSignonPasswordReset.html (Password Reset Page)
• mrcSignonPasswordResetEmail.html (Password Reset Email Body)
• mrcSignonPasswordResetRequest.html (Password Reset Request Page)