, (*1)
Laravel JWT
, (*2)
This package provides out-of-the-box API authentication using JWT for Laravel., (*3)
Installation.
You can install this package by running:, (*4)
composer require codecasts/laravel-jwt
Setup.
In order to setup this package into your application, minimal configuration
is actually needed., (*5)
1) Service Provider.
Register this package's Service Provider by adding it to the providers
section of your config/app.php file:, (*6)
You may skip this step on Laravel 5.5 due to the auto-discovery package feature., (*7)
'providers' => [
// ... other providers omitted
Codecasts\Auth\JWT\ServiceProvider::class,
],
2) Configuration file.
Publish the configuration file (config/jwt.php) by running the
following command after registering the Service Provider., (*8)
php artisan vendor:publish --provider="Codecasts\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)., (*9)
This package provides a command that can be used for generating a strong key., (*10)
Get a new key by running:, (*11)
php artisan jwt:generate
Then, copy the generated key contents into your .env file., (*12)
NOTICE: The key generation process will not automatically
set it inside your .env file, do it manually., (*13)
4) Setup Guard
In order to automatically authenticate your routes using JWT tokens,
you need to change the guard driver to jwt, (*14)
Inside config/auth.php set the corresponding guard group you want to protect:, (*15)
If you have the default guard group named api, your auth.php
should be like this:, (*16)
'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., (*17)
Usage.
This package aims to be dead simple to use., (*18)
The following templates can be used to setup your existing
authentication controllers and resources., (*19)
NOTICE: Full working examples of use for this package
will be added on this package when it reaches it's 1.0 version., (*20)
Protecting Routes.
This package is fully integrated with Laravel Authentication., (*21)
The default configuration (config/jwt.php) brings a sensitive value that
is very useful when your application is not completely an API: middleware_match, (*22)
By not completely an API, I mean, the JWT guard is not the default one., (*23)
In those cases, in order to use the auth middleware, the config key
middleware_match MUST be set to true., (*24)
This configuration key allows non protected routes to work properly., (*25)
Notice that this option will match middleware group names with guard names., (*26)
In this case, the 'api' middleware group will always use the api guard., (*27)
Also, the 'web' middleware group will always use the web guard, (*28)
If you do not use this value, you will need to use suffixes when referencing the
auth middleware, like auth:api., (*29)
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., (*30)
Check out the examples., (*31)
On the following examples, all Guard instances are injected from Illuminate\Contracts\Auth\Guard, (*32)
On the following examples, all Request instances are injected from Illuminate\Http\Request, (*33)
Token from User Instance.
This method should be used when you just registered a user and any other
special cases., (*34)
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., (*35)
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., (*36)
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., (*37)
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., (*38)
You can set them in two ways., (*39)
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):, (*40)
If the method customJWTClaims() is present on the model being issue the token against,
this claims will be automatically included., (*41)
class User extends Model implements Authenticatable
{
public function customJWTClaims()
{
return [
'email' => $this->email,
'name' => $this->name,
];
}
}
Contributing
Please see CONTRIBUTING for details., (*42)
Wallogit.com
