The Forgot Password module enables the users to sign up and also to reset their password. It works with the local accounts which are managed within your Mendix App. These accounts are the best choice when you do not want to use a single sign-on (SSO) solution to integrate with your existing identity and access management (IAM) infrastructure.
This module allows the end-user to enter their email address, and an email will be sent with a confirmation link. The end-user then opens the link and gets the option to reset their password in both scenarios (sign up and forgot password). In the sign up case, the end-user is also asked to provide their name. For version 5.3.0 and above of the module, you can specify different templates to be sent, depending on the language in which the end-user is seeing the app.
There are below versions of the Forgot Password module, depending on whether you are using Mendix Studio Pro 8, or 9 and above. These all work in the same way, and require the dependencies specified below.
Mendix Version
Forgot Password Version
10.21.01 and above
6.4.0
10.12.10 and above
6.1.0
10.6.0 and above
6.0.0
9.20.0 and above
5.1.0
9.12.7 and above
5.x.x
8.18.x
4.x.x
If you already use the Forgot Password module in your Mendix 8 app, you can find instructions on how to upgrade in Upgrading from Mendix 8 to Mendix 9 section below.
Dependencies
The Forgot Password module has the following dependencies:
Community Commons (For Email Connector module version 6.3.0 and above)
Features
Allows end-users to reset the password stored locally in your app
Allows end-users to sign up for your app by validating that the end-user has access to the email address they enter by sending a password reset email
Supports email aliases, in other words, the from address in email templates can be different from the SMTP account used to send the email
Supports multi-language email templates for sending password reset emails
Automatically deletes expired or previously used password reset links.
Supports multi-instance apps (horizontal scaling)
Limitation
When changing the encryption key for the Encryption module, all previously sent password reset email links become invalid. Users must request a new password reset link.
Installing the Forgot Password Module
In these instructions, it is assumed that your main module is MyFirstModule. If you are using a different module name, use that instead of MyFirstModule.
Add the Dependencies listed above from the Marketplace.
You can accept any warnings about files being overwritten.
Open the App Settings and make the following changes:
In the Configurations tab, edit the current configuration to add a 32-character string value for the constant Encryption.EncryptionKey.
In the Runtime tab, add the microflow Deeplink.StartDeeplink and ForgotPassword.ASU_Startup as the After startup microflow or as a sub-microflow to an existing after startup microflow.
For the Forgot Password module version 6.0.0 (Mendix 10.6.0 and above), do not add the Deeplink.StartDeeplink microflow as the After startup microflow.
If you are changing the URL prefix value in the Runtime tab, ensure that you use the same value in the URLPrefix constant of the Forgot Password module. Otherwise, the signup and reset URLs will not work.
In the User roles tab, add a new role called Guest in MyFirstModule
Do not set any Deep Link userroles in the App security for the version 6.0.0 (Mendix 10.6.0 and above).
Set the following permissions for the user roles:
Administrator
Administration.Administrator
DeepLink.Admin
Email_Connector.EmailConnectorAdmin or EmailTemplate.Administrator - Email_Connector permissions are needed if you are using version 4.1.0 or above (for Mendix 8) or version 5.1.0 or above (for Mendix 9 and above). EmailTemplate permissions are only needed if using a version which uses the deprecated Email Module with Templates module
Encryption.user
ForgotPassword.Administrator
MxModelReflection.ModelAdministrator
System.Administrator
MyFirstModule.Administrator
Guest
DeepLink.User
ForgotPassword.Guest_ResetPassword
ForgotPassword.Guest_SignUp
System.User
MyFirstModule.Guest
User
Administration.User
DeepLink.User
ForgotPassword.Guest_ResetPassword
MxModelReflection.Readonly
MxModelReflection.TokenUser
System.User
MyFirstModule.User
In the Anonymous users tab, set Allow Anonymous users to Yes
Set Role-based home pages so the target of user role Guest is ForgotPassword.Nav_GuestHomePage
The Nav_GuestHomePage microflow is the home page for an anonymous user. This microflow either shows the login page or triggers the deep link process which performs the reset password function.
Add the menu item ForgotPasswordConfiguration to the app navigation. Link this item to the ForgotPassword.ForgotPasswordConfiguration_Edit page and assign it to the Administrator user role.
The ForgotPasswordConfiguration page should be accessible to the administrator only. It allows the administrator to configure the email template and deep link, and it shows all the open password reset requests.
For version 6.3.0 and above of the Forgot Password module, go to the Edit tab of the Studio Pro, click New features, and disable the Access Rules editor. Then, open the Module Security for the Email_Connector module in the Marketplace. In the Entity Access tab, assign read-only access to the Email_Connector.EmailConnectorAdmin module role for the EmailTemplateLanguage_EmailTemplate template. If you are using version 5.3.0 or above of the module, you do not need to disable the Access Rules Editor and can proceed with the remaining steps as described above.
Run the application.
Sign in as demo_administrator from Demo Users and choose the ForgotPasswordConfiguration menu item.
In the Reset Password Email tab, do the following:
Click SMTP settings to configure or validate SMTP settings for the Email Connector or Email Module with Templates module (depending on the version of the Forgot Password module). In version 5.4.0 and above this will create a SMTP configuration which you will need to select.
In version 5.4.0 and above, select the SMTP configuration you want to use for sending reset password email.
From the drop-down menu, choose the Reset email template tab and provide the details for the email to be sent when an end-user has forgotten their password.
For version 5.3.0 and above, you can Create and Edit several reset email templates. Each template is linked to a language you have added to your app. Based on the language in which end-user sees the app, the associated template will be used to send the reset email. If no template is explicitly associated with the end-user's language, the template which is not associated with any language will be used. For versions below 5.3.0, you can only set up a single template.
For version 5.4.0 and above, the fromAddress in the email template does not have to be the same as the address in your SMTP configuration. For more information, see Using Email Aliases section below.
In the Signup Email tab, provide the details for the email to be sent when an end-user wants to sign up. These options are same as described above, for the Reset Password Email tab.
To disable the sign up functionality and use the Forgot Password module only for resetting passwords, do the following:
Remove the Sign-up button from the LoginSnippet snippet in the _Use Me folder of the Forgot Password Marketplace module.
Remove all the actions from the CreateNewUserFromSignUp microflow.
In the Deeplink tab, configure the deeplink to use the ForgotPassword.Step3_DL_SetNewPassword microflow.
The Deeplink tab is not available in version 6.0.0 (for Mendix 10.6.0 and above) as the Deep Link module has been deprecated.
Using Email Aliases
From version 5.4.0 of the Forgot Password module, the fromAddress used in the email template does not have to be the same as the email address in the SMTP configuration. This provides flexibility, allowing you to send emails from different addresses while utilizing the same SMTP configuration for authentication.
Consider a scenario, where your SMTP username is user@example.com and you have configured this account in your SMTP configuration. You could set the fromAddress in your email template to be any email address or alias you have control over, such as sales@example.com, support@example.com, or ceo@example.com, and this is what the recipient will see in the email they receive.
You may have to configure an email alias on your SMTP server if you are using a different fromAddress in your email template than the email address of your selected SMTP account. Some SMTP servers will not send emails if the fromAddress is not associated with the SMTP account.
Testing the Forgot Password Module
Sign out of the app.
On the sign in page, click Signup.
Enter your name and email ID and click Send. You will get confirmation that a password recovery email has been sent.
You will receive an email containing a link to reset your password.
Open the link in the browser. You can now reset your password.
Upgrading to a Later Version
Follow the sections below to upgrade your Mendix app to later version.
Upgrading from Mendix 8 to Mendix 9
To convert the Mendix 8.18.x to Mendix 9.12.5 or above, follow the steps below:
Upgrade all the dependencies of the Forgot Password module to the latest version compatible with Mendix 9.
Open your app in Mendix 9.12.5 or above and allow it to be upgraded.
Use these instructions before you upgrade the Forgot Password module. The point at which you should get the new version is included in the steps below.
Dependencies
Migrating to Email Connector Module has the following dependencies:
An app that uses Mendix 8 or above.
The email templates must be set up as follows:
The reset password template must contain _Reset in the template name.
The signup template must contain _Signup in the template name.
Migration Process
Importing Additional Modules
Import the modules which are needed for the migration process.
Add the following user roles to the Administrator user role:
Email_Connector.EmailConnectorAdmin
MigrationUtility.EmailConnectorMigrationUtilAdmin
Performing Migration
Follow the Migration Steps in the GitHub repo of the community-supported Email Connector Migration Utility tool to configure the migration utility and migrate the data from the Email Module with Templates module to the Email connector module.
Actions After the Migration
Import the latest version of the Forgot Password module (v4.1.0 or above for Mendix 8, or v5.1.0 or above for Mendix 9 and above). This will have the Email Connector module as a dependency.
Remove the Administrator user roles for EmailTemplate and MigrationUtility.
Remove any module roles related to EmailTemplate and MigrationUtility.
Check the userlib folder in your app directory and remove the Java*.jars* related to the Email Module with Templates module as indicated by a .EmailTemplate.RequiredLib file (for example, activation-1.1.1.jar and the related activation-1.1.1.jar.EmailTemplate.RequiredLib).
What Happens If the Email Templates Don't Have the Right Names?
Associations between Email-connector.EmailTemplate and ForgotPassword.Configuration will not be migrated and you will not be able to see your existing templates. You will have to create the templates again.
What Happens If the Database Contains More than One Template with the Same Template Name?
Only the first one found during the migration will be associated with the Email Connector configuration.
What Happens If I Click Start Migration on the ETToEC Overview Page Multiple Times?
Your data will be migrated multiple times and duplicate records will be created in the database.
What Should I Do If My Email Templates Are Not Available after Migration?
You will have to create templates again using the Forgot Password configuration page, as described in Installing the Forgot Password Module section above.
