From da059fe870cb5d04c9945a9ced611fdc4ab9c5a0 Mon Sep 17 00:00:00 2001
From: Mark Story <mark@mark-story.com>
Date: Mon, 29 Jun 2026 22:21:26 -0400
Subject: [PATCH] Improve documentation for CookieAuthenticator

Increase the strength of the recommendation to use
EncryptedCookieMiddleware. Without encryption remember-me cookies are
vulernable to tampering by end users.
---
 docs/en/authenticators.md                 | 21 +++++++++++++++++----
 src/Authenticator/CookieAuthenticator.php |  3 +++
 2 files changed, 20 insertions(+), 4 deletions(-)

diff --git a/docs/en/authenticators.md b/docs/en/authenticators.md
index d94f04f4..c5ff4baf 100644
--- a/docs/en/authenticators.md
+++ b/docs/en/authenticators.md
@@ -326,9 +326,10 @@ feature for your login forms.
 Just make sure your login form has a field that matches the field name
 that is configured in this authenticator.
 
-To encrypt and decrypt your cookie make sure you added the
-EncryptedCookieMiddleware to your app *before* the
-AuthenticationMiddleware.
+> [!WARNING]
+> You must enable `EncryptedCookieMiddleware` and add the cookie authenticator `name`
+> to the encrypted cookie list before using `CookieAuthenticator`.
+> Without encryption, remember me cookie values can be tampered with.
 
 Configuration options:
 
@@ -372,7 +373,19 @@ The cookie authenticator can be added to a Form & Session based
 authentication system. Cookie authentication will automatically re-login users
 after their session expires for as long as the cookie is valid. If a user is
 explicitly logged out via `AuthenticationComponent::logout()` the
-authentication cookie is **also destroyed**. An example configuration would be:
+authentication cookie is **also destroyed**.  Before enabling CookieAuthentication, first
+enable `EncryptedCookieMiddleware`:
+
+```php
+// In Application::middleware()
+use Cake\Http\Middleware\EncryptedCookieMiddleware;
+
+$middlewareQueue->add(
+    new EncryptedCookieMiddleware(['CookieAuth'], Configure::read('Security.cookieKey'))
+);
+```
+
+Then add `CookieAuthenticator` to your authentication service configuration:
 
 ```php
 // In Application::getAuthenticationService()
diff --git a/src/Authenticator/CookieAuthenticator.php b/src/Authenticator/CookieAuthenticator.php
index f53e4f57..68deaeae 100644
--- a/src/Authenticator/CookieAuthenticator.php
+++ b/src/Authenticator/CookieAuthenticator.php
@@ -33,6 +33,9 @@
  * Cookie Authenticator
  *
  * Authenticates an identity based on a cookie data.
+ *
+ * You *must* enable encrypted cookies with `EncryptedCookieMiddleware` before using CookieAuthenticator.
+ * Without encryption remember-me cookie values can be tampered with.
  */
 class CookieAuthenticator extends AbstractAuthenticator implements PersistenceInterface
 {