一、前言

  1. 如果只是单纯需要使用 JWT，可以参考在下之前：Lumen5.7使用JWT【2019.02.11最新教程】，更新啦！或者Lumen5.6使用JWT【最新教程】，亲身失败百次的总结 的教程。
  2. 由于学院 文档 的简洁性，导致新手初学不易理解。所以本文将在学院 文档 的基础上增加少许细节，仅供新手参考。

  3. 相关指导文献： 理解OAuth 2.0、RESTful API 设计指南 。

    二、说明

  4. 切不知不觉 Lumen 已经更新到 ‘5.7.x’ 版本，因此本文也紧跟脚步，使用最新版的 Lumen 进行讲解，最重要的是 Laravel/Lumen 5.7.x 版本只支持 ‘PHP7.1.3’ 及以上。

  5. 本文使用 ‘dusterio/lumen-passport: ^0.2.9’ 版本 。

  6. 操作环境：‘Windows 10’ + ‘PHP7.2’ + ‘MariaDB10.3’。上述环境在下均已测试多次，现分享出本人至今 ‘Windows’ 下正常开发使用的 整合压缩包 。

    三、开始

  7. 使用 ‘Composer’ 安装最新的 Lumen 到本地。
    composer create-project laravel/lumen passport-test --prefer-dist

  8. 进入项目 ‘passport-test’ 中，安装 ‘dusterio/lumen-passport: ^0.2.9’ 到本地。
    composer require dusterio/lumen-passport

  9. 首先模拟 Laravel 目录结构，复制‘vender/laravel/lumen-framework’下的 ‘config 目录到 ‘passport-test’ 根路径。复制完成以后 ‘passport-test’ 的根目录结构如下：

    1. /app
    2. ......others.......
    3. /config                                    <<<<<< 配置文件目录
    4. /vendor
    5. ......others.......

  10. 以后的配置文件，都只需要在根路径下的 ‘config’目录操作即可，修改根路径下的 ‘.env 文件：

    1. ......others.......
    2. APP_KEY=9TBF8FrZZgYBoM0AzKjkii/yb6TJVm11        #### Lumen默认没有设置APP_KEY
    3. CACHE_DRIVER=file                               #### 修改为文件缓存
    4. ......others (包括MySQL的配置项) .......

    本文使用以下指令快速启动服务。
    php -S localhost:8000 public/index.php

  11. 下面开始实现 JWT 功能。由于本人习惯在 ‘app’ 路径下新建一个 ‘Api’ 目录存放接口控制器类、 ‘Models’ 目录存放模型，因此之后的项目目录结构是：

    1. ......others.......
    2. /app
    3. ..........others.......
    4. ..../Api                                   <<<<<< 接口控制器文件目录
    5. ..../Models                                <<<<<< 模型文件目录
    6. /config                                    <<<<<< 配置文件目录
    7. /vendor
    8. ......others.......

    5.1 修改 ‘bootstrap’ 文件夹下的 ‘app.php’ 如下所示，需要注意的是，我修改了最后一段代码，也即修改了 Lumen 默认的控制器命名空间和默认的路由文件：
    ```php

    Dir: @/bootstrap/app.php

    <?php

requireonce _DIR.’/../vendor/autoload.php’;

try { (new Dotenv\Dotenv(DIR.’/../‘))->load(); } catch (Dotenv\Exception\InvalidPathException $e) { // }

$app = new Laravel\Lumen\Application( realpath(DIR.’/../‘) );

// 取消注释 $app->withFacades(); $app->withEloquent();

$app->singleton( Illuminate\Contracts\Debug\ExceptionHandler::class, App\Exceptions\Handler::class );

$app->singleton( Illuminate\Contracts\Console\Kernel::class, App\Console\Kernel::class );

注意！我已经修改了默认的认证中间件的路径！！

$app->routeMiddleware([ ‘auth’ => App\Api\Middlewares\Authenticate::class, ]);

// 取消注释 $app->register(App\Providers\AppServiceProvider::class); $app->register(App\Providers\AuthServiceProvider::class);

// 新增Passport的注册 $app->register(Laravel\Passport\PassportServiceProvider::class); $app->register(Dusterio\LumenPassport\PassportServiceProvider::class);

注意！我已经修改了默认的命名空间！！

$app->router->group([ ‘namespace’ => ‘App\Api\Controllers’, ], function ($router) { require DIR . ‘/../routes/api.php’; # 注意！我已经修改了默认的路由文件！！ });

return $app;

  1. 5.2. 修改 **'config'** 文件夹下的 **'auth.php'** 如下所示：<br />
  2. ```php
  3. # Dir: @/config/auth.php
  4. <?php
  6. return [
  7.     'defaults' => [
  8.         'guard' => env('AUTH_GUARD', 'api'),
  9.     ],
  11.     'guards' => [
  12.         'api' => ['driver' => 'passport', 'provider' => 'passport-provider'],
  13.     ],
  15.     'providers' => [
  16.         'passport-provider' => [
  17.             'driver' => 'eloquent',
  18.             'model' => \App\Models\UserModel::class
  19.         ]
  20.     ],
  22.     'passwords' => [
  23.         //
  24.     ],
  26. ];

