Kentico CMS 7.0 Developer's Guide

Password recovery

Password recovery

Previous topic Next topic Mail us feedback on this topic!  

Password recovery

Previous topic Next topic JavaScript is required for the print function Mail us feedback on this topic!  

If a user forgets their password, they may retrieve or reset it, provided they have access to the e‑mail address specified for their account. A password may be recovered by submitting a request through one of the website's logon forms.


By default, a forgotten password button is included on the logon page of the CMS Desk and Site Manager administration interface.




You can hide the button by adding the following key to the /configuration/appSettings section of your web.config file:


<add key="CMSShowForgottenPassLink" value="false" />


On the live site, users can recover their password through Logon form web parts that have their Allow forgotten password retrieval property enabled.




When submitting the request, users can either type in their user name or e‑mail address. If a user name is entered, the recovery e‑mail will be sent to the given account's address. In cases where an address is used, the request will affect the password of the user account with the corresponding address. Password recovery e‑mails are sent from the address specified in the Send password e-mails from setting.


Depending on the value of the Reset password requires e‑mail approval setting, one of two possible password recovery modes will be used.


Password reset without e-mail approval


If the Reset password requires e‑mail approval setting is disabled, then users who request their password will receive an e‑mail containing the password directly. If the current password format is plain text, the existing password will be sent to the user. If an encrypted password format is used, the system will generate a new password for the user.


Password reset with e-mail approval


If the Reset password requires e‑mail approval setting is enabled, several steps will be added to the process. Users who submit a password recovery request through a logon form will first receive an e‑mail containing a link to a page where they can manually set a new password. This option is more secure, because the password cannot be read from the e‑mail by potential attackers. Also, the reset link is only valid temporarily. The time period during which the link is valid can be specified in hours by the Reset password interval setting.


When a user clicks the link in the e‑mail, they will be redirected to the default ~/CMSModules/Membership/CMSPages/ResetPassword.aspx system page, where they will be able to enter a new password. The URL of the link contains a token in its query string that automatically identifies the user whose password should be changed. After someone visits the link, it becomes invalid and cannot be accessed again.


If you wish to use a custom page for this purpose, simply create a new page on the website according to your specific requirements and place the Reset password web part on it. This web part displays a form with the same functionality as described above for the ResetPassword.aspx system page. After you create the page, enter its URL into the Reset password page URL website setting, or into the same property of individual Logon form web parts.


If the Send e‑mail with reset password setting is enabled, users will receive another e‑mail containing their new password once they successfully reset it.





Global administrator password


If you happen to lose the password for your administrator account and cannot access the management interface, you can use on of the following techniques to recover:


Reset password via web.config key - insert the following key to the appSettings section of your web.config:


<add key="CMSAdminEmergencyReset" value="<your username>;<your new password>;[true/false]" />


The first and second parameter specify your user name and your new password, delimited by a semicolon. The third parameter is optional and indicates whether you want to create a new user with global administrator rights.


The key will be automatically deleted after you gain access to the user interface.


Clear password in database - find your user record in the CMS_User table and clear the contents of the UserPassword column. Then sign in to the administration interface with a blank password and set a new password.



Password recovery e‑mail templates


The e‑mails sent to users during the password retrieval process are based on E-mail templates, which can be found in Site manager -> Administration -> E‑mail templates. The following password‑related templates are available:


Membership - Forgotten password - sent to users when they use the password recovery feature and the Reset password requires e‑mail approval setting is disabled.

Membership - Change password request - sent as a reply to password recovery requests if Reset password requires e‑mail approval is enabled.

Membership - Changed password - sent to users if their password is changed by an administrator, either manually or by generating a new one.

Membership - Resend password - used if the current password information is sent to a user from the administration interface (this can only be done if passwords are stored in plain text format).


These templates can be edited as needed, so you may fully customize the content of the e‑mails. You can enter the following context macros to include dynamic values in their text:


{% UserName %} - the name of the user's account. If you are using site prefixes for user names, all occurrences of this macro in e‑mail templates can have the prefix trimmed out with the following method: {%TrimSitePrefix(UserName)%}

{% Password %} - the current (new) password of the given user.

{% LogonURL %} - returns the URL of the page where the retrieval password request was submitted. Only available in the Forgotten password template.


The two macros below are available specifically in the Change password request template:


{% ResetPasswordURL %} - resolves into the URL of the page where the user can change their password.

{% CancelURL %} - returns the URL of a page that will cancel the request when opened. This can be used to create links that users can click in situations where someone else requested a new password for their user account (either intentionally or accidentally).


In addition to the special ones listed above, you can also use all other standard macro expressions in the templates. See the Development -> Macro expressions chapter of this guide for more information about macro expressions in Kentico CMS.