feat: replace token-based impersonation with enterprise-grade header-based system
Replaces the insecure token-in-localStorage approach with a header-based impersonation system backed by cache sessions and MFA verification. Key changes: - New impersonation_sessions audit table (immutable, ULID PK) - MFA verification required to start impersonation (TOTP/email/backup) - X-Impersonate-User header + HandleImpersonation middleware - Per-request auth context swap (admin session never modified) - IP pinning, sensitive route blocking, no nesting, sliding 60-min TTL - Activity log auto-tagged with impersonated_by during sessions - Frontend: sessionStorage, BroadcastChannel sync, countdown timer - ImpersonateDialog with reason + MFA verification flow - 26 comprehensive tests covering core, middleware, audit, lifecycle Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
This commit is contained in:
@@ -4,39 +4,114 @@ declare(strict_types=1);
|
||||
|
||||
namespace App\Http\Controllers\Api\V1\Admin;
|
||||
|
||||
use App\Enums\MfaMethod;
|
||||
use App\Http\Controllers\Controller;
|
||||
use App\Http\Requests\Admin\StartImpersonationRequest;
|
||||
use App\Http\Resources\Admin\AdminUserResource;
|
||||
use App\Http\Resources\Admin\ImpersonationSessionResource;
|
||||
use App\Models\User;
|
||||
use App\Services\ImpersonationService;
|
||||
use App\Services\MfaService;
|
||||
use Illuminate\Http\JsonResponse;
|
||||
use Illuminate\Http\Request;
|
||||
|
||||
final class AdminImpersonationController extends Controller
|
||||
{
|
||||
public function __construct(
|
||||
private readonly ImpersonationService $impersonationService,
|
||||
private readonly MfaService $mfaService,
|
||||
) {}
|
||||
|
||||
public function start(User $user): JsonResponse
|
||||
/**
|
||||
* Start impersonating a user.
|
||||
* POST /admin/impersonate/{user}
|
||||
*/
|
||||
public function start(StartImpersonationRequest $request, User $user): JsonResponse
|
||||
{
|
||||
/** @var User $admin */
|
||||
$admin = auth()->user();
|
||||
$result = $this->impersonationService->start($admin, $user);
|
||||
|
||||
$session = $this->impersonationService->start(
|
||||
admin: $admin,
|
||||
targetUser: $user,
|
||||
reason: $request->validated('reason'),
|
||||
mfaCode: $request->validated('mfa_code'),
|
||||
mfaMethod: MfaMethod::from($request->validated('mfa_method')),
|
||||
ipAddress: $request->ip(),
|
||||
userAgent: $request->userAgent(),
|
||||
);
|
||||
|
||||
$session->load('targetUser.organisations');
|
||||
|
||||
return $this->success([
|
||||
'token' => $result['token'],
|
||||
'user' => new AdminUserResource($result['user']->load('organisations')),
|
||||
'admin_id' => $result['admin_id'],
|
||||
'session' => new ImpersonationSessionResource($session),
|
||||
'user' => new AdminUserResource($session->targetUser),
|
||||
]);
|
||||
}
|
||||
|
||||
public function stop(): JsonResponse
|
||||
/**
|
||||
* Stop impersonation.
|
||||
* POST /admin/stop-impersonation
|
||||
* Called by the admin (without X-Impersonate-User header).
|
||||
*/
|
||||
public function stop(Request $request): JsonResponse
|
||||
{
|
||||
/** @var User $currentUser */
|
||||
$currentUser = auth()->user();
|
||||
$admin = $this->impersonationService->stop($currentUser);
|
||||
/** @var User $admin */
|
||||
$admin = $request->user();
|
||||
|
||||
$session = $this->impersonationService->getActiveSessionForAdmin($admin);
|
||||
|
||||
if (! $session) {
|
||||
return $this->error('No active impersonation session.', 400);
|
||||
}
|
||||
|
||||
$this->impersonationService->stop($session);
|
||||
|
||||
return $this->success([
|
||||
'user' => new AdminUserResource($admin->load('organisations')),
|
||||
]);
|
||||
}
|
||||
|
||||
/**
|
||||
* Get impersonation status.
|
||||
* GET /admin/impersonate/status
|
||||
*/
|
||||
public function status(Request $request): JsonResponse
|
||||
{
|
||||
/** @var User $admin */
|
||||
$admin = $request->user();
|
||||
|
||||
$session = $this->impersonationService->getActiveSessionForAdmin($admin);
|
||||
|
||||
if (! $session) {
|
||||
return $this->success([
|
||||
'active' => false,
|
||||
]);
|
||||
}
|
||||
|
||||
$session->load('targetUser');
|
||||
|
||||
return $this->success([
|
||||
'active' => true,
|
||||
'session' => new ImpersonationSessionResource($session),
|
||||
]);
|
||||
}
|
||||
|
||||
/**
|
||||
* Send MFA email code for impersonation verification.
|
||||
* POST /admin/impersonate/send-mfa-code
|
||||
*/
|
||||
public function sendMfaCode(Request $request): JsonResponse
|
||||
{
|
||||
/** @var User $admin */
|
||||
$admin = $request->user();
|
||||
|
||||
if (! $admin->mfa_enabled) {
|
||||
return $this->error('MFA is not enabled.', 403);
|
||||
}
|
||||
|
||||
$this->mfaService->sendEmailCode($admin);
|
||||
|
||||
return $this->success(null, 'Verification code sent.');
|
||||
}
|
||||
}
|
||||
|
||||
112
api/app/Http/Middleware/HandleImpersonation.php
Normal file
112
api/app/Http/Middleware/HandleImpersonation.php
Normal file
@@ -0,0 +1,112 @@
|
||||
<?php
|
||||
|
||||
declare(strict_types=1);
|
||||
|
||||
namespace App\Http\Middleware;
|
||||
|
||||
use App\Services\ImpersonationService;
|
||||
use App\Models\User;
|
||||
use Closure;
|
||||
use Illuminate\Http\Request;
|
||||
use Illuminate\Support\Facades\Log;
|
||||
use Symfony\Component\HttpFoundation\Response;
|
||||
|
||||
class HandleImpersonation
|
||||
{
|
||||
/**
|
||||
* Routes that are blocked during impersonation.
|
||||
* These are prefix-matched against the request path (without api/v1 prefix).
|
||||
*/
|
||||
private const SENSITIVE_ROUTE_PREFIXES = [
|
||||
'auth/password',
|
||||
'auth/logout',
|
||||
'auth/mfa',
|
||||
'auth/trusted-devices',
|
||||
'me/profile',
|
||||
'me/change-password',
|
||||
'me/change-email',
|
||||
'admin/impersonate',
|
||||
'verify-email-change',
|
||||
];
|
||||
|
||||
public function __construct(
|
||||
private readonly ImpersonationService $impersonationService,
|
||||
) {}
|
||||
|
||||
public function handle(Request $request, Closure $next): Response
|
||||
{
|
||||
$targetUserId = $request->header('X-Impersonate-User');
|
||||
|
||||
if (! $targetUserId) {
|
||||
return $next($request);
|
||||
}
|
||||
|
||||
/** @var User|null $admin */
|
||||
$admin = $request->user();
|
||||
|
||||
if (! $admin) {
|
||||
return response()->json(['message' => 'Authentication required.'], 401);
|
||||
}
|
||||
|
||||
// Block sensitive routes during impersonation
|
||||
if ($this->isSensitiveRoute($request)) {
|
||||
return response()->json([
|
||||
'message' => 'This action is not allowed during impersonation.',
|
||||
], 403);
|
||||
}
|
||||
|
||||
// Validate impersonation session via Redis
|
||||
$session = $this->impersonationService->validateRequest(
|
||||
$admin->id,
|
||||
$targetUserId,
|
||||
$request->ip(),
|
||||
);
|
||||
|
||||
if (! $session) {
|
||||
return response()->json([
|
||||
'message' => 'Impersonation session is invalid or has expired.',
|
||||
'impersonation_ended' => true,
|
||||
], 403);
|
||||
}
|
||||
|
||||
// Load the target user
|
||||
$targetUser = User::find($targetUserId);
|
||||
|
||||
if (! $targetUser) {
|
||||
return response()->json(['message' => 'Target user not found.'], 404);
|
||||
}
|
||||
|
||||
// Store impersonation context in request attributes
|
||||
$request->attributes->set('impersonator', $admin);
|
||||
$request->attributes->set('impersonation_session', $session);
|
||||
|
||||
// Swap auth context — the rest of the request sees the target user
|
||||
app('auth')->setUser($targetUser);
|
||||
|
||||
// Tag all log entries with impersonation context
|
||||
Log::shareContext([
|
||||
'impersonated_by' => $admin->id,
|
||||
'impersonation_session_id' => $session->id,
|
||||
]);
|
||||
|
||||
// Increment actions count
|
||||
$this->impersonationService->incrementActionsCount($session);
|
||||
|
||||
return $next($request);
|
||||
}
|
||||
|
||||
private function isSensitiveRoute(Request $request): bool
|
||||
{
|
||||
// Get path relative to API prefix (strip api/v1/)
|
||||
$path = $request->path();
|
||||
$path = preg_replace('#^api/v1/#', '', $path);
|
||||
|
||||
foreach (self::SENSITIVE_ROUTE_PREFIXES as $prefix) {
|
||||
if (str_starts_with($path, $prefix)) {
|
||||
return true;
|
||||
}
|
||||
}
|
||||
|
||||
return false;
|
||||
}
|
||||
}
|
||||
25
api/app/Http/Requests/Admin/StartImpersonationRequest.php
Normal file
25
api/app/Http/Requests/Admin/StartImpersonationRequest.php
Normal file
@@ -0,0 +1,25 @@
|
||||
<?php
|
||||
|
||||
declare(strict_types=1);
|
||||
|
||||
namespace App\Http\Requests\Admin;
|
||||
|
||||
use Illuminate\Foundation\Http\FormRequest;
|
||||
|
||||
class StartImpersonationRequest extends FormRequest
|
||||
{
|
||||
public function authorize(): bool
|
||||
{
|
||||
return true; // Authorization handled in service
|
||||
}
|
||||
|
||||
/** @return array<string, mixed> */
|
||||
public function rules(): array
|
||||
{
|
||||
return [
|
||||
'reason' => ['required', 'string', 'min:5', 'max:500'],
|
||||
'mfa_code' => ['required', 'string'],
|
||||
'mfa_method' => ['required', 'string', 'in:totp,email,backup_code'],
|
||||
];
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,29 @@
|
||||
<?php
|
||||
|
||||
declare(strict_types=1);
|
||||
|
||||
namespace App\Http\Resources\Admin;
|
||||
|
||||
use Illuminate\Http\Request;
|
||||
use Illuminate\Http\Resources\Json\JsonResource;
|
||||
|
||||
class ImpersonationSessionResource extends JsonResource
|
||||
{
|
||||
/** @return array<string, mixed> */
|
||||
public function toArray(Request $request): array
|
||||
{
|
||||
return [
|
||||
'id' => $this->id,
|
||||
'admin_id' => $this->admin_id,
|
||||
'target_user_id' => $this->target_user_id,
|
||||
'target_user' => new AdminUserResource($this->whenLoaded('targetUser')),
|
||||
'reason' => $this->reason,
|
||||
'mfa_method' => $this->mfa_method,
|
||||
'started_at' => $this->started_at?->toIso8601String(),
|
||||
'expires_at' => $this->expires_at?->toIso8601String(),
|
||||
'ended_at' => $this->ended_at?->toIso8601String(),
|
||||
'end_reason' => $this->end_reason,
|
||||
'actions_count' => $this->actions_count,
|
||||
];
|
||||
}
|
||||
}
|
||||
Reference in New Issue
Block a user