Summary
ClinSpark can be configured to support the ability for users to reset their own passwords. The implementation of feature set follows an industry best practice.
This is an optional system setting. Once enabled, it applies to all user accounts.
Note that this workflow does not apply for user accounts utilizing SSO login/authentication mechanisms.
Demonstration
https://vimeo.com/585094576/6adeab94ae
Prerequisites
AWS SES
Starting in ClinSpark version 1.5.0, password reset is supported through AWS Simple Email Service (SES), and no longer relies on SendGrid.
The AWS SES configuration is managed by Foundry Health.
Google reCAPTCHA
Google reCAPTCHA site keys must be established for this feature, because it is used as an anti-spam protection.
This configuration is customer specific and must be put in place by Foundry Health ‘superadmin’ users. If you are unsure of the state of this configuration, please reach out via service desk for support.
Password Reset Email Template
A password reset email template must be configured. By default, all customer environments will have a standard (default) template established, so there is typically no setup required.
Additional details on this template are presented later in this article.
User Account ‘Email Address’
All users that wish to use the password reset feature must have a valid email address defined as part of their profile. Without a defined email address, the feature will not work.
Setup
Users logged in with a role containing ‘Administration General Settings’ role action must setup a Password Reset Timeout duration within Administration > General Settings.
Defining this value enables the password reset feature.
This timeout value will determine how long users have to reset their password after the email has been sent.
Workflow
The ‘Email Password Reset’ link will become visible to users after they’ve failed login at least one time.
Additionally, users can navigate directly to the password reset page by appending their instance URL with ‘/emailreset’. For example: https://customer.clinspark.com/emailreset
Users are required to provide a valid email address, associated with the ClinSpark user account, to submit a password reset request. Additionally, they must pass the reCAPTCHA challenge.
Users will receive a confirmation that the password reset process has been initiated, with instructions sent to the email address provided.
Users will check their email inbox to review instructions to continue with password reset.
Once users click on the ‘Reset your password’ link in the email, they’ll be brought back to ClinSpark Password Reset screen. The password reset link provided via e-mail expires after the configured timeout period set in Administration > General Settings.
Upon updating their password, users will be logged into ClinSpark with their updated credentials.
Common Workflow Error Scenarios
If the password reset workflow is not working as described, there are some common error scenarios to review that may help resolve issues.
User waits too long to click the reset link in the email
The reset link provided will only be active for the amount of time defined as part of the system setup (timeout value). Users must click this link before it expires.
If this is a common occurrence, one consideration is to increase the timeout limit defined as part of the configuration under Administration > General Settings > Communications.
User clicks the link in the email multiple times
The reset link in the email (button and URL) is designed to only be accessed one time. After the link has been clicked, it cannot be used again. Users must re-initiate the password reset workflow from the ClinSpark login screen again if the link is no longer active.
Emails are flagged as ‘Junk’ or ‘Spam’
Password reset e-mails may be flagged as ‘Spam’ or ‘Junk’, depending on how filtering rules are applied for the user’s individual inbox or their organization’s mail provider. It is suggested that users be on the lookout for the password reset e-mails and mark them as ‘Not Junk/Spam’ if received as such.
Emails are never received into user inbox
Site organization mail providers have filtering rules in place that would intercept messages coming from an unknown domain or sender. While the password reset emails are safe and legitimate, site IT departments may need to ensure these emails are not blocked. Email messages may come from those defined as part of Administration > General Settings > Communications > E-mail.
Additionally, IT departments may need to whitelist emails and traffic coming from SendGrid, where password reset email links are routed.
Users cannot initiate the password reset workflow
There are some possibilities leading to this scenario:
Users do not have an email addressed defined in their ClinSpark account. A valid email address must be present on the user account requesting a password reset.
The system setting for ‘password reset timeout duration’ is not set. This setting must have a defined value in order for the password reset functionally to work.
Sites have the option of providing background images to appear at the ClinSpark login screen. Some background images may make it difficult to see the ‘reset password’ link once it becomes active. These images can be changed if necessary.
Modifying the email template
The default password reset email template present in customer configurations should be sufficient for all users of the application. It is based off the ‘Basic’ template layout provided by the Postmark open source project, present here: https://github.com/wildbit/postmark-templates
Some customers may have a desire to modify the template in minor ways to address things such as the styling, layout, and text.
FH engineering staff are able to modify these templates through a protected global configuration setting called ‘PasswordResetEmailTemplate’. We may accommodate changes upon review and request via the Service Desk.