Add AuthenticationComponent::replaceIdentity()

docs/en/authentication-component.md

@@ -102,6 +102,60 @@ The result returned will contain an array like this:
 > context you're working in you'll have to use these instances from now on if you
 > want to continue to work with the modified response and request objects.
 
+## Replacing the current identity
+
+Use `setIdentity()` to change which user is logged in (e.g. after registration
+or social-login first-touch). It clears all persisted identity data and writes
+the new identity through every persisting authenticator:
+
+```php
+$this->Authentication->setIdentity($user);
+```
+
+> [!WARNING]
+> `setIdentity()` ends an active impersonation session by default, because it
+> goes through `clearIdentity()` first, which calls `stopImpersonating()` on
+> impersonation-aware authenticators. See the two methods below for the
+> non-default cases.
+
+### Refresh the active identity for the current request only
+
+When you only need to swap the in-request identity (for example to attach
+eager-loaded associations or computed flags in `beforeFilter()`) without
+touching the session or persistence, use `replaceIdentity()`:
+
+```php
+// AppController::beforeFilter()
+$identity = $this->Authentication->getIdentity();
+if ($identity && !$identity->some_association) {
+    $reloaded = $this->fetchTable('Users')
+        ->get($identity->getIdentifier(), finder: 'fullProfile');
+    $this->Authentication->replaceIdentity($reloaded);
+}
+```
+
+This rewrites only the request attribute. The session is not modified, so an
+active impersonation is preserved and no privilege-escalation side effects
+(like session rotation) occur.
+
+### Persist a refreshed identity while impersonating
+
+If the refresh has to survive into subsequent requests but you still want to
+keep an active impersonation alive, pass `preserveImpersonation: true` to
+`setIdentity()`:
+
+```php
+$this->Authentication->setIdentity($reloaded, preserveImpersonation: true);
+```
+
+The new identity is persisted into the session as usual, but the
+impersonation slot (`AuthImpersonate`) and the active authenticator are left
+intact. Note that this also skips the session rotation that the default
+`setIdentity()` flow performs - it is a refresh, not a privilege transition,
+so do not use it for login or role changes.
+
+See [User Impersonation](impersonation.md) for the broader context.
+
 ## Configure Automatic Identity Checks
 
 By default `AuthenticationComponent` will automatically enforce an identity to

docs/en/impersonation.md

@@ -67,3 +67,23 @@ There are a few limitations to impersonation.
 1. Your application must be using the `Session` authenticator.
 2. You cannot impersonate another user while impersonation is active. Instead
     you must `stopImpersonating()` and then start it again.
