Password Security Configuration - Documentation topics on: changing user passwords,configuration properties,password dictionary,password expiration,password recycling,password security,regular expression,security,security policy,.

Password Security Configuration

When a user attempts to change their password, the new password entered by the user is checked to ensure it meets a number of acceptability criteria regarding length, acceptable and required characters, time before expiration, and time (if any) before previously used passwords can be re-used.

Important Note

The dotCMS distribution is configured by default with minimal security to ease installation, evaluation, and testing of the dotCMS starter site. Therefore the default values of all password validation properties are set to the minimum security levels.
It is strongly recommended that you increase the password security settings for your site before publishing it.

You may change the values for all password acceptance criteria by editing the Passwords section of the file (/dotserver/tomcat-X.x/webapps/ROOT/WEB-INF/classes/

Note: it is strongly recommended that all changes to the file be made through a Root folder plugin.

Validation Parameters

The following parameters configure how the contents of passwords are validated. These parameters determine what constitutes a valid password, and what passwords the system will reject when a user attempts to use them.

Regular Expression Validation

The default password validator enables you to specify a regular expression to validate passwords. All new passwords created must match the specified regular expression before the new password will be saved. To change the regular expression used to validate passwords, modify the passwords.regexptoolkit.pattern property.

    # This pattern ensures that passwords must have between 6 and 20 valid
    # characters:
    #           1. may contains digits from 0-9
    #           2. may contain lowercase characters
    #           3. may contain uppercase characters
    #           4. may contain special symbols in the list "@#$%"
    #           5. may **not** contain spaces
    #           6. match anything with previous condition checking 
    #              length is at least 6 characters
    # This pattern ensures that passwords must have at least 6 characters and no spaces


  • If the regular expression used for validation is changed, then you must also change the Validation Messages (used to notify users when their new password doesn't match the regular expression).
  • ““\” is replaced with “\\” to work in Java.
  • For more information on how to use regular expressions, please see the Java regular expression class documentation.

Password Validator (Password Toolkit)

Instead of using the default (regular expression) validator, you may change the library used to validate passwords to implement and enforce alternate or custom password rules. To change the password validator library, you must create the new password library and then replace the value of the passwords.toolkit property with the class name of the validator to use. The default value of the property is shown below:

    # Input a class name that extends com.liferay.portal.pwd.BasicToolkit. This
    # class will be called to generate and validate passwords.


  • The default password validator is com.liferay.portal.pwd.RegExpToolkit.
  • The class used for the passwords.toolkit property must extend the com.liferay.portal.pwd.BasicToolkit class.

Allow Dictionary Words

Passwords that consist only of regular words in a dictionary are very easy to break with a simple brute force password attack. For this reason, you may wish to change the passwords.allow.dictionary.word property to false, to reject passwords which exist in the dictionary.

    # Set the following to true if passwords can be a dictionary word.

Additional Requirements

The following parameters may be used to provide additional limitations and requirements on user passwords beyond the contents of the password.

Change Password on First Login

It's common security practice to force users to change their passwords the first time they login, to ensure that users don't continue using simple default passwords provided by administrators. To force users to change their passwords the first time they login, change the passwords.change.on.first.use property to true:

    # Set the following to true if users ought to change their passwords on
    # first use when an Administrator creates their account.

Password Expiration

By default, passwords do not expire. You may configure passwords to expire after a set time period, forcing users to change their passwords periodically. Once a user password expires, the user will be able to use their password to login only once more, and at that time will then be prompted to change their password before they are allowed to login. To change the password expiration, set the value (in days) of the passwords.lifespan property.

    # Set the number of days that will pass before users are prompted to change
    # their password. Set the number of days to 0 if passwords never expire. 

Password Recycling / Password Dictionary

When using Password Expiration, you may wish to reject passwords that users have used previously, to prevent users with expired passwords from immediately changing their password back to the expired password. The passwords.recycle property allows you to set the minimum time (in days) before a user can re-use any password. When this property is set, all a user's previous passwords are kept in an internal password dictionary, and the user is prevented from re-using any previous password until the specified recycle period has expired for that password.

    # Set the number of days that must have passed before a password is allowed
    # to be recycled and used again. Set the number of days to 0 if passwords
    # can always be reused.

Validation Messages

When a user's choice for a password is rejected, a message is displayed based on the reason for the rejection. If you change the validation methods, you must also change the messages to match the new validation requirements, or the messages received by the user will be incorrect.

The password validation messages are specified in the file via the passwords.regexptoolkit.pattern.error and passwords.recycle.error properties.


The values of both of these properties specify names of language properties which are specified in the language properties files (in /dotserver/Tomcat-X.xx/webapps/ROOT/WEB-INF/messages/). You must change the values of the two listed language properties in the file to match the changes you've made to the validation methods (such as the Regular Expression Validation property).

Multilingual Support

In addition to the file, if you wish to support additional languages on the dotCMS backend, you must also change the values of the two specified language properties in the language properties files for the additional languages you wish to support. For example, if you wish to support Spanish on your site backend, you will need to also change the values of the User-Info-Save-Password-Failed and User-Info-Save-Password-Recycle-Failed properties in the file.

Note: It is strongly recommended that all changes to the language properties files be made via a Root folder plugin.


  • The Password Recycling parameter (passwords.recycle) is most valuable when it is set to a longer time period than the Password Expiration parameter (passwords.lifespan).
    • Otherwise, when a user's password expires, the user will be able to immediately change their password back to the previous password.
  • Changes to the Password Validation parameters (passwords.toolkit and passwords.regexptoolkit.pattern) will only be applied to new passwords.
    • When password validation rules are changed, users with existing passwords will not be forced to change their passwords to conform to new requirements (until their passwords expire).
  • dotCMS passwords are stored with on-the-fly upgradable encryption, utilizing per-user salting and complex hashing with multiple iterations.
    • For more information on the details of password security, please contact dotCMS support.