incorp/laravel-jwt-impersonate

Laravel Impersonate is a plugin that allows to you to authenticate as your users.

Friday, September 8, 2017
by Rickycezar
Repository
1 Watchers
1 Stars
936 Installations

PHP
0 Dependents
0 Suggesters
53 Forks
0 Open issues
17 Versions
8 % Grown

The README.md

Incorp Laravel JWT Impersonate

DISCLAIMER: This is a project meant to fit the needs of a private company. This means this repository will not focus on flexibe open-source driven development, rather it will be changed and altered as the company sees fit., _(*1)

Laravel JWT Impersonate makes it easy to authenticate as your users. Add a simple trait to your user model and impersonate as one of your users in one click., _(*2)

Requirements
Installation
Simple usage
- Using the built-in controller
Advanced Usage
Configuration

Requirements

Laravel >= 5.8
PHP >= 7.1
JWT-Auth >= dev-develop

Installation

Require it with Composer:

composer require incorp/laravel-jwt-impersonate

Add the service provider at the end of your config/app.php:

'providers' => [
    // ...
    Incorp\Impersonate\ImpersonateServiceProvider::class,
],

Add the trait Incorp\Impersonate\Models\Impersonate to your User model.

Simple usage

Impersonate a user:, _(*3)

$token = Auth::user()->impersonate($other_user);
// You're now logged as the $other_user and the authentication token is stored in $token.

Leave impersonation:, _(*4)

$token = Auth::user()->leaveImpersonation();
// You're now logged as your original user and the authentication token is stored in $token.

Using the built-in controller

In your routes file you can call the impersonate route macro if you want to use the built-in controller., _(*5)

Route::impersonate();

Alternatively, you can execute this macro with your RouteServiceProvider., _(*6)

namespace App\Providers;

class RouteServiceProvider extends ServiceProvider
{
    public function map() {
        Route::middleware('web')->group(function (Router $router) {
            $router->impersonate();
        });
    }
}

// Where $id is the ID of the user you want impersonate
route('impersonate', $id) //the url path is "impersonate/take/{id}".

// Generate an URL to leave current impersonation
route('impersonate.leave') //the url path is "impersonate/leave".

// Check the current user impersonation status
route('impersonate.info') //the url path is "impersonate/info".

Advanced Usage

Defining impersonation authorization

By default all users can impersonate an user.
You need to add the method canImpersonate() to your user model:, _(*7)

    /**
     * @return bool
     */
    public function canImpersonate()
    {
        // For example
        return $this->is_admin == 1;
    }

By default all users can be impersonated.
You need to add the method canBeImpersonated() to your user model to extend this behavior:, _(*8)

    /**
     * @return bool
     */
    public function canBeImpersonated()
    {
        // For example
        return $this->can_be_impersonated == 1;
    }

Using your own strategy

It is possible to implement your own controller to deal with impersonation:, _(*9)

use Incorp\Impersonate\Services\ImpersonateManager;

class ImpersonateController extends Controller
{
    protected $manager;

    // Dependency Injection
    public function __construct(ImpersonateManager $manager)
    {
        $this->manager = $manager;
    }

    public function impersonate(){ /*....*/ }
    public function leave(){ /*....*/ }
}

class ImpersonateController extends Controller
{
    protected $manager;

    //Direct app call
    public function __construct()
    {
        $this->manager = app('impersonate');
    }

    public function impersonate(){ /*....*/ }
    public function leave(){ /*....*/ }
}



- Working with the manager:
```php
$manager = app('impersonate');

// Find a user by its ID
$manager->findUserById($id);

// TRUE if you are impersonating an user.
$manager->isImpersonating();

// Impersonate a user. Pass the original user and the user you want to impersonate. Returns authentication token
$token = $manager->take($from, $to);

// Leave current impersonation. Returns authentication token
$token = $manager->leave();

// Get the impersonator ID
$manager->getImpersonatorId();




### Middleware

**Protect From Impersonation**

You can use the middleware `impersonate.protect` to protect your routes against user impersonation.  
This middleware can be useful when you want to protect specific pages like users subscriptions, users credit cards, ... 



Router::get('/my-credit-card', function() {
    echo "Can't be accessed by an impersonator";
})->middleware('impersonate.protect');




### Exceptions

There are six possible exceptions thrown by the service:
- `AlreadyImpersonatingException` is thrown when an impersonator tries to take another persona without leaving the first one.
- `CantBeImpersonatedException` is thrown when the method `canBeImpersonated()` fails.
- `CantImpersonateException` is thrown when the method `canImpersonate()` fails.
- `CantImpersonateSelfException` is thrown when an user tries to impersonate self.
- `NotImpersonatingException` is thrown when an user tries to leave an impersonation without being impersonating.
- `ProtectedFromImpersonationException` is thrown when an impersonator tries to get access to a route protected by the middleware.

Each exception have a message and a status code available through the respective methods `getErrorMessage()` and `getErrorCode()`.

### Events

There are two events available that can be used to improve your workflow:
- `TakeImpersonation` is fired when an impersonation is taken.
- `LeaveImpersonation` is fired when an impersonation is left.

Each events returns two properties `$event->impersonator` and `$event->impersonated` containing a User model isntance.

## Configuration

The package comes with a configuration file.  

Publish it with the following command:


php artisan vendor:publish --tag=impersonate




Available options:


    // The custom claim key used to store the original user id in the JWT token.
    'session_key' => 'impersonated_by',



```php
    // The alias for the authentication middleware to be used in the routes.
    'auth_alias' => 'auth',

Licence

MIT, _(*10)

The Versions

08/09 2017

dev-master

9999999-dev

Laravel Impersonate is a plugin that allows to you to authenticate as your users.

library laravel-jwt-impersonate

Laravel Impersonate is a plugin that allows to you to authenticate as your users.