|
| 1 | +# Laravel Impersonate Guard |
| 2 | + |
| 3 | +This is a guard implementation in Laravel for handling user impersonation. It extends Laravel's `SessionGuard` and provides additional methods for impersonation-related functionality. |
| 4 | + |
| 5 | +User impersonation is a feature that enables an administrator or privileged user to temporarily assume the identity of another user within the application. This capability proves valuable for troubleshooting, testing user-specific features, or providing support. |
| 6 | + |
| 7 | +Moreover, It supports multiple authentication guards. For example, admin guard users can also impersonate web guard users. |
| 8 | + |
| 9 | +## Security Considerations |
| 10 | + |
| 11 | +User impersonation should be used with caution, especially in production environments. It's important to properly authenticate and authorize users before allowing them to impersonate others. Additionally, sensitive actions or pages should be protected from access while in impersonation mode to prevent unauthorized use. |
| 12 | + |
| 13 | +## Installation |
| 14 | + |
| 15 | +You can install this package via Composer: |
| 16 | + |
| 17 | +```bash |
| 18 | +composer require ukeloop/laravel-impersonatable-guard |
| 19 | +``` |
| 20 | + |
| 21 | +## Configuration |
| 22 | + |
| 23 | +Update your authentication configuration to use the `ImpersonatableSessionGuard` instead of Laravel's default `SessionGuard`. You need to replace the driver from `session` to `impersonatable.session`: |
| 24 | + |
| 25 | +```php |
| 26 | +// config/auth.php |
| 27 | + |
| 28 | +'guards' => [ |
| 29 | + 'web' => [ |
| 30 | + 'driver' => 'impersonatable.session', |
| 31 | + 'provider' => 'users', |
| 32 | + ], |
| 33 | +], |
| 34 | +``` |
| 35 | + |
| 36 | +## Usage |
| 37 | + |
| 38 | +### Impersonate Users |
| 39 | + |
| 40 | +Start impersonating the specified user. This method takes an instance of `Illuminate\Contracts\Auth\Authenticatable` representing the user to impersonate. |
| 41 | + |
| 42 | +```php |
| 43 | +Auth::guard('web')->impersonate($user); |
| 44 | +``` |
| 45 | + |
| 46 | +### Once Impersonate Users |
| 47 | + |
| 48 | +Temporarily impersonate the specified user for a single request. This method is useful for actions that need to be performed as another user without permanently switching the user context. |
| 49 | + |
| 50 | +```php |
| 51 | +Auth::guard('web')->onceImpersonate($user); |
| 52 | +``` |
| 53 | + |
| 54 | +### Exit Impersonation |
| 55 | + |
| 56 | +Stop impersonating the current user and return to the original user context. |
| 57 | + |
| 58 | +```php |
| 59 | +Auth::guard('web')->exitImpersonation(); |
| 60 | +``` |
| 61 | + |
| 62 | +### Get Original User |
| 63 | + |
| 64 | +Get the original user that was being impersonated. |
| 65 | + |
| 66 | +```php |
| 67 | +$originalUser = Auth::guard('web')->originalUser(); |
| 68 | +``` |
| 69 | + |
| 70 | +### Check Currently impersonated state |
| 71 | + |
| 72 | +Check if the guard is currently in an impersonated state. |
| 73 | + |
| 74 | +```php |
| 75 | +$isImpersonated = Auth::guard('web')->impersonated(); |
| 76 | +``` |
| 77 | + |
| 78 | +## Protect Impersonation With Middleware |
| 79 | + |
| 80 | +You can use the middleware `impersonation.protect` to protect your routes against user impersonation. This middleware ensures that users cannot access certain routes while impersonating another user. |
| 81 | + |
| 82 | +```php |
| 83 | +Route::get('/protect-form-impersonation', 'ExampleController@handleImportantRequest')->middleware('impersonation.protect'); |
| 84 | +``` |
| 85 | + |
| 86 | +Protect with specified guards: |
| 87 | + |
| 88 | +```php |
| 89 | +Route::get('/protect-form-impersonation', 'ExampleController@handleImportantRequest')->middleware('impersonation.protect:specified-guard'); |
| 90 | +``` |
| 91 | + |
| 92 | +## Example Impersonation Controller |
| 93 | + |
| 94 | +Example controller for impersonating users: |
| 95 | + |
| 96 | +```php |
| 97 | +use App\Models\User; |
| 98 | +use Illuminate\Http\RedirectResponse; |
| 99 | +use Illuminate\Support\Facades\Auth; |
| 100 | +use RuntimeException; |
| 101 | +use Ukeloop\ImpersonatableGuard\Contracts\ImpersonatableGuard; |
| 102 | + |
| 103 | +class ImpersonationController extends Controller |
| 104 | +{ |
| 105 | + /** |
| 106 | + * Start impersonating the specified user. |
| 107 | + */ |
| 108 | + public function impersonate(User $user): RedirectResponse |
| 109 | + { |
| 110 | + $guard = Auth::guard('web'); |
| 111 | + |
| 112 | + if (!$guard instanceof ImpersonatableGuard) { |
| 113 | + throw new RuntimeException('This guard is not allowed to impersonate.'); |
| 114 | + } |
| 115 | + |
| 116 | + $guard->impersonate($user); |
| 117 | + |
| 118 | + return redirect('/'); |
| 119 | + } |
| 120 | + |
| 121 | + /** |
| 122 | + * Stop impersonating the current user and return to the original user context. |
| 123 | + */ |
| 124 | + public function exit(): RedirectResponse |
| 125 | + { |
| 126 | + $guard = Auth::guard('web'); |
| 127 | + |
| 128 | + if (!$guard instanceof ImpersonatableGuard) { |
| 129 | + throw new RuntimeException('This guard is not allowed to impersonate.'); |
| 130 | + } |
| 131 | + |
| 132 | + $guard->exitImpersonation(); |
| 133 | + |
| 134 | + return redirect('/'); |
| 135 | + } |
| 136 | +} |
| 137 | +``` |
| 138 | + |
| 139 | +## Custom Impersonate Guard |
| 140 | + |
| 141 | +You can create custom impersonate guards by implementing `Ukeloop\ImpersonatableGuard\Contracts\ImpersonatableGuard`. |
| 142 | + |
| 143 | +```php |
| 144 | +use Ukeloop\ImpersonatableGuard\Contracts\ImpersonatableGuard; |
| 145 | + |
| 146 | +class CustomImpersonateGuard implements ImpersonatableGuard |
| 147 | +{ |
| 148 | + // Define your own logic |
| 149 | +} |
| 150 | +``` |
0 commit comments