+3. Calling `setIdentity()` or `clearIdentity()` (and therefore `logout()`)
+    ends impersonation by default. The service's `clearIdentity()` actively
+    calls `stopImpersonating()` on impersonation-aware authenticators, so any
+    code path that swaps the persisted identity will revert to the original
+    user.
+
+    To refresh the active identity without disturbing impersonation, use one
+    of the dedicated methods on `AuthenticationComponent`:
+
+    - `replaceIdentity($identity)` updates the in-request identity attribute
+      only. The session is not touched. Use this for the common
+      `beforeFilter()` case of attaching eager-loaded associations to the
+      active user for the rest of the request.
+    - `setIdentity($identity, preserveImpersonation: true)` persists the new
+      identity into the session like the default flow, but keeps the
+      impersonation slot intact. Use this when the refresh has to survive
+      into subsequent requests.
+
+    See [Replacing the current identity](authentication-component.md#replacing-the-current-identity)
+    for examples.

src/AuthenticationService.php

@@ -184,22 +184,36 @@ public function authenticate(ServerRequestInterface $request): ResultInterface
      *
      * @param \Psr\Http\Message\ServerRequestInterface $request The request.
      * @param \Psr\Http\Message\ResponseInterface $response The response.
+     * @param bool $stopImpersonation Whether to stop an active impersonation
+     *  before clearing each authenticator. Defaults to true (existing
+     *  behavior). Pass false to keep the impersonation session intact - the
+     *  authenticator's `clearIdentity()` is still called, but
+     *  `stopImpersonating()` is not.
      * @return array Return an array containing the request and response objects.
      * @return array{request: \Psr\Http\Message\ServerRequestInterface, response: \Psr\Http\Message\ResponseInterface}
      */
-    public function clearIdentity(ServerRequestInterface $request, ResponseInterface $response): array
-    {
+    public function clearIdentity(
+        ServerRequestInterface $request,
+        ResponseInterface $response,
+        bool $stopImpersonation = true,
+    ): array {
         foreach ($this->authenticators() as $authenticator) {
             if ($authenticator instanceof PersistenceInterface) {
-                if ($authenticator instanceof ImpersonationInterface && $authenticator->isImpersonating($request)) {
+                if (
+                    $stopImpersonation
+                    && $authenticator instanceof ImpersonationInterface
+                    && $authenticator->isImpersonating($request)
+                ) {
                     $stopImpersonationResult = $authenticator->stopImpersonating($request, $response);
                     ['request' => $request, 'response' => $response] = $stopImpersonationResult;
                 }
                 $result = $authenticator->clearIdentity($request, $response);
                 ['request' => $request, 'response' => $response] = $result;
             }
         }
-        $this->_successfulAuthenticator = null;
+        if ($stopImpersonation) {
+            $this->_successfulAuthenticator = null;
+        }
 
         return [
             'request' => $request->withoutAttribute($this->getConfig('identityAttribute')),
@@ -501,6 +515,10 @@ public function stopImpersonating(ServerRequestInterface $request, ResponseInter
      */
     public function isImpersonating(ServerRequestInterface $request): bool
     {
+        if (!$this->getAuthenticationProvider() instanceof AuthenticatorInterface) {
+            return false;
+        }
+
         $provider = $this->getImpersonationProvider();
 
         return $provider->isImpersonating($request);

src/AuthenticationServiceInterface.php

@@ -21,6 +21,9 @@
 use Authentication\Authenticator\ResultInterface;
 use Psr\Http\Message\ServerRequestInterface;
 
+/**
+ * @method \Authentication\IdentityInterface buildIdentity(\ArrayAccess<string, mixed>|array<string, mixed> $identityData) Build an identity object from raw identity data.
+ */
 interface AuthenticationServiceInterface extends PersistenceInterface
 {
     /**

src/Controller/Component/AuthenticationComponent.php

@@ -18,6 +18,7 @@
 
 use ArrayAccess;
 use ArrayObject;
+use Authentication\AuthenticationService;
 use Authentication\AuthenticationServiceInterface;
 use Authentication\Authenticator\AuthenticatorInterface;
 use Authentication\Authenticator\ImpersonationInterface;
@@ -299,15 +300,34 @@ public function getIdentityData(string $path): mixed
      * is cleared and then set to ensure that privilege escalation
      * and de-escalation include side effects like session rotation.
      *
+     * Pass `$preserveImpersonation = true` to keep an active impersonation
+     * session alive while replacing the identity. The active authenticators'
+     * `clearIdentity()` is still called (so the new identity properly
+     * overwrites the existing one in storage), but the impersonation slot is
+     * left intact. Use this when refreshing the active impersonated user
+     * (for example, attaching eager-loaded associations) without ending the
+     * impersonation.
+     *
      * @param \ArrayAccess|array $identity Identity data to persist.
+     * @param bool $preserveImpersonation Whether to keep an active
+     *  impersonation alive while replacing the identity. Defaults to false
+     *  (existing behavior).
      * @return $this
      */
-    public function setIdentity(ArrayAccess|array $identity)
+    public function setIdentity(ArrayAccess|array $identity, bool $preserveImpersonation = false)
     {
         $controller = $this->getController();
         $service = $this->getAuthenticationService();
 
-        $service->clearIdentity($controller->getRequest(), $controller->getResponse());
+        if ($preserveImpersonation && $service instanceof AuthenticationService) {
+            $service->clearIdentity(
+                $controller->getRequest(),
+                $controller->getResponse(),
+                stopImpersonation: false,
+            );
+        } else {
+            $service->clearIdentity($controller->getRequest(), $controller->getResponse());
+        }
 
         /** @var array{request: \Cake\Http\ServerRequest, response: \Cake\Http\Response} $result */
         $result = $service->persistIdentity(
@@ -322,6 +342,38 @@ public function setIdentity(ArrayAccess|array $identity)
         return $this;
     }
 
+    /**
+     * Replace the in-request identity object without persisting it.
+     *
+     * Use this when you only need to swap the identity attribute on the
+     * current request - for example, to attach eager-loaded associations
+     * or computed flags to the active user for the rest of the request -
+     * without going through `clearIdentity()` and `persistIdentity()`.
+     *
+     * Unlike `setIdentity()`, this does not touch the session and does not
+     * end an active impersonation, because no authenticator's
+     * `clearIdentity()` is invoked.
+     *
+     * @param \ArrayAccess|array $identity Identity data or an identity object.
+     * @return $this
+     */
+    public function replaceIdentity(ArrayAccess|array $identity)
+    {
+        $controller = $this->getController();
+        $service = $this->getAuthenticationService();
+
+        $identity = $service->buildIdentity($identity);
+
+        $controller->setRequest(
+            $controller->getRequest()->withAttribute(
+                $service->getIdentityAttribute(),
+                $identity,
+            ),
+        );
+
+        return $this;
+    }
+
     /**
      * Log a user out.
      *