mirror of
https://github.com/stancl/tenancy-docs.git
synced 2025-12-12 18:24:03 +00:00
117 lines
No EOL
3.9 KiB
Markdown
117 lines
No EOL
3.9 KiB
Markdown
---
|
|
title: User impersonation
|
|
extends: _layouts.documentation
|
|
section: content
|
|
---
|
|
|
|
# User impersonation
|
|
|
|
This package comes with a feature that lets you impersonate users inside tenant databases. This feature works with **any identification method** and **any auth guard** — even if you use multiple.
|
|
|
|
## How it works
|
|
|
|
You generate an impersonation token an store it in the central database, in the `tenant_user_impersonation_tokens` table.
|
|
|
|
Each record in the table holds the following data:
|
|
|
|
- The token value (128 character string)
|
|
- The tenant's id
|
|
- The user's id
|
|
- The name of the auth guard
|
|
- The URL to redirect to after the impersonation takes place
|
|
|
|
You visit an impersonation route that you create — though little work is needed on your side, your route will mostly just call a method provided by the feature. This route is a **tenant route**, meaning it's on the tenant domain if you use domain identification, or prefixed with the tenant id if you use path identification.
|
|
|
|
This route checks tries to find a record in that table based on the token, and if it's valid it authenticates you with the stored user id against the auth guard and redirects you to the stored URL.
|
|
|
|
If the impersonation succeeds, the token is deleted from the database.
|
|
|
|
All tokens expire after 60 seconds by default, and this TTL can be customized — see the section at the very bottom.
|
|
|
|
## Enabling the feature
|
|
|
|
To enable this feature, go to your `config/tenancy.php` file and make sure the following class is in your `features` part of the config:
|
|
|
|
```jsx
|
|
Stancl\Tenancy\Features\UserImpersonation::class,
|
|
```
|
|
|
|
Next, publish the migration for creating the table with impersonation tokens:
|
|
|
|
```jsx
|
|
php artisan vendor:publish --tag=impersonation-migrations
|
|
```
|
|
|
|
And finally, run the migration:
|
|
|
|
```jsx
|
|
php artisan migrate
|
|
```
|
|
|
|
## Usage
|
|
|
|
First, you need to create a tenant route that looks like this:
|
|
|
|
```jsx
|
|
use Stancl\Tenancy\Features\UserImpersonation;
|
|
|
|
// We're in your tenant routes!
|
|
|
|
Route::get('/impersonate/{token}', function ($token) {
|
|
return UserImpersonation::makeResponse($token);
|
|
});
|
|
|
|
// Of course use a controller in a production app and not a Closure route.
|
|
// Closure routes cannot be cached.
|
|
```
|
|
|
|
Note that the route path or name are completely up to you. The only logic that the package does is generating tokens, verifying tokens, and doing the impersonated user log in.
|
|
|
|
Then, to use impersonation in your app, generate a token like this:
|
|
|
|
```jsx
|
|
// Let's say we want to be redirected to the dashboard
|
|
// after we're logged in as the impersonated user.
|
|
$redirectUrl = '/dashboard';
|
|
|
|
$token = tenancy()->impersonate($tenant, $user->id, $redirectUrl);
|
|
```
|
|
|
|
And redirect the user (or, presumably an "admin") to the route you created.
|
|
|
|
### Domain identification
|
|
|
|
```jsx
|
|
// Note: This is not part of the package, it's up to you to implement
|
|
// a concept of "primary domains" if you need them. Or maybe you use
|
|
// one domain per tenant. The package lets you do anything you want.
|
|
$domain = $tenant->primary_domain;
|
|
return redirect("https://$domain/impersonate/$token");
|
|
```
|
|
|
|
### Path identification
|
|
|
|
```jsx
|
|
// Make sure you use the correct prefix for your routes.
|
|
return redirect("{$tenant->id}/impersonate/$token");
|
|
```
|
|
|
|
And that's it. The user will be redirected to your impersonation route, logged in as the impersonated user, and finally redirected to your redirect URL.
|
|
|
|
### Custom auth guards
|
|
|
|
If you're using multiple auth guards, you may want to specify what auth guard the impersonation logic should use.
|
|
|
|
To do this, simply pass the auth guard name as the fourth argument to the `impersonate()` method. So to expand on our example above:
|
|
|
|
```jsx
|
|
tenancy()->impersonate($tenant, $user->id, $redirectUrl, 'jwt');
|
|
```
|
|
|
|
## Customization
|
|
|
|
You may customize the TTL of impersonation tokens by setting the following static property to the amount of seconds you want to use:
|
|
|
|
```jsx
|
|
Stancl\Tenancy\Features\UserImpersonation::$ttl = 120; // 2 minutes
|
|
``` |