Password policies

New in version 12.0.

Introduction

TYPO3 includes a password policy validator which can be used to validate passwords against configurable password policies. A default password policy is included which ensures that passwords meet the following requirements:

  • At least 8 characters

  • At least one number

  • At least one upper case character

  • At least one special character

  • It must be different than current password (if available)

Password policies can be configured individually for both frontend and backend context. It is also possible to extend a password policy with custom validation requirements.

The password policy applies to:

  • Creating a backend user during installation

  • Setting a new password for a backend user in User settings

  • Resetting a password for a backend user

  • Resetting a password for a frontend user (see also the feature toggle "security.usePasswordPolicyForFrontendUsers")

  • Password fields in tables be_users and fe_users

Optionally, a password policy can be configured for custom TCA fields of the type password.

Note

During the development of TYPO3 v12 LTS more areas are added where the password policy is considered.

Configuring password policies

A password policy is defined in the TYPO3 global configuration. Each policy must have a unique identifier (the identifier default is reserved by TYPO3) and must at least contain one validator.

The password policy identifier is used to assign the defined password policy to the backend and/or frontend context. By default, TYPO3 uses the password policy default:

config/system/settings.php | typo3conf/system/settings.php
$GLOBALS['TYPO3_CONF_VARS']['BE']['passwordPolicy'] = 'default';
$GLOBALS['TYPO3_CONF_VARS']['FE']['passwordPolicy'] = 'default';

A custom password policy with the identifier simple can be configured like:

config/system/additional.php | typo3conf/system/additional.php
$GLOBALS['TYPO3_CONF_VARS']['SYS']['passwordPolicies'] = [
    'simple' => [
        'validators' => [
            \TYPO3\CMS\Core\PasswordPolicy\Validator\CorePasswordValidator::class => [
                'options' => [
                    'minimumLength' => 6,
                ],
            ],
        ],
    ],
];

Then assign the custom password policy simple to frontend and/or backend context:

config/system/settings.php | typo3conf/system/settings.php
$GLOBALS['TYPO3_CONF_VARS']['BE']['passwordPolicy'] = 'simple';
$GLOBALS['TYPO3_CONF_VARS']['FE']['passwordPolicy'] = 'simple';

Attention

When implementing a custom password policy please refer to the secure password guidelines.

Password policy validators

TYPO3 ships with two password policy validators, which are both used in the default password policy.

\TYPO3\CMS\Core\PasswordPolicy\Validator\CorePasswordValidator

This validator has the ability to ensure a complex password with a defined minimum length and four individual requirements.

The following options are available:

minimumLength
Type

int

Default

8

The minimum length of a given password.

upperCaseCharacterRequired
Type

bool

Default

false

If set to true at least one upper case character (A-Z) is required.

lowerCaseCharacterRequired
Type

bool

Default

false

If set to true at least one lower case character (a-z) is required.

digitCharacterRequired
Type

bool

Default

false

If set to true at least one digit character (0-9) is required.

specialCharacterRequired
Type

bool

Default

false

If set to true at least one special character (not 0-9, a-z, A-Z) is required.

\TYPO3\CMS\Core\PasswordPolicy\Validator\NotCurrentPasswordValidator

This validator can be used to ensure, that the new user password is not equal to the old password. The validator must always be configured with the exclude action \TYPO3\CMS\Core\PasswordPolicy\PasswordPolicyAction::NEW_USER_PASSWORD, because it should be excluded, when a new user account is created.

Disable password policies globally

To disable the password policy globally (e.g. for local development) an empty string has to be supplied as password policy for frontend and backend context:

config/system/additional.php | typo3conf/system/additional.php
if (\TYPO3\CMS\Core\Core\Environment::getContext()->isDevelopment()) {
    $GLOBALS['TYPO3_CONF_VARS']['BE']['passwordPolicy'] = '';
    $GLOBALS['TYPO3_CONF_VARS']['FE']['passwordPolicy'] = '';
}

Warning

Do not deactivate the password policies on a production server as this decreases security massively. In the example above the deactivation of the password policies is wrapped into a condition which is only applied in development context.

Custom password validator

To create a custom password validator, a new class has to be added which extends \TYPO3\CMS\Core\PasswordPolicy\Validator\AbstractPasswordValidator. It is required to overwrite the following functions:

  • public function initializeRequirements(): void

  • public function validate(string $password, ?ContextData $contextData = null): bool

Please refer to \TYPO3\CMS\Core\PasswordPolicy\Validator\CorePasswordValidator for a detailed implementation example.

Event

The following PSR-14 event is available: