The checkCredentials hook is triggered when a login attempt fails due to a wrong password. It passes the username and password as well as the user object as arguments and expects a boolean as return value which indicates whether the credentials are correct or not. If the return value is false, other hooks of the same type will still be executed.

Using the checkCredentials hook has been deprecated and will no longer work in Contao 5.0.


  1. string $username

    The username submitted from the login form.

  2. string $credentials

    The password submitted from the login form.

  3. \Contao\User $user

    User object model from database record with the given username.

Return Values

Return true if the credentials are valid, false otherwise.


// src/EventListener/CheckCredentialsListener.php
namespace App\EventListener;

use Contao\CoreBundle\DependencyInjection\Attribute\AsHook;
use Contao\User;

class CheckCredentialsListener
    public function __invoke(string $username, string $credentials, User $user): bool
        // Custom method of checking credentials (e.g. external service)
        if ($this->customCredentialsCheck($username, $credentials)) {
            // More custom logic …

            return true;

        return false;