JWT的使用详解

背景

公司处在前后端分离的转折阶段，作为后端人员，要找到一个适用于接口验证的方式，公司仍保持后端使用Laravel框架，而laravel框架默认的是【web】方式，web 方式是使用 session 来进行用户认证，当然也是可以使用，但是有一定的不安全，经过调研，主流使用的Token验证方式。

介绍JWT

JWT资料

• 项目Wiki
• 官方指导文档
• The Anatomy of a JSON Web Token

JWT：全称Json Web Token，是一种规范化的token。可以理解为对token这一技术提出的一套规范，是在RFC 7519中提出的。

安装及基础配置

laravel方式

1.安装

composer require tymon/jwt-auth

2.进行配置

文档中有描述，要把Tymon\JWTAuth\Providers\LaravelServiceProvider类添加到app.php的providers中，这里是指在laravel5.4及以下版本必要的操作。本人使用的laravel5.6，所以无需添加。

2.1 发布配置文件

php artisan vendor:publish --provider=“Tymon\JWTAuth\Providers\LaravelServiceProvider”

这里会在config下创建一个jwt.php的配置文件

2.2 生成密钥

php artisan jwt:secret

该命令会修改.env文件，然后里面会生成一个加密密钥，例如：

2.3 配置Auth Guard

在config/auth.php文件中，需要将guards/driver更新为jwt

  /*
    |--------------------------------------------------------------------------
    | Authentication Guards
    |--------------------------------------------------------------------------
    |
    | Next, you may define every authentication guard for your application.
    | Of course, a great default configuration has been defined for you
    | here which uses session storage and the Eloquent user provider.
    |
    | All authentication drivers have a user provider. This defines how the
    | users are actually retrieved out of your database or other storage
    | mechanisms used by this application to persist your user's data.
    |
    | Supported: "session", "token"
    |
    */

    'guards' => [
        'web' => [
            'driver' => 'session',
            'provider' => 'users',
        ],

        'api' => [
            'driver' => 'jwt', //修改了这里，有token改为了jwt
            'provider' => 'users',
        ],
    ],

2.4 更新模型

为了简单，我使用默认的User来生成token，具体的使用其他的模型来生成token，请静候后续。
在User模型增加一些代码

<?php

namespace App;

use Illuminate\Notifications\Notifiable;
use Illuminate\Foundation\Auth\User as Authenticatable;
use Tymon\JWTAuth\Contracts\JWTSubject;

class User extends Authenticatable implements JWTSubject
{
    use Notifiable;

    /**
     * The attributes that are mass assignable.
     *
     * @var array
     */
    protected $fillable = [
        'name', 'email', 'password',
    ];

    /**
     * The attributes that should be hidden for arrays.
     *
     * @var array
     */
    protected $hidden = [
        'password', 'remember_token',
    ];

    /**
     * @inheritDoc
     */
    public function getJWTIdentifier()
    {
        // TODO: Implement getJWTIdentifier() method.
        return $this->getKey();
    }

    /**
     * @inheritDoc
     */
    public function getJWTCustomClaims()
    {
        // TODO: Implement getJWTCustomClaims() method.
        return [];
    }
}

2.5 注册Facade

这里注册的两个facade并不是必须的，只是为了后续代码编写提供便利。
config/app.php

'aliases' => [
        ...
        // 添加以下两行
        'JWTAuth' => \Tymon\JWTAuth\Facades\JWTAuth::class,
        'JWTFactory' => \Tymon\JWTAuth\Facades\JWTFactory::class,
],

要是不用Facade的话，也可以使用辅助函数auth();

2.6 注册路由

文档上也有，我这里就按照自己的风格来记录喽。

Route::post('login', 'AuthController@login');
Route::group([
    'prefix' => 'jwt', //这里是为了统一，后续所有对外的API，前缀统一为jwt，再额外走一个中间件，中间件功能是验证，后续会详细描述
    'middleware'=>'api.auth'
], function ($router) {
    /*中间件定义在控制器中，所以这里可以不用再次定义*/
    Route::post('logout', 'AuthController@logout');
    Route::post('refresh', 'AuthController@refresh');
    Route::post('me', 'AuthController@me');
    Route::post('user-info','UserJWTController@postUerInfo');
});

2.7 创建token控制器

php artisan make:controller AuthController

<?php

namespace App\Http\Controllers;

use Illuminate\Http\Request;
use App\Http\Controllers\Controller;
use App\User;
use Tymon\JWTAuth\Facades\JWTAuth;

class AuthController extends Controller
{
    //
    /**
     * Create a new AuthController instance.
     * 要求附带email和password（数据来源users表）
     *
     * @return void
     */
    public function __construct()
    {
        // 这里额外注意了：官方文档样例中只除外了『login』
        // 这样的结果是，token 只能在有效期以内进行刷新，过期无法刷新
        // 如果把 refresh 也放进去，token 即使过期但仍在刷新期以内也可刷新
        // 不过刷新一次作废
//        $this->middleware('auth:api', ['except' => ['login']]);
        // 另外关于上面的中间件，官方文档写的是『auth:api』
        // 但是我推荐用 『jwt.auth』，效果是一样的，但是有更加丰富的报错信息返回
    }

    /**
     * Get a JWT via given credentials.
     *
     * @return \Illuminate\Http\JsonResponse
     */
    public function login()
    {
        $credentials = request(['email', 'name']);
//dd($credentials);
        //第二种生成token方式：基于User模型返回实例
        $user = User::where([
            'email'=>$credentials['email'],
            'name'=>$credentials['name'],
        ])->first();

        $token = auth('api')->login($user);//因为没有使用Facade，所以这里使用auth函数的时候，要制命Guard的类型，可在auth.php查看，若是使用JWT，则需要将api数组的dricver由token改为jwt
        /*用JWTAuth Facade来写
        *$token = JWTAuth::fromUser($user);
        * */
        if(!$token){
            return response()->json(['error' => 'Unauthorized'], 401);
        }
        return $this->respondWithToken($token);


        //第一种生成token方式：基于账密参数
        if (! $token = auth('api')->attempt($credentials)) {
            return response()->json(['error' => 'Unauthorized'], 401);
        }

        return $this->respondWithToken($token);
    }

    /**
     * Get the authenticated User.
     *
     * @return \Illuminate\Http\JsonResponse
     */
    public function me()
    {
        return response()->json(auth('api')->user());
    }

    /**
     * Log the user out (Invalidate the token).
     *
     * @return \Illuminate\Http\JsonResponse
     */
    public function logout()
    {
        auth('api')->logout();

        return response()->json(['message' => 'Successfully logged out']);
    }

    /**
     * Refresh a token.
     * 刷新token，如果开启黑名单，以前的token便会失效。
     * 值得注意的是用上面的getToken再获取一次Token并不算做刷新，两次获得的Token是并行的，即两个都可用。
     * @return \Illuminate\Http\JsonResponse
     */
    public function refresh()
    {
        return $this->respondWithToken(auth('api')->refresh());
    }

    /**
     * Get the token array structure.
     *
     * @param  string $token
     *
     * @return \Illuminate\Http\JsonResponse
     */
    protected function respondWithToken($token)
    {
        return response()->json([
            'access_token' => $token,
            'token_type' => 'bearer',
            'expires_in' => auth('api')->factory()->getTTL() * 60
        ]);
    }

}

JWT token详解

1.token的获取、使用、刷新等

上面我已经配置好了，其实我就可以直接调用API来获取、使用token了，如下postman展示：

1.1 获取token

1.2 使用token

上面创建路由时，我有一个获取用户信息的路由，调用如下：

我这是加入到了url中。其他的我就不赘述了。

2. token的创建、组成

一个JWT token是由三部分组成的，header、payload和signature，详情可以查看Token组成方式

2.1 token的创建

看到前面的AuthController.php，会发现我写了两种token的创建方法，这里介绍一下，其实有三种方法：

• 1.基于账密参数
• 2.基于Users的实例
• 3.基于users的用户主键id

第一种：基于账密参数

// 使用辅助函数
$credentials = request(['email', 'password']); 
$token = auth()->attempt($credentials)

// 使用 Facade
$credentials = $request->only('email', 'password');
$token = JWTAuth::attempt($credentials);

第二种：基于users的实例

// 使用辅助函数
$user = User::first();
$token = auth()->login($user);

// 使用 Facade
$user = User::first();
$token = JWTAuth::fromUser($credentials);

第三种：基于users的主键id

// 使用辅助函数
$token = auth()->tokenById(1);

// 使用 Facade
源码中没找到

JWT token应用于对外API验证

在创建路由的时候，给群组增加了一个名为api.auth的中间件，这样所有想走JWT验证的API，都可以放入该群组，接下来我们就看看这个中间件都干了什么

创建中间件

php artisan make:middleware RefreshToken

注册中间件

如果你希望中间件在应用处理每个 HTTP 请求期间运行。只需要在 app/Http/Kernel.php 中的 $middleware 属性中列出这个中间件，然后分配一个键名。

protected $routeMiddleware = [
        .....
        'api.auth' => RefreshToken::class
    ];

其实JWT也有很多中间件，想使用也可以像是上面配置一样，分配个键名，如下：

protected $middlewareAliases = [
    'jwt.auth' => Authenticate::class,
    'jwt.check' => Check::class,
    'jwt.refresh' => RefreshToken::class,
    'jwt.renew' => AuthenticateAndRenew::class,
];

编写中间件文件

<?php

namespace App\Http\Middleware;

use Closure;
use Illuminate\Support\Facades\Auth;
use Tymon\JWTAuth\Exceptions\JWTException;
use Tymon\JWTAuth\Exceptions\TokenExpiredException;
use Tymon\JWTAuth\Facades\JWTAuth;
use Tymon\JWTAuth\Http\Middleware\BaseMiddleware;

class RefreshToken extends BaseMiddleware
{
    /**
     * Handle an incoming request.
     *
     * @param  \Illuminate\Http\Request  $request
     * @param  \Closure  $next
     * @return mixed
     */
    public function handle($request, Closure $next)
    {
        /*这里是用作外部业务调用我方暴漏的API时，验证需要的中间件
         *
         *
         * */
        $token = $request->get('token','');
        if(!$token)
        {return response()->json([
            'code'=>700,
            'msg'=>'token 必须存在',
        ]);}

        try {
            //检测用户登录状态
            if($this->auth->parseToken()->authenticate()){
/*                //解析token
                $token = JWTAuth::parseToken()->getToken();
                //获取载荷
                $payload = JWTAuth::parseToken()->getPayload();
                //载荷里面token的过期时间
                $exp = date('y-m-d H:i:s',$payload->get('exp'));
                $nbf = date('y-m-d H:i:s',$payload->get('nbf'));
                $iat = date('y-m-d H:i:s',$payload->get('iat'));
                var_dump($token,$exp,$nbf,$iat,$payload);*/
                return $next($request);
            }

        }catch (TokenExpiredException $tokenExpiredException){
            //捕捉到过期的token，判断是否在刷新有效期，在的话刷新并将新的token并通过此次请求
            try {
                /*token在刷新期内，是可以自动执行刷新获取新的token的
                 * 当JWT_BLACKLIST_ENABLED=false时，可以在JWT_REFRESH_TTL时间内，无限次刷新使用旧的token换取新的token
                 * 当JWT_BLACKLIST_ENABLED=true时，刷新token后旧的token即刻失效，被放入黑名单
                 * */
                $token = $this->auth->refresh();
                //使用一次性登录，确保此次请求成功
                Auth::guard('api')->onceUsingId($this->auth->manager()->getPayloadFactory()->buildClaimsCollection()->toPlainArray()['sub']);
                //方案一：将token返回给客户端，方便客户端下次请求使用，此方式直接跳转下一步
                return $this->setAuthenticationHeader($next($request), $token);
                //方案一：直接返回json串，客户端接受后需再次请求验证
//                return response()->json([
//                    'code'=>1,
//                    'data'=>[
//                        'refresh_token'=>$token,
//                        'token_type' => 'bearer',
//                        'expires_in' => auth('api')->factory()->getTTL() * 60
//                    ],
//                ]);
            }catch (JWTException $JWTException){
                return response()->json([
                    'code'=>$JWTException->getCode(),
                    'msg'=>$JWTException->getMessage(),
                ]);
            }


        }catch (JWTException $JWTException){
            return response()->json([
                'code'=>$JWTException->getCode(),
                'msg'=>$JWTException->getMessage(),
            ]);
        }

    }
}

这里继承的基础中间件内容如下：

<?php

/*
 * This file is part of jwt-auth.
 *
 * (c) Sean Tymon <tymon148@gmail.com>
 *
 * For the full copyright and license information, please view the LICENSE
 * file that was distributed with this source code.
 */

namespace Tymon\JWTAuth\Http\Middleware;

use Illuminate\Http\Request;
use Symfony\Component\HttpKernel\Exception\UnauthorizedHttpException;
use Tymon\JWTAuth\Exceptions\JWTException;
use Tymon\JWTAuth\JWTAuth;

abstract class BaseMiddleware
{
    /**
     * The JWT Authenticator.
     *
     * @var \Tymon\JWTAuth\JWTAuth
     */
    protected $auth;

    /**
     * Create a new BaseMiddleware instance.
     *
     * @param  \Tymon\JWTAuth\JWTAuth  $auth
     *
     * @return void
     */
    public function __construct(JWTAuth $auth)
    {
        $this->auth = $auth;
    }

    /**
     * Check the request for the presence of a token.
     *
     * @param  \Illuminate\Http\Request  $request
     *
     * @throws \Symfony\Component\HttpKernel\Exception\BadRequestHttpException
     *
     * @return void
     */
    public function checkForToken(Request $request)
    {
        if (! $this->auth->parser()->setRequest($request)->hasToken()) {
            throw new UnauthorizedHttpException('jwt-auth', 'Token not provided');
        }
    }

    /**
     * Attempt to authenticate a user via the token in the request.
     *
     * @param  \Illuminate\Http\Request  $request
     *
     * @throws \Symfony\Component\HttpKernel\Exception\UnauthorizedHttpException
     *
     * @return void
     */
    public function authenticate(Request $request)
    {
        $this->checkForToken($request);

        try {
            if (! $this->auth->parseToken()->authenticate()) {
                throw new UnauthorizedHttpException('jwt-auth', 'User not found');
            }
        } catch (JWTException $e) {
            throw new UnauthorizedHttpException('jwt-auth', $e->getMessage(), $e, $e->getCode());
        }
    }

    /**
     * Set the authentication header.
     *
     * @param  \Illuminate\Http\Response|\Illuminate\Http\JsonResponse  $response
     * @param  string|null  $token
     *
     * @return \Illuminate\Http\Response|\Illuminate\Http\JsonResponse
     */
    protected function setAuthenticationHeader($response, $token = null)
    {
        $token = $token ?: $this->auth->refresh();
        $response->headers->set('Authorization', 'Bearer '.$token);

        return $response;
    }
}

这里描述的业务逻辑是：

• 1.用户请求时，token未过期，则通过请求
• 2.请求时，token有效期过，但是还在刷新期，允许使用旧token无限次刷新获取新token，并临时允许此次请求
• 3.请求时，若是已过刷新期，则验证失败
  这里就涉及到了三个时间。

JWT token的三个时间

我们先看一下生成的jwt.php文件的内容：

<?php

/*
 * This file is part of jwt-auth.
 *
 * (c) Sean Tymon <tymon148@gmail.com>
 *
 * For the full copyright and license information, please view the LICENSE
 * file that was distributed with this source code.
 */

return [

    /*
    |--------------------------------------------------------------------------
    | JWT Authentication Secret
    |--------------------------------------------------------------------------
    |
    | Don't forget to set this in your .env file, as it will be used to sign
    | your tokens. A helper command is provided for this:
    | `php artisan jwt:secret`
    |
    | Note: This will be used for Symmetric algorithms only (HMAC),
    | since RSA and ECDSA use a private/public key combo (See below).
    |
    */

    'secret' => env('JWT_SECRET'),

    /*
    |--------------------------------------------------------------------------
    | JWT Authentication Keys
    |--------------------------------------------------------------------------
    |
    | The algorithm you are using, will determine whether your tokens are
    | signed with a random string (defined in `JWT_SECRET`) or using the
    | following public & private keys.
    |
    | Symmetric Algorithms:
    | HS256, HS384 & HS512 will use `JWT_SECRET`.
    |
    | Asymmetric Algorithms:
    | RS256, RS384 & RS512 / ES256, ES384 & ES512 will use the keys below.
    |
    */

    'keys' => [

        /*
        |--------------------------------------------------------------------------
        | Public Key
        |--------------------------------------------------------------------------
        |
        | A path or resource to your public key.
        |
        | E.g. 'file://path/to/public/key'
        |
        */

        'public' => env('JWT_PUBLIC_KEY'),

        /*
        |--------------------------------------------------------------------------
        | Private Key
        |--------------------------------------------------------------------------
        |
        | A path or resource to your private key.
        |
        | E.g. 'file://path/to/private/key'
        |
        */

        'private' => env('JWT_PRIVATE_KEY'),

        /*
        |--------------------------------------------------------------------------
        | Passphrase
        |--------------------------------------------------------------------------
        |
        | The passphrase for your private key. Can be null if none set.
        |
        */

        'passphrase' => env('JWT_PASSPHRASE'),

    ],

    /*
    |--------------------------------------------------------------------------
    | JWT time to live
    |--------------------------------------------------------------------------
    |
    | Specify the length of time (in minutes) that the token will be valid for.
    | Defaults to 1 hour.
    |
    | You can also set this to null, to yield a never expiring token.
    | Some people may want this behaviour for e.g. a mobile app.
    | This is not particularly recommended, so make sure you have appropriate
    | systems in place to revoke the token if necessary.
    | Notice: If you set this to null you should remove 'exp' element from 'required_claims' list.
    |
    */

    'ttl' => env('JWT_TTL', 60),

    /*
    |--------------------------------------------------------------------------
    | Refresh time to live
    |--------------------------------------------------------------------------
    |
    | Specify the length of time (in minutes) that the token can be refreshed
    | within. I.E. The user can refresh their token within a 2 week window of
    | the original token being created until they must re-authenticate.
    | Defaults to 2 weeks.
    |
    | You can also set this to null, to yield an infinite refresh time.
    | Some may want this instead of never expiring tokens for e.g. a mobile app.
    | This is not particularly recommended, so make sure you have appropriate
    | systems in place to revoke the token if necessary.
    |
    */

    'refresh_ttl' => env('JWT_REFRESH_TTL', 20160),

    /*
    |--------------------------------------------------------------------------
    | JWT hashing algorithm
    |--------------------------------------------------------------------------
    |
    | Specify the hashing algorithm that will be used to sign the token.
    |
    | See here: https://github.com/namshi/jose/tree/master/src/Namshi/JOSE/Signer/OpenSSL
    | for possible values.
    |
    */

    'algo' => env('JWT_ALGO', 'HS256'),

    /*
    |--------------------------------------------------------------------------
    | Required Claims
    |--------------------------------------------------------------------------
    |
    | Specify the required claims that must exist in any token.
    | A TokenInvalidException will be thrown if any of these claims are not
    | present in the payload.
    |
    */

    'required_claims' => [
        'iss',
        'iat',
        'exp',
        'nbf',
        'sub',
        'jti',
    ],

    /*
    |--------------------------------------------------------------------------
    | Persistent Claims
    |--------------------------------------------------------------------------
    |
    | Specify the claim keys to be persisted when refreshing a token.
    | `sub` and `iat` will automatically be persisted, in
    | addition to the these claims.
    |
    | Note: If a claim does not exist then it will be ignored.
    |
    */

    'persistent_claims' => [
        // 'foo',
        // 'bar',
    ],

    /*
    |--------------------------------------------------------------------------
    | Lock Subject
    |--------------------------------------------------------------------------
    |
    | This will determine whether a `prv` claim is automatically added to
    | the token. The purpose of this is to ensure that if you have multiple
    | authentication models e.g. `App\User` & `App\OtherPerson`, then we
    | should prevent one authentication request from impersonating another,
    | if 2 tokens happen to have the same id across the 2 different models.
    |
    | Under specific circumstances, you may want to disable this behaviour
    | e.g. if you only have one authentication model, then you would save
    | a little on token size.
    |
    */

    'lock_subject' => true,

    /*
    |--------------------------------------------------------------------------
    | Leeway
    |--------------------------------------------------------------------------
    |
    | This property gives the jwt timestamp claims some "leeway".
    | Meaning that if you have any unavoidable slight clock skew on
    | any of your servers then this will afford you some level of cushioning.
    |
    | This applies to the claims `iat`, `nbf` and `exp`.
    |
    | Specify in seconds - only if you know you need it.
    |
    */

    'leeway' => env('JWT_LEEWAY', 0),

    /*
    |--------------------------------------------------------------------------
    | Blacklist Enabled
    |--------------------------------------------------------------------------
    |
    | In order to invalidate tokens, you must have the blacklist enabled.
    | If you do not want or need this functionality, then set this to false.
    |
    */

    'blacklist_enabled' => env('JWT_BLACKLIST_ENABLED', true),

    /*
    | -------------------------------------------------------------------------
    | Blacklist Grace Period
    | -------------------------------------------------------------------------
    |
    | When multiple concurrent requests are made with the same JWT,
    | it is possible that some of them fail, due to token regeneration
    | on every request.
    |
    | Set grace period in seconds to prevent parallel request failure.
    |
    */

    'blacklist_grace_period' => env('JWT_BLACKLIST_GRACE_PERIOD', 60),

    /*
    |--------------------------------------------------------------------------
    | Cookies encryption
    |--------------------------------------------------------------------------
    |
    | By default Laravel encrypt cookies for security reason.
    | If you decide to not decrypt cookies, you will have to configure Laravel
    | to not encrypt your cookie token by adding its name into the $except
    | array available in the middleware "EncryptCookies" provided by Laravel.
    | see https://laravel.com/docs/master/responses#cookies-and-encryption
    | for details.
    |
    | Set it to true if you want to decrypt cookies.
    |
    */

    'decrypt_cookies' => false,

    /*
    |--------------------------------------------------------------------------
    | Providers
    |--------------------------------------------------------------------------
    |
    | Specify the various providers used throughout the package.
    |
    */

    'providers' => [

        /*
        |--------------------------------------------------------------------------
        | JWT Provider
        |--------------------------------------------------------------------------
        |
        | Specify the provider that is used to create and decode the tokens.
        |
        */

        'jwt' => Tymon\JWTAuth\Providers\JWT\Lcobucci::class,

        /*
        |--------------------------------------------------------------------------
        | Authentication Provider
        |--------------------------------------------------------------------------
        |
        | Specify the provider that is used to authenticate users.
        |
        */

        'auth' => Tymon\JWTAuth\Providers\Auth\Illuminate::class,

        /*
        |--------------------------------------------------------------------------
        | Storage Provider
        |--------------------------------------------------------------------------
        |
        | Specify the provider that is used to store tokens in the blacklist.
        |
        */

        'storage' => Tymon\JWTAuth\Providers\Storage\Illuminate::class,

    ],

];

有效时间

'ttl' => env('JWT_TTL', 60), //单位分钟

有效是指你获取token后，在多少时间内可以凭这个token去获取资源，逾期无效。

刷新时间

'refresh_ttl' => env('JWT_REFRESH_TTL', 20160),

刷新时间指的是在这个时间内可以凭旧 token 换取一个新 token。例如 token 有效时间为 60 分钟，刷新时间为 20160 分钟，在 60 分钟内可以通过这个 token 获取新 token，但是超过 60 分钟是不可以的，然后你可以一直循环获取，直到总时间超过 20160 分钟，不能再获取。
这里要强调的是，是否在刷新期可以一直用旧的token获取新的token，这个是由blacklist_enabled这个配置决定的，这个是指是否开启黑名单，默认是开启的，即刷新后，旧token立马加入黑名单，不可在用。

'blacklist_enabled' => env('JWT_BLACKLIST_ENABLED', true),

宽限时间

// 宽限时间需要开启黑名单（默认是开启的），黑名单保证过期token不可再用，最好打开
'blacklist_enabled' => env('JWT_BLACKLIST_ENABLED', true)

// 设定宽限时间，单位：秒
'blacklist_grace_period' => env('JWT_BLACKLIST_GRACE_PERIOD', 60)

宽限时间是为了解决并发请求的问题，假如宽限时间为 0s ，那么在新旧 token 交接的时候，并发请求就会出错，所以需要设定一个宽限时间，在宽限时间内，旧 token 仍然能够正常使用

写在最后

更多的可以查看源码，走啦

前人栽树，后人乘凉:
JWT 完整使用详解

使用 Jwt-Auth 实现 API 用户认证以及无痛刷新访问令牌
JWT 扩展具体实现详解