Kentico CMS 6.0 Developer's Guide

Password settings

Password settings

Previous topic Next topic Mail us feedback on this topic!  

Password settings

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

Passwords are a critical part of any authentication process, so Kentico CMS provides various password‑related configuration options that you can adjust according to the level of security required by your website. These settings can be found in Site Manager -> Settings -> Security & Membership -> Passwords.




Password format


There are multiple different formats that can be used to store passwords in the database. They may either be saved in plain text or as the result of a security hash function. You can choose which option should be used via the Password format setting.


By default, passwords are stored using the SHA2 hash format with the additional application of a salt. This option is recommended, since it provides the best security. A salt is a string that is appended to passwords before they are hashed, which helps protect against dictionary or other types of brute force attacks, and also ensures that every user has a different password hash (even if multiple users have the same password). The randomly generated GUID of each user is assigned as the salt for the password. If you wish to further increase the length of the salt, you can add the following key to the /configuration/appSettings section of your web.config file:


<add key="CMSPasswordSalt" value="SaltText" />


The value of this key will be added to the salt after the user GUID.


If you change the password format, please keep in mind that this only affects how future passwords are stored and existing passwords will remain unchanged. It is necessary to set all passwords again so that they are stored in the new format. For this reason, it is recommended to set the appropriate format directly after the installation, before you create user accounts or allow users to start registering.


Forgotten password recovery


If a user forgets their password, they may retrieve or reset it as long as they have access to the e‑mail address specified for the given account. This can be done 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.




If necessary, the button can be hidden by adding the following key to the /configuration/appSettings section of your web.config file:


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


On the live site, password recovery may be performed 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:


If it is disabled, then users who request their password will receive an e‑mail containing the password directly. The current password will be sent if it is stored in plain text, or a new one will be generated for the user account if a hashed password format is used.


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 and the reset link is only valid temporarily (also, it can only be used to reset the password once).


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 into a form. The URL of the link contains a token in its query string that automatically identifies the user whose password should be changed. For security reasons, this link will only remain valid for a limited amount of time after the initial request (12 hours by default). Once the link expires, it will no longer be possible to change the password through it. You can set the exact length of the expiration interval in the Reset password interval setting.


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. The URL of the custom page must then be entered 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 recover by editing the database directly:


If you're using plain text passwords, you can read or change the password in the CMS_User table.

If you're using hashed passwords, you need to set the password in the CMS_User table to an empty string. Then, you can sign in to Site Manager with an empty password and change the password as necessary.


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 should have the prefix trimmed out through 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.


Password strength policy


The system can be configured to use a password policy, which means that new passwords entered by users will be validated according to a certain set of requirements. Passwords that do not meet the specified conditions will be rejected.


To enforce a password policy on your website, enable the Use password policy setting. The specific rules of the policy can be configured through the remaining settings in the category:


Minimal length - sets the minimum number of total characters required for user passwords.

Number of non alphanumeric characters - sets the minimum number of non alphanumeric characters (i.e. any character except for numbers and letters) that must be present in a password in order for it to be accepted.

Regular expression - can be used to enter a regular expression that will be used to validate user passwords. For example: ^(?=.*\d)(?=.*[a-z])(?=.*[A-Z]).*$
This sample expression would require passwords to contain at least one lower case letter, upper case letter and number. The minimum amount of characters would be determined by the other policy settings.


The requirements defined by all three settings are combined together to form the final password policy.


The policy is applied in all sections of the website where a new password can be entered. This includes various types of web parts that display forms on the live site, such as My account or the Registration form, and the administration interface (Administration -> Users). The requirements of the policy, except for the regular expression, are additionally observed when the system automatically generates new passwords. This is also the case if the Use password policy setting is disabled, so you can affect how passwords should be generated even if you do not wish to set a policy for your website's users.


When a user types in a password, it is validated in real time and its status is reflected by an indicator below the field. If a policy is set, passwords that do not fulfill the requirements will be rejected with the Not acceptable status.




Valid passwords will have a different status displayed according to their relative strength, which is calculated based on the recommended values for the total password length (12 by default) and number of non alphanumeric characters (2 by default). If a password policy is not enabled for the website, the current strength status of passwords will still be shown, but only as a recommendation and all passwords will be accepted.


To help users come up with an appropriate password, you can use the Policy violation message setting to specify a text message that will be displayed to users who attempt to enter a password that does not fulfill the requirements of the password policy. If left empty, a default message will be shown, informing about the minimum password length and number of non alphanumeric characters. If you wish to use a regular expression, it is recommended to describe its requirements in a custom message. If your site has multiple cultures (languages) assigned to it, you can enter a different message for each language via the Localize (AddNewUICulture) action available next to the setting's field.




Customizing the password strength indicator


You can change the recommended values that are used to calculate the password strength by editing the code of the appropriate controls:


To set different values globally for the entire application, edit the code behind of the ~/CMSModules/Membership/FormControls/Passwords/PasswordStrength.ascx control and enter different numbers into the mPreferedLength and mPreferedNonAlphaNumChars variables.


You can also override the values for specific instances where this control is used through its PreferedLength and PreferedNonAlphaNumChars properties (e.g. in the code of the Registration form web part).


The appearance of individual password strength status labels may be customized through CSS styles. Each one has a different class assigned, e.g. PasswordStrengthNotAcceptable




Password policy and strength in custom forms


When creating custom forms, you can easily add password fields that validate according to the specified policy and display password strength.


To do this, specify either the Password strength or Password with confirmation form control for the given field, which will automatically ensure the functionality described above.