CakePHP Authentication 4: build a secure login in CakePHP 5

To add login to a CakePHP 5 application in October 2026, install cakephp/authentication 4.x, add AuthenticationMiddleware after routing and body parsing, and configure a Session plus Form authenticator with a Password identifier. Version 4 changed how identifiers are configured, so most 3.x tutorials and Stack Overflow answers no longer copy-paste cleanly.

This tutorial builds a complete email-and-password login on the current release line (4.2.1, published 10 July 2026): service configuration, login and logout actions, password hashing, a safe post-login redirect, an optional “remember me” cookie and an integration test. The last section lists the 3.x to 4.x changes you need if you are upgrading an existing app.

What you need

• A CakePHP 5 application. The current cakephp/app skeleton targets CakePHP 5.4, which needs PHP 8.2 or later. The plugin itself declares PHP 8.1+ and cakephp/http ^5.0.
• A users table with at least id, email and password columns. The password column must be long enough for a bcrypt or Argon2 hash; VARCHAR(255) is the safe choice.
• The CSRF middleware that ships with the skeleton left switched on. Login forms are a classic CSRF target.

Install and load the plugin from the project root:

composer require cakephp/authentication:^4.0
bin/cake plugin load Authentication

Wire the middleware in the right order

Authentication runs as PSR-15 middleware. Order matters: it must come after RoutingMiddleware (so array-style login URLs can be matched) and BodyParserMiddleware (so JSON logins are readable). The official docs call out middleware order as the first thing to check when redirects or JSON logins misbehave.

// src/Application.php
public function middleware(MiddlewareQueue $middlewareQueue): MiddlewareQueue
{
    $middlewareQueue
        ->add(new ErrorHandlerMiddleware(Configure::read('Error'), $this))
        ->add(new HostHeaderMiddleware())
        ->add(new AssetMiddleware(['cacheTime' => Configure::read('Asset.cacheTime')]))
        ->add(new RoutingMiddleware($this))
        ->add(new BodyParserMiddleware())
        ->add(new CsrfProtectionMiddleware(['httponly' => true]))
        ->add(new AuthenticationMiddleware($this));

    return $middlewareQueue;
}

Your Application class must also implement AuthenticationServiceProviderInterface, which the middleware calls once per request to get a configured service.

Configure the authentication service

This is where 4.x differs most from older tutorials. There is no loadIdentifier() on the service any more: each authenticator receives its own identifier through the identifier option, and the credential constants now live on PasswordIdentifier.

use Authentication\AuthenticationService;
use Authentication\AuthenticationServiceInterface;
use Authentication\AuthenticationServiceProviderInterface;
use Authentication\Identifier\PasswordIdentifier;
use Cake\Routing\Router;
use Psr\Http\Message\ServerRequestInterface;

public function getAuthenticationService(ServerRequestInterface $request): AuthenticationServiceInterface
{
    $service = new AuthenticationService();
    $service->setConfig([
        'unauthenticatedRedirect' => Router::url(['prefix' => false, 'plugin' => false, 'controller' => 'Users', 'action' => 'login']),
        'queryParam' => 'redirect',
    ]);

    $fields = [
        PasswordIdentifier::CREDENTIAL_USERNAME => 'email',
        PasswordIdentifier::CREDENTIAL_PASSWORD => 'password',
    ];

    // Session first: once logged in, the identity is read from the session.
    $service->loadAuthenticator('Authentication.Session');
    $service->loadAuthenticator('Authentication.Form', [
        'identifier' => [
            'className' => 'Authentication.Password',
            'fields' => $fields,
        ],
        'fields' => $fields,
        'loginUrl' => Router::url(['prefix' => false, 'plugin' => false, 'controller' => 'Users', 'action' => 'login']),
    ]);

    return $service;
}

Authenticators run in order until one succeeds. Session reads the identity stored at login; Form only acts on the login URL and passes the posted email and password to the Password identifier, which looks the user up through the ORM and verifies the hash.

Session or PrimaryKeySession?

The plain Session authenticator stores the whole user entity in the session and trusts it on later requests. If you need roles or an “is active” flag to take effect immediately, use PrimaryKeySession instead: it stores only the primary key and reloads the user on every request. In 4.x this replaces the removed identify option of Session.

$service->loadAuthenticator('Authentication.PrimaryKeySession');

Require login with the component

Load the component in AppController. From then on every action requires an authenticated identity unless you opt it out.

// src/Controller/AppController.php
public function initialize(): void
{
    parent::initialize();
    $this->loadComponent('Flash');
    $this->loadComponent('Authentication.Authentication');
}

Public actions are listed per controller in beforeFilter():

// src/Controller/UsersController.php
public function beforeFilter(\Cake\Event\EventInterface $event): void
{
    parent::beforeFilter($event);
    $this->Authentication->allowUnauthenticated(['login', 'add']);
}

Write the login and logout actions

The middleware has already tried to authenticate the request by the time your action runs, so the login action only inspects the result. Since 4.1.0 the component has redirectAfterLogin(), which sends the user to the validated redirect query parameter or to the default you pass. Use it instead of reading ?redirect= yourself; passing raw query strings to redirect() creates an open redirect.

