Feature: Laravel 5.2 Custom Authentication Guard and Driver

[mtpultz]

The docs indicate it is possible to create your own implementation of Illuminate\Contracts\Auth\Guard and registering it as a driver in a service provider.

I was reading about the new stateless token authentication that was added in 5.2 in a JacobBennett Gist (the docs are really vague), but it doesn't appear to be the same as JWT tokens. That said it would be amazing to be able to leverage Laravel's API the same way.

Would it be possible to create a custom driver to reduce the amount of changes required to implement JWT tokens, and reduce the API a bit so using more of Laravel's API? For example getting a user is Auth::guard('api')->user(); using the API guard, and the equivalent could be Auth::guard('jwt')->user();

[daviestar]

+1

[tdhsmith]

This is already being worked on on the develop branch. (cf. JWTGuard.php)

If you're interested, there are some discussions on the matter at #376, #384, and #479, among others.

[mtpultz]

Thanks @tdhsmith, I'm very interested. Thanks for the links. Are there any areas that you need help on to make this usable for early stages of development using Laravel 5.2? From the links it appears that Laravel 5.2 has a lot of methods implemented, but I'm not familiar enough with it to tell how far along it is. Most of the issues are related to Lumen integration. Trying to time this with our needs of upcoming development.

[mtpultz]

@tdhsmith are there steps to setup the use of the JWTGuard to test it out? The current wiki setup doesn't seem to work the same way.

[tdhsmith]

Are there any areas that you need help on to make this usable for early stages of development using Laravel 5.2?

Well I haven't personally worked on any of the new guard stuff, so I don't have a good sense myself. Perhaps @tymondesigns has suggestions. I think the main goals are just to test it thoroughly (are there unit tests for everything?) and then evaluate which other methods on SessionGuard might be useful to adapt for it.

are there steps to setup the use of the JWTGuard to test it out?

Not yet. I think it should be sufficient to set your auth driver to jwt (assuming you've already done the config stuff in the docs). Then in general you should replace calls to JWTAuth with calls to Auth itself, and explore the new helpers this provides. In particular you should test out "traditional" auth sugars like Auth::user(), Auth::guest(), Auth::id(), and Auth::logout(). (If you're working in an app that already accomplishes everything with middleware route gating though, you probably won't see big changes then, since you probably aren't running any checks like this anywhere.)

[tdhsmith]

These are some other thoughts I've had on ways forward. They might not be exactly related to your question, but I figured I would share them here as long as I have them:

• There're some interesting questions on how the auth provider should be adapted, because right now there is an odd cycle in the call stack JWTGuard --> JWT --> auth provider --> JWTGuard --> user provider. In any case, I think it's probably dangerous to keep using the same provider class, Illuminate, for both guards. The guards inherently behave different and we shouldn't limit ourselves by expecting them to both conform to one provider. (I've argued previously that I don't think we should keep the once method names in JWTGuard because they imply an alternative that doesn't exist in a stateless auth system, but that might only be opinionated bikeshedding on my behalf.)
• In an ideal world, there would be an sibling repo to this that has example applications for different Laravel and Lumen versions and can also double as a base for functional tests. A number of recent issues, including the Lumen problems that eventually sparked the guard, have been caused by situations that couldn't really be detected by pure unit tests, so having whole app architectures to run would really help with some of the subtler specification/functionality issues.

[tymondesigns]

@tdhsmith on your first point, I removed the JWTAuth dependency from the JWTGuard so there is no weird auth call stack now, only JWTGuard --> JWT --> Laravel's AuthManger. Or did I miss something?

And you second point, It has been on my mind for a while, that it would be great to have concrete examples where people can see how things plumb together. Once I get this next release out of the way, that will be next I think.

[tdhsmith]

Nope you're totally right. I was simultaneously looking at pre-guard code and the new code, and not keeping them separate in my mind. The JWT / JWTAuth split keeps that cycle stuff from happening. Smart choice! 👍

[daviestar]

This is the L5.1 demo app that led me here: https://laracasts.com/discuss/channels/laravel/starter-application-vuejs-laravel-dingo-jwt

[mtpultz]

This is just a post of the steps to get the JWTGuard in place for an API using Laravel 5.2.x to possibly help with starting the documentation of this feature, but also to see if this is the best way to implement JWTGuard. For example, is there a way that not so many methods need to be overridden with one or two changes.

Using JWTGuard with Laravel 5.2.x

1. config/app.php - add Tymon\JWTAuth\Providers\LaravelServiceProvider::class to providers
2. In your terminal publish the config file: php artisan vendor:publish --provider="Tymon\JWTAuth\Providers\LaravelServiceProvider"
3. In your terminal generate the secret: php artisan jwt:secret
4. config/auth.php - set the default guard to api, and change the api driver to jwt

'defaults' => [
    'guard' => 'api',
    'passwords' => 'users',
],

'guards' => [
    ...

    'api' => [
        'driver' => 'jwt',
        'provider' => 'users',
    ],
],

5. /app/routes.php - add a few basic authentication routes

Route::group([
    'prefix' => 'api'
], function () {

    $this->post('login', 'Auth\AuthController@login');
    $this->get('logout', 'Auth\AuthController@logout');

    Route::group([
        'prefix' => 'restricted',
        'middleware' => 'auth:api',
    ], function () {

        Route::get('/test', function () {
            return 'authenticated';
        });

        Route::get('/index', 'HomeController@index');
    });
});

6. /app/AuthController.php

Authentication appears to almost work out of the box using the JWTGuard. To maintain the existing throttling I copied the AuthenticateUsers::login into AuthController and edited the second parameter of the call to attempt from $request->has('remember'); to be the default used in JWTGuard::attempt, and stored the $token for use.

public function login(Request $request)
{
    ...

    if ($token = Auth::guard($this->getGuard())->attempt($credentials)) {
        return $this->handleUserWasAuthenticated($request, $throttles, $token);
    }

    ...
}

7. AuthenticatedUsers::handleUserWasAuthenticated also needs to know about the $token

protected function handleUserWasAuthenticated(Request $request, $throttles, $token)
{
    if ($throttles) {
        $this->clearLoginAttempts($request);
    }

    if (method_exists($this, 'authenticated')) {
        return $this->authenticated($request, Auth::guard($this->getGuard())->user(), $token);
    }

    return redirect()->intended($this->redirectPath());
}

8. AuthenticateUsers::handleUserWasAuthenticated checks for a method authenticated, which I added to AuthController to respond when authentication is successful

protected function authenticated($request, $user, $token)
{
    return response()->json([
        'user'    => $user,
        'request' => $request->all(),
        'token'   => $token
    ]);
}

9. AuthenticatesUsers::sendFailedLoginResponse can be pulled up to AuthController to respond with JSON instead of redirecting failed authentication attempts

protected function sendFailedLoginResponse(Request $request)
{
    return response()->json([
        'message'  => $this->getFailedLoginMessage(),
        'username' => $this->loginUsername(),
        'request'  => $request,
    ]);
}

10. User model needs to implement Tymon\JWTAuth\Contracts\JWTSubject (see #260, and JWTSubject)

...

use Tymon\JWTAuth\Contracts\JWTSubject as AuthenticatableUserContract;

use Illuminate\Contracts\Auth\CanResetPassword as CanResetPasswordContract;

class User extends Model implements
    AuthenticatableContract,
    AuthorizableContract,
    CanResetPasswordContract,
    AuthenticatableUserContract
{
    use Authenticatable, Authorizable, CanResetPassword;

    ...

    /**
     * @return mixed
     */
    public function getJWTIdentifier()
    {
        return $this->getKey(); // Eloquent model method
    }

    /**
     * @return array
     */
    public function getJWTCustomClaims()
    {
        return [];
    }
}

11. Test out whether authentication works by hitting the /login route with Postman by setting the header to key: Authorization, value: Bearer TOKEN_STRING

12. In order to hit the authenticated routes /test this setup will work, but if you're using the HomeController and hitting a route like /index, make sure you remove the auth middleware from the controller's constructor, otherwise the routes to actions within the HomeController won't work.

Registration Using JWTGuard with Laravel 5.2.x

1. The RegistersUsers trait added to the AuthController also needs an update as JWTGuard doesn't have a login method only an attempt method. So you need to pull up the register method to AuthController and substitute out the guard invoking login for attempt, capture the token, and then return the token in a response.

public function register(Request $request)
{
    $validator = $this->validator($request->all());

    if ($validator->fails()) {
        $this->throwValidationException(
            $request, $validator
        );
    }

    $this->create($request->all());

    $credentials = [
        'username' => $request['username'],
        'password' => $request['password'],
    ];

    $token = Auth::guard($this->getGuard())->attempt($credentials);

    return response()->json(['token' => $token]);
}

Logout

To logout invoke JWTGuard's logout method, which invalidates the token, resets the user, and unsets the token.

public function logout()
{
    Auth::guard($this->getGuard())->logout();

    // ...
}

[MitchellMcKenna]

Thanks @mtpultz, would someone be able to post a similar guide to using JWTGuard with Lumen as well?

[mtpultz]

@tymondesigns seems worth adding a login action to the guard to allow for easy registration (this is more of a note). If I have time on the weekend I'll have a look at it.