5.3. 修改 ‘app/Providers’ 文件夹下的 ‘AuthServiceProvider.php’ 如下所示：

  1. # Dir: @/app/Providers/AuthServiceProvider.php
  2. <?php
  4. use Dusterio\LumenPassport\LumenPassport;
  5. use Illuminate\Support\ServiceProvider;
  7. class AuthServiceProvider extends ServiceProvider
  8. {
  9.     /**
  10.      * Register any application services.
  11.      *
  12.      * @return void
  13.      */
  14.     public function register()
  15.     {
  16.         //
  17.     }
  19.     /**
  20.      * Boot the authentication services for the application.
  21.      *
  22.      * @return void
  23.      */
  24.     public function boot()
  25.     {
  26.         LumenPassport::routes($this->app); # 注册Passport相关路由
  27.         LumenPassport::allowMultipleTokens(); # 允许生成多个有效Token
  28.     }
  29. }

5.4. 修改 ‘app/Models’ 文件夹下的 ‘UserModel.php’ 如下所示：

  1. # Dir: @/app/Models/UserModel.php
  2. <?php
  4. namespace App\Models;
  6. use Illuminate\Auth\Authenticatable;
  7. use Laravel\Lumen\Auth\Authorizable;
  8. use Illuminate\Database\Eloquent\Model;
  9. use Illuminate\Contracts\Auth\Authenticatable as AuthenticatableContract;
  10. use Illuminate\Contracts\Auth\Access\Authorizable as AuthorizableContract;
  11. use Laravel\Passport\HasApiTokens;
  13. /**
  14.  * @author AdamTyn
  15.  * @description <用户>数据模型
  16.  */
  17. class UserModel extends Model implements AuthenticatableContract, AuthorizableContract
  18. {
  19.     use Authenticatable, Authorizable, HasApiTokens;
  21.     /**
  22.      * 绑定数据表
  23.      * @var string
  24.      */
  25.     protected $table = 'users';
  27.     /**
  28.      * 使用模型时可以访问的字段
  29.      * @var array
  30.      */
  31.     protected $fillable = [
  32.         'user_name', 'password',
  33.     ];
  35.     /**
  36.      * 使用模型无法序列化为JSON时的字段
  37.      * @var array
  38.      */
  39.     protected $hidden = [
  40.         'password',
  41.     ];
  43.     /**
  44.      * 使用Passport用户凭证字段，数据库必须保证该字段的唯一性（默认是email）
  45.      * @var string
  46.      */
  47.     static private $credentials = 'user_name';
  49.     /**
  50.      * @author AdamTyn
  51.      * @description 使用用户凭证字段查询用户
  52.      *
  53.      * @param $username
  54.      * @return $this
  55.      */
  56.     public function findForPassport($username)
  57.     {
  58.         if (!isset(self::$credentials)) {
  59.             return $this->whereEmail($username)->first();
  60.         }
  61.         return $this->where(self::$credentials, $username)->first();
  62.     }
  63. }

5.5. 在 ‘app/Api/Controllers’ 文件夹下新建 ‘ClientController.php’，内容如下所示：

  1. # Dir: @/app/Api/Controllers/ClientController.php
  2. <?php
  4. namespace App\Api\Controllers;
  6. use Illuminate\Http\Request;
  7. use Laravel\Passport\ClientRepository;
  8. use Illuminate\Support\Facades\Hash;
  9. use Illuminate\Support\Facades\Log;
  10. use Laravel\Lumen\Routing\Controller;
  12. /**
  13.  * @author AdamTyn
  14.  * @description <用户客户端相关>控制器
  15.  */
  16. class ClientController extends Controller
  17. {
  18.     /**
  19.      * 用户客户端仓库的单例
  20.      * @var \Laravel\Passport\ClientRepository
  21.      */
  22.     private static $clientRepository = null;
  24.     /**
  25.      * 用户模型
  26.      * @var \App\Models\UserModel
  27.      */
  28.     private static $userModel = null;
  30.     /**
  31.      * 当前时间戳
  32.      * @var int
  33.      */
  34.     protected $currentDateTime;
  36.     /**
  37.      * 授权方式：password=密码授权的令牌，personal=私人授权的令牌
  38.      * @var string
  39.      */
  40.     protected $grantType = 'password';
  42.     /**
  43.      * @author AdamTyn
  44.      *
  45.      * AuthController constructor.
  46.      */
  47.     public function __construct()
  48.     {
  49.         empty(self::$userModel) ? (self::$userModel = (new \App\Models\UserModel)) : true;
  50.         $this->currentDateTime = time();
  51.     }
  53.     /**
  54.      * @author AdamTyn
  55.      * @description 用户注册（默认密码123456）
  56.      *
  57.      * @param \Illuminate\Http\Request;
  58.      * @return \Illuminate\Contracts\Routing\ResponseFactory|\Symfony\Component\HttpFoundation\Response
  59.      */
  60.     public function register(Request $request)
  61.     {
  62.         $field = [
  63.             'user_name' => $request->get('user_name') ?? time(),
  64.             'password' => Hash::make($request->get('password') ?? '123456')
  65.         ];
  67.         $user = (self::$userModel)->create($field);
  68.         $response['data'] = $user;
  70.         return response()->json($response);
  71.     }
  73.     /**
  74.      * @author AdamTyn
  75.      * @description 添加使用密码认证的客户端
  76.      *
  77.      * @param \Illuminate\Http\Request;
  78.      * @return \Illuminate\Contracts\Routing\ResponseFactory|\Symfony\Component\HttpFoundation\Response
  79.      */
  80.     public function registerPasswordClient(Request $request)
  81.     {
  82.         $response = array('status_code' => '2000');
  84.         try {
  85.             $user = (self::$userModel)->whereUserName($request->input('user_name'))->firstOrFail();
  86.             $this->createClient($response, $request, $user);
  87.         } catch (\Exception $exception) {
  88.             $response = [
  89.                 'status_code' => '5002',
  90.                 'msg' => '无法响应请求，服务端异常',
  91.             ];
  92.             Log::error($exception->getMessage() . ' at' . $this->currentDateTime);
  93.         }
  95.         return response()->json($response);
  96.     }
  98.     /**
  99.      * @author AdamTyn
  100.      * @description 登录私人访问的客户端
  101.      *
  102.      * @param \Illuminate\Http\Request;
  103.      * @return \Illuminate\Contracts\Routing\ResponseFactory|\Symfony\Component\HttpFoundation\Response
  104.      */
  105.     public function loginPersonalClient(Request $request)
  106.     {
  107.         $response = array('status_code' => '2000');
  108.         $this->changeGrantType();
  110.         try {
  111.             $user = (self::$userModel)->whereUserName($request->input('user_name'))->firstOrFail();
  112.             if (Hash::check($request->input('password'), $user->getAuthPassword())) {
  113.                 $response['data'] = $user->createToken(data_get($request, 'token_name', $user->user_name . '`s token_name'));
  114.             } else {
  115.                 $response = [
  116.                     'status_code' => '5000',
  117.                     'msg' => '系统错误',
  118.                 ];
  119.             }
  120.         } catch (\Exception $exception) {
  121.             $response = [
  122.                 'status_code' => '5002',
  123.                 'msg' => '无法响应请求，服务端异常',
  124.             ];
  125.             Log::error($exception->getMessage() . ' at' . $this->currentDateTime);
  126.         }
  128.         return response()->json($response);
  129.     }
  131.     /**
  132.      * @author AdamTyn
  133.      * @description 添加私人访问的客户端
  134.      *
  135.      * @param \Illuminate\Http\Request;
  136.      * @return \Illuminate\Contracts\Routing\ResponseFactory|\Symfony\Component\HttpFoundation\Response
  137.      */
  138.     public function registerPersonalClient(Request $request)
  139.     {
  140.         $response = array('status_code' => '2000');
  141.         $this->changeGrantType();
  143.         try {
  144.             $user = (self::$userModel)->whereUserName($request->input('user_name'))->firstOrFail();
  145.             $this->createClient($response, $request, $user);
  146.         } catch (\Exception $exception) {
  147.             $response = [
  148.                 'status_code' => '5002',
  149.                 'msg' => '无法响应请求，服务端异常',
  150.             ];
  151.             Log::error($exception->getMessage() . ' at' . $this->currentDateTime);
  152.         }
  154.         return response()->json($response);
  155.     }
  157.     /**
  158.      * @author AdamTyn
  159.      * @description 初始化用户客户端仓库的单例
  160.      *
  161.      * @return void
  162.      */
  163.     private function initialClientRepository()
  164.     {
  165.         empty(self::$clientRepository) ? (self::$clientRepository = (new ClientRepository)) : true;
  166.     }
  168.     /**
  169.      * @author AdamTyn
  170.      * @description 改变授权类型为私人访问
  171.      *
  172.      * @return void
  173.      */
  174.     private function changeGrantType()
  175.     {
  176.         $this->grantType = 'personal';
  177.     }
  179.     /**
  180.      * @author AdamTyn
  181.      * @description 新增用户客户端记录
  182.      *
  183.      * @param array $response
  184.      * @param \Illuminate\Http\Request $request
  185.      * @param \App\Models\UserModel $user
  186.      * @return void
  187.      */
  188.     private function createClient(&$response, $request, $user)
  189.     {
  190.         $this->initialClientRepository();
  192.         if (Hash::check($request->input('password'), $user->getAuthPassword())) {
  193.             $grantType = ($this->grantType == 'password');
  195.             $client = self::$clientRepository->create(
  196.                 $user->id,
  197.                 $user->user_name . '`s new ' . $this->grantType . ' client',
  198.                 data_get($request, 'redirect', 'http://localhost:8000'),
  199.                 !$grantType,
  200.                 $grantType
  201.             );
  203.             $response['data'] = [
  204.                 'client_id' => $client->id,
  205.                 'client_name' => $client->name,
  206.                 'client_grant_type' => $this->grantType,
  207.                 'client_secret' => $grantType ? $client->secret : null,
  208.                 'client_redirect' => $client->redirect,
  209.             ];
  210.         } else {
  211.             $response = [
  212.                 'status_code' => '5000',
  213.                 'msg' => '系统错误',
  214.             ];
  215.         }
  217.         return;
  218.     }
  219. }

5.6. 创建 ‘users’ 数据表，在数据库中简单填充一条数据。需要注意的是 Lumen 默认数据库使用 ‘utf8mb4’ 编码，如果数据库版本较低，需要修改‘app/Providers/AppServiceProvider.php’ 如下：

  1. # Dir: @/app/Providers/AppServiceProvider.php
  2. <?php
  4. namespace App\Providers;
  6. use Illuminate\Support\Facades\Schema;
  7. use Illuminate\Support\ServiceProvider;
  9. class AppServiceProvider extends ServiceProvider
  10. {
  11.     /**
  12.      * Register any application services.
  13.      *
  14.      * @return void
  15.      */
  16.     public function register()
  17.     {
  18.         Schema::defaultStringLength(191);
  19.     }
  20. }

5.7. 使用以下 Artisan 在数据库中新增 ‘Passport’ 的相关数据表，并且填充2条测试数据：

  1. php artisan migrate
  2. php artisan passport:install             <<<在oauth_clients表中填充了2条测试数据，并且生成了加密用的Key
  1. 运行测试。在‘routers/api.php’ 中添加相应的路由规则。 ```php

    Dir: @/routers/api.php

    <?php

模拟用户注册路由

$router->post(‘register’, ‘ClientController@register’);

模拟登录私人访问的客户端

$router->post(‘loginPersonalClient’, ‘ClientController@loginPersonalClient’);

模拟添加使用密码认证的客户端

$router->post(‘registerPasswordClient’, ‘ClientController@registerPasswordClient’);

模拟添加私人访问的客户端

$router->post(‘registerPersonalClient’, ‘ClientController@registerPersonalClient’);

Passport相关的路由已经被组件定义，无需自己定义

  1. 最后，可以得出以下测试结果。<br />
  2. ```php
  3. HTTP/1.1 200 OK. POST http://127.0.0.1:8000/register
  4. Request: user_name='testman', password='123456'
  5. {
  6.     "status_code": "2000",
  7.     "data": {
  8.         "user_name": "testman",
  9.         "updated_at": "2019-02-13 09:31:14",
  10.         "created_at": "2019-02-13 09:31:14",
  11.         "id": 5
  12.     }
  13. }
  1. HTTP/1.1 200 OK. POST http://127.0.0.1:8000/registerPasswordClient
  2. Request: user_name='testman', password='123456'
  3. {
  4.     "status_code": "2000",
  5.     "data": {
  6.         "client_id": 21,
  7.         "client_name": "testman`s new password client",
  8.         "client_grant_type": "password",
  9.         "client_secret": "hojrGJUQMzXAm9e9r7q1K01I1Rx8rWP3LgV5xW4a",
  10.         "client_redirect": "http://localhost:8000"
  11.     }
  12. }
  1. HTTP/1.1 200 OK. POST http://127.0.0.1:8000/registerPersonalClient
  2. Request: user_name='testman', password='123456'
  3. {
  4.     "status_code": "2000",
  5.     "data": {
  6.         "client_id": 22,
  7.         "client_name": "testman`s new personal client",
  8.         "client_grant_type": "personal",
  9.         "client_secret": null,
  10.         "client_redirect": "http://localhost:8000"
  11.     }
  12. }
  1. HTTP/1.1 200 OK. POST http://127.0.0.1:8000/loginPersonalClient
  2. Request: user_name='testman',token_name='testman_token', password='123456'
  3. {
  4.     "status_code": "2000",
  5.     "data": {
  6.         "accessToken": "eyJ0eXiIsImp0aSI6IjRkYmQ4ZGZDM5YmVmOTVlYzk4ZW6c",
  7.         "token": {
  8.             "id": "4dbd8dd35a8c109a40629d9a204915e7a22db0bd6dc",
  9.             "user_id": 2,
  10.             "client_id": 20,
  11.             "name": "testman_token",
  12.             "scopes": [],
  13.             "revoked": false,
  14.             "created_at": "2019-02-13 09:33:50",
  15.             "updated_at": "2019-02-13 09:33:50",
  16.             "expires_at": "2020-02-13 09:33:50"
  17.         }
  18.     }
  19. }
  1. HTTP/1.1 200 OK. GET http://127.0.0.1:8000/oauth/tokens
  2. Authorization: Bearer eyJ0eXiIsImp0aSI6IjRkYmQ4ZGZDM5YmVmOTVlYzk4ZW6c
  3. [
  4.     {
  5.         "id": "5fc4cf22e2b5386660659775fc5919",
  6.         "user_id": 2,
  7.         "client_id": 20,
  8.         "name": "token_name",
  9.         "scopes": [],
  10.         "revoked": false,
  11.         "created_at": "2019-02-13 08:52:31",
  12.         "updated_at": "2019-02-13 08:52:31",
  13.         "expires_at": "2020-02-13 08:52:31",
  14.         "client": {
  15.             "id": 20,
  16.             "user_id": null,
  17.             "name": "test",
  18.             "redirect": "http://localhost",
  19.             "personal_access_client": true,
  20.             "password_client": false,
  21.             "revoked": false,
  22.             "created_at": "2019-02-13 08:48:48",
  23.             "updated_at": "2019-02-13 08:48:48"
  24.         }
  25.     }
  26. ]
  1. HTTP/1.1 200 OK. GET http://127.0.0.1:8000/oauth/clients
  2. Authorization: Bearer eyJ0eXiIsImp0aSI6IjRkYmQ4ZGZDM5YmVmOTVlYzk4ZW6c
  3. [
  4.     {
  5.         "id": 3,
  6.         "user_id": 1,
  7.         "name": " Password Grant Client",
  8.         "secret": "FfA04DRjDA9iMi4RJ9ju9mBtmKDyu4HbHYXRCoKD",
  9.         "redirect": "http://localhost",
  10.         "personal_access_client": false,
  11.         "password_client": true,
  12.         "revoked": false,
  13.         "created_at": "2019-02-13 14:43:58",
  14.         "updated_at": "2019-02-13 14:43:58"
  15.     }
  16. ]
  1. 放出参考的示例 Code。至此，Lumen5.7使用Passport 讲解结束，给出所有 Passport 中预设的路由规则：

Lumen5.7使用Passport【2019.02.13最新教程】，更新啦 - 图1

四、结语

  1. 本教程面向新手，更多教程会在日后给出。
  2. 随着系统升级，软件更新，以后的配置可能有所变化，在下会第一时间测试并且更新教程。
  3. 欢迎联系在下，讨论建议都可以，之后会发布其它的教程。
  4. 如果读者使用的是旧版本 Lumen，可以参考本人之前出了 Lumen5.4使用OAuth2.0基于Passport【最新教程】 以及Lumen5.4配置OAuth2.0【强迫症，就是要用最新版本的Lumen】 教程。
  5. 后面紧锣密鼓地将会推出 Laravel业务篇 系列的教程，敬请期待。