Password Reset
To allow users to regain access to their account when they forgot their password we need to enable them to reset their password.
Note: The Mail Configuration has to be done for password retrieval mails to be sent.
MailTemplates
The password reset mail is constructed from multiple MailTemplate
(see MailTemplate) objects.
MailTemplate name | Used as | Default value |
---|---|---|
RESET_PASSWORD_SUBJECT |
Subject line | Request to reset your Structr password |
RESET_PASSWORD_SENDER_NAME |
Sender name | Structr Mail Daemon |
RESET_PASSWORD_SENDER_ADDRESS |
Sender address | structr-mail-daemon@localhost |
RESET_PASSWORD_TEXT_BODY |
Plaintext mail body | Go to ${link} to reset your password. |
RESET_PASSWORD_HTML_BODY |
HTML mail body | <div>Click <a href='${link}'>here</a> to reset your password.</div> |
RESET_PASSWORD_BASE_URL |
Used to build the link variable |
${concat("http://", application.host, ":", application.http.port)} (see structr.conf) |
RESET_PASSWORD_CONFIRM_KEY_KEY |
key parameter name in the link variable. Allows the user to be logged in once without a password. |
key |
RESET_PASSWORD_TARGET_PAGE_KEY |
target parameter name in the link variable. |
target |
RESET_PASSWORD_TARGET_PAGE |
target parameter value in the link variable. Specifies the redirect page after successful login. |
/reset-password |
Technical Note: The visibility flags of these mail templates is irrelevant as the password reset mail is created as a privileged user.
Example link
variable: https://support.structr.com/reset-password?key=<PASSWORD-RESET-KEY>&target=/reset-password
Note: Since all necessary templates have defaults none of them is strictly necessary but in order to deliver a better user experience at least the first three are recommended.
Requesting a password reset
The process is multi-step:
-
The user needs to request a “Reset password” mail by
POST
ing his email address to/structr/rest/reset-password
as follows{ eMail: "user.name@mail.com" }
-
If the email address exists in the user database the password reset mail (constructed according to the above definitions) will be sent to the specified address
-
Upon clicking the link the user will be logged in and redirected to the specified
target
page where he can change his password -
The user can now change his password by
PUT
ting a new password to/structr/rest/me
(see Static Resources){ password: "newSuperSecurePassword" }
Note: The key JsonRestServlet.user.autologin
in structr.conf needs to be set to true
in order for the user to be auto-logged in.
Note: The authentication key
is valid once and deleted after usage. The user could also decide to use the application without changing his password as he is now logged in.
Note: For step 1 and 4 to work the correct Resource Access Grants must be configured:
- POST
ing to resetPassword
must to be allowed for public users (Grant Signature: _resetPassword
)
- PUT
ting to me
must to be allowed for authenticated users (Grant Signature: User
)
Note: Steps 1 and 4 are usually done using JavaScript / jQuery / AJAX and are left for the reader to implement.