User Password Security Configuration

Last Updated: Oct 23, 2019
documentation for the dotCMS Content Management System

When a user attempts to change their password, the new password entered by the user is checked to ensure it meets the password acceptability criteria regarding length and acceptable and required characters.

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 value for the 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 properties file extension.

Validation Parameters

The following parameters configure how new passwords are validated. These parameters determine what constitutes a valid password (e.g. what passwords the system will reject when a user attempts to save a new password) and what message is displayed to a user when they enter a password that doesn't meet the minimum requirements.

Regular Expression Validation

Passwords are validated by checking to see if the password matches the value of a regular expression you specify. 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 Message (used to notify users when a 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.

Validation Message

When a user's choice for a password is rejected, a message is displayed informing them of the minimum password requirements. If you change the regular expression used to validate passwords, you must also change the validation error message to match the new regular expression requirements, or the message received by the user will be incorrect.

The password validation message is specified in the file via the passwords.regexptoolkit.pattern.error property:


This property specifies the name of a language property which is specified in the language properties files (in /dotserver/Tomcat-X.xx/webapps/ROOT/WEB-INF/messages/). You must change the value of the listed language property in the file to match the changes you've made to 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 value of the validation message language property 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 must also add or change the value of the User-Info-Save-Password-Failed property in the file.

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


  • Changes to the Password Validation parameter (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.
  • 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.

External Authentication Systems

The above validation methods are included by default in dotCMS. If you wish to do more advanced password validation, such as password expiration and password dictionaries, you can integrate dotCMS with an external authentical system such as SAML or a custom extensible authentication plugin.

For more information on the details of integrating dotCMS with an external authentication system, please contact dotCMS support.

On this page


We Dig Feedback

Selected excerpt: