kino/laravel-jwt

Dead simple JWT Auth Provider for Laravel 5.4+

Laravel JWT

, _(*1)

This package provides out-of-the-box API authentication using JWT for Laravel., _(*2)

Installation.

You can install this package by running:, _(*3)

composer require kino/laravel-jwt

Setup.

In order to setup this package into your application, minimal configuration is actually needed., _(*4)

1) Service Provider.

Register this package's Service Provider by adding it to the providers section of your config/app.php file:, _(*5)

   'providers' => [

       // ... other providers omitted

       Kino\Auth\JWT\ServiceProvider::class,

   ],

2) Configuration file.

Publish the configuration file (config/jwt.php) by running the following command after registering the Service Provider., _(*6)

php artisan vendor:publish --provider="Kino\Auth\JWT\ServiceProvider"

3) Generate a Secret.

In order for this package to works, you will need a separate secret (do not use the application key)., _(*7)

This package provides a command that can be used for generating a strong key., _(*8)

Get a new key by running:, _(*9)

php artisan jwt:generate

Then, copy the generated key contents into your .env file., _(*10)

NOTICE: The key generation process will not automatically set it inside your .env file, do it manually., _(*11)

4) Setup Guard

In order to automatically authenticate your routes using JWT tokens, you need to change the guard driver to jwt, _(*12)

Inside config/auth.php set the corresponding guard group you want to protect:, _(*13)

If you have the default guard group named api, your auth.php should be like this:, _(*14)

  'guards' => [
        // ... other guards omitted.

        'api' => [
            'driver'   => 'jwt', // this is the line you need to change.
            'provider' => 'users',
        ],
    ],

That's it, we are all ready to use it., _(*15)

Usage.

This package aims to be dead simple to use., _(*16)

The following templates can be used to setup your existing authentication controllers and resources., _(*17)

NOTICE: Full working examples of use for this package will be added on this package when it reaches it's 1.0 version., _(*18)

Protecting Routes.

This package is fully integrated with Laravel Authentication., _(*19)

The default configuration (config/jwt.php) brings a sensitive value that is very useful when your application is not completely an API: 'middleware_match, _(*20)

By not completely an API, I mean, the JWT guard is not the default one., _(*21)

In those cases, in order to use the auth middleware, the config key middleware_match MUST be set to true., _(*22)

This configuration key allows non protected routes to work properly., _(*23)

Notice that this option will match middleware group names with guard names., _(*24)

In this case, the 'api' middleware group will always use the api guard. Also, the 'web' middleware group will always use the web guard., _(*25)

If you do not use this value, you will need to use suffixes when referencing the auth middleware, like auth:api., _(*26)

Issuing and Renewing Tokens.

For issuing tokens, no special class is actually needed, you can just expect create a Guard current implementation from the IoC and work from there., _(*27)

Check out the examples., _(*28)

** On the following examples, all Guard instances are injected from Illuminate\Contracts\Auth\Guard ** ** On the following examples, all Request instances are injected from Illuminate\Http\Request **, _(*29)

Token from User Instance.

This method should be used when you just registered a user and any other special cases., _(*30)

public function tokenFromUser(Guard $auth)
{
    // generating a token from a given user.
    $user = SomeUserModel::find(12);

    // logs in the user
    $auth->login($user);

    // get and return a new token
    $token = $auth->issue();

    return $token;
}

Token from User Credentials.

This method should be used when you just registered a user and any other special cases., _(*31)

public function tokenFromCredentials(Guard $auth, Request $request)
{
    // get some credentials
    $credentials = $request->only(['email', 'password']);

    if ($auth->attempt($credentials)) {
       return $token = $auth->issue();
    }

    return ['Invalid Credentials'];
}

Refreshing Tokens.

Tokens can be refreshed in 2 different ways: Auto detect or manual., _(*32)

If you do not pass any argument into the refresh method, the Guard will look for either a Authorization header or a token field on the request's body., _(*33)

public function refreshToken(Guard $auth)
{
    // auto detecting token from request.
    $token = $auth->refresh();

    // manually passing the token to be refreshed.
    $token = $auth->refresh($oldToken);

    return $token;
}

Custom Claims.

Of course, there are support for custom claims., _(*34)

You can set them in two ways., _(*35)

By explicitly passing them.

$customClaims = [
    'custom1' => 'value1',
    'custom2' => 'value2',
];

// when issuing
$auth->issue($customClaims);

// when refreshing
// custom claims are the second parameter as the first one is the
// old token
$auth->refresh(null, $customClaims);

By Authenticatable method.

If all your users will have the same custom claims, you can setup a default custom claims method on your User's model (or any other Authenticatable you're using):, _(*36)

If the method customJWTClaims() is present on the model being issue the token against, this claims will be automatically included., _(*37)

class User extends Model implements Authenticatable
{
    public function customJWTClaims()
    {
        return [
            'email' => $this->email,
            'name'  => $this->name,
        ];
    }
}