public function login(): ?\Cake\Http\Response
{
    $this->request->allowMethod(['get', 'post']);
    $result = $this->Authentication->getResult();

    if ($result && $result->isValid()) {
        return $this->Authentication->redirectAfterLogin('/dashboard');
    }
    if ($this->request->is('post')) {
        $this->Flash->error(__('Invalid email or password'));
    }

    return null;
}

public function logout(): \Cake\Http\Response
{
    $this->Authentication->logout();

    return $this->redirect(['controller' => 'Users', 'action' => 'login']);
}

Keep the error message generic. Saying whether the email or the password was wrong lets attackers enumerate accounts. The template is an ordinary form; FormHelper adds the CSRF token automatically:

<?= $this->Form->create() ?>
<?= $this->Form->control('email', ['type' => 'email', 'autocomplete' => 'username']) ?>
<?= $this->Form->control('password', ['autocomplete' => 'current-password']) ?>
<?= $this->Form->button(__('Log in')) ?>
<?= $this->Form->end() ?>

Log out with a POST link ($this->Form->postLink()) rather than a plain GET link, so a third-party page cannot log your users out.

Hash passwords on save

The Password identifier uses DefaultPasswordHasher, which calls PHP’s password_hash() with PASSWORD_DEFAULT (bcrypt today). Hash in an entity mutator so that every save path is covered:

// src/Model/Entity/User.php
namespace App\Model\Entity;

use Authentication\PasswordHasher\DefaultPasswordHasher;
use Cake\ORM\Entity;

class User extends Entity
{
    protected array $_accessible = ['email' => true, 'password' => true];
    protected array $_hidden = ['password'];

    protected function _setPassword(string $password): string
    {
        return (new DefaultPasswordHasher())->hash($password);
    }
}

$_hidden keeps the hash out of JSON output and of any view that serialises the user. Never make id or role columns mass-assignable through $_accessible.

Migrating legacy hashes

If you are inheriting MD5 or SHA1 hashes from an older system, configure the identifier with Authentication.Fallback listing Authentication.Default first and Authentication.Legacy second. After a successful login, check $authentication->getIdentificationProvider()->needsPasswordRehash() and save the plain password again so it is re-hashed with bcrypt. The plugin documentation shows the full pattern.

Add “remember me” safely

The Cookie authenticator re-logs users in after their session expires. It must be paired with EncryptedCookieMiddleware; without encryption the cookie can be tampered with. Add the middleware with the cookie name, then load the authenticator after Form and Session:

$middlewareQueue->add(new EncryptedCookieMiddleware(['CookieAuth'], Configure::read('Security.cookieKey')));

$service->loadAuthenticator('Authentication.Cookie', [
    'identifier' => 'Authentication.Password',
    'fields' => $fields,
    'loginUrl' => '/users/login',
]);

Add a remember_me checkbox to the login form. The cookie stores the username and a hashed token, and calling logout() destroys it. Security.cookieKey is your own configuration key; store a long random value in an environment variable, never in a committed file. Release 4.2.1 also hardened how these cookie tokens are generated, which is one more reason to stay on the latest 4.x patch.

Test the protected pages

In integration tests you do not need to post the login form. Put a user into the session under the default Auth key and request the page:

use Cake\TestSuite\IntegrationTestTrait;
use Cake\TestSuite\TestCase;

class DashboardControllerTest extends TestCase
{
    use IntegrationTestTrait;

    protected array $fixtures = ['app.Users'];

    public function testRedirectsGuests(): void
    {
        $this->get('/dashboard');
        $this->assertRedirectContains('/users/login');
    }

    public function testShowsDashboardToUser(): void
    {
        $user = $this->fetchTable('Users')->get(1);
        $this->session(['Auth' => $user]);
        $this->get('/dashboard');
        $this->assertResponseOk();
    }
}

If you switched to PrimaryKeySession, store the key instead: $this->session(['Auth' => 1]). For POST tests, call $this->enableCsrfToken() first.

Upgrading from Authentication 3.x

Version 4.0.0 was released on 9 February 2026. The official upgrade guide lists these breaking changes:

Most applications only need the first three rows: a search-and-replace for the constants and moving identifier config into the Form authenticator. Multi-language sites with several login URLs must add the Multi URL checker or logins on the extra URLs silently stop working.

Gotchas

• Login always fails with correct credentials. Check the fields mapping on both the identifier and the authenticator, and that the stored password is a hash, not plain text.
• JSON logins fail. BodyParserMiddleware must come before AuthenticationMiddleware.
• Redirect loop on the login page. The login action is missing from allowUnauthenticated().
• Authorization next. Authentication only answers “who is this?”. Use the separate cakephp/authorization plugin to decide what that user may do.

What to do next

1. Pin cakephp/authentication to ^4.2 and run composer update to pick up the cookie-token hardening.
2. Add rate limiting or a lockout in front of the login action; the plugin does not throttle attempts.
3. Write one integration test per protected controller that asserts guests are redirected.