Laravel 的 API 认证系统 Passport

介绍

在 Laravel 中,实现基于传统表单的登陆和授权已经非常简单,但是如何满足 API 场景下的授权需求呢?在 API 场景里通常通过令牌来实现用户授权,而非维护请求之间的 Session 状态。在 Laravel 项目中使用 Passport 可以轻而易举地实现 API 授权认证,Passport 可以在几分钟之内为你的应用程序提供完整的 OAuth2 服务端实现。Passport 是基于由 Alex Bilbie 维护的 League OAuth2 server 建立的。

{note} 本文档假定你已熟悉 OAuth2 。如果你并不了解 OAuth2 ,阅读之前请先熟悉下 OAuth2 的常用术语和功能。

安装

使用 Composer 安装 Passport :

composer require laravel/passport

接下来,将 Passport 的服务提供者注册到配置文件 config/app.phpproviders 数组中:

Laravel\Passport\PassportServiceProvider::class,

Passport 服务提供器使用框架注册自己的数据库迁移目录,因此在注册提供器后,就应该运行 Passport 的迁移命令来自动创建存储客户端和令牌的数据表:

php artisan migrate

{note} 如果你不打算使用 Passport 的默认迁移,你应该在 AppServiceProviderregister 方法中调用 Passport::ignoreMigrations 方法。 你可以用这个命令 php artisan vendor:publish --tag=passport-migrations 导出默认迁移。

接下来,运行 passport:install 命令来创建生成安全访问令牌时所需的加密密钥,同时,这条命令也会创建用于生成访问令牌的「个人访问」客户端和「密码授权」客户端:

php artisan passport:install

上面命令执行后,请将 Laravel\Passport\HasApiTokens Trait 添加到 App\User 模型中,这个 Trait 会给你的模型提供一些辅助函数,用于检查已认证用户的令牌和使用范围:

<?php

namespace App;

use Laravel\Passport\HasApiTokens;
use Illuminate\Notifications\Notifiable;
use Illuminate\Foundation\Auth\User as Authenticatable;

class User extends Authenticatable
{
    use HasApiTokens, Notifiable;
}

接下来,在 AuthServiceProviderboot 方法中调用 Passport::routes 函数。这个函数会注册发出访问令牌并撤销访问令牌、客户端和个人访问令牌所必需的路由:

<?php

namespace App\Providers;

use Laravel\Passport\Passport;
use Illuminate\Support\Facades\Gate;
use Illuminate\Foundation\Support\Providers\AuthServiceProvider as ServiceProvider;

class AuthServiceProvider extends ServiceProvider
{
    /**
     * 应用程序的策略映射。
     *
     * @var array
     */
    protected $policies = [
        'App\Model' => 'App\Policies\ModelPolicy',
    ];

    /**
     * Register any authentication / authorization services.
     *
     * @return void
     */
    public function boot()
    {
        $this->registerPolicies();

        Passport::routes();
    }
}

最后,将配置文件 config/auth.php 中授权看守器 guardsapidriver 选项改为 passport。此调整会让你的应用程序在在验证传入的 API 的请求时使用 Passport 的 TokenGuard 来处理:

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

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

前端快速上手

{note} 如果想要使用 Passport 的 Vue 组件,那么你必须使用 Vue Javascript 框架,另外这些组件还用到了 Bootstrap CSS 框架。当然你也可以不使用上面的任何工具,但在实现你自己的前端部分时,Passport 的 Vue 组件仍旧有很高的参考价值。

Passport 配备了一些可以让你的用户自行创建客户端和个人访问令牌的 JSON API。然而,编写一些前端代码来与这些 API 进行交互很是耗时。因此 Passport 也引入了预先构建的 Vue 组件,你可以直接使用,也可以基于这些代码实现自己的前端部分。

使用 Artisan 命令 vendor:publish 来发布 Passport 的 Vue 组件:

php artisan vendor:publish --tag=passport-components

已发布的组件将被放置在 resources/assets/js/components 目录中,可以在 resources/assets/js/app.js 文件中注册它们:

Vue.component(
    'passport-clients',
    require('./components/passport/Clients.vue')
);

Vue.component(
    'passport-authorized-clients',
    require('./components/passport/AuthorizedClients.vue')
);

Vue.component(
    'passport-personal-access-tokens',
    require('./components/passport/PersonalAccessTokens.vue')
);

这些组件注册后,运行 npm install安装vue所依赖的文件,运行npm run dev 命令以确保重新编译你的资源。重新编译资源后,你可以将这些组件放入应用程序的模板中,然后开始创建客户端和个人访问令牌:

<passport-clients></passport-clients>
<passport-authorized-clients></passport-authorized-clients>
<passport-personal-access-tokens></passport-personal-access-tokens>

部署 Passport

第一次将 Passport 部署到生产服务器时,需要运行 passport:keys 命令。该命令生成 Passport 所需要的用来产生访问令牌的加密密钥。生成的这些密钥不会保存在源码控制中:

php artisan passport:keys

配置

令牌的有效期

默认情况下,Passport 发放的访问令牌是永久有效的,不需要刷新。但是如果你想自定义访问令牌的有效期,可以使用 tokensExpireInrefreshTokensExpireIn 方法。上述两个方法同样需要在 AuthServiceProviderboot 方法中调用:

use Carbon\Carbon;

/**
 * Register any authentication / authorization services.
 *
 * @return void
 */
public function boot()
{
    $this->registerPolicies();

    Passport::routes();

    Passport::tokensExpireIn(Carbon::now()->addDays(15));

    Passport::refreshTokensExpireIn(Carbon::now()->addDays(30));
}

发放访问令牌

熟悉 OAuth2 的开发者一定知道, OAuth2 中必不可少的部分就是授权码。当使用授权码时,客户端应用程序会将用户重定向到你的服务器,他们将批准或拒绝向客户端发出访问令牌的请求。

管理客户端

首先,构建需要与应用程序 API 交互的应用程序,开发人员将需要通过创建一个「客户端」来注册自己的应用程序。一般来说,这包括在用户批准其授权请求后,提供其应用程序的名称和应用程序可以重定向到的 URL。

passport:client 命令

创建客户端最简单的方式是使用 Artisan 命令 passport:client,你可以使用此命令创建自己的客户端,用于测试你的 OAuth2 的功能。在你执行 client 命令时,Passport 会提示你输入有关客户端的信息,最终会给你提供客户端的 ID 和 密钥:

php artisan passport:client

JSON API

考虑到你的用户无法使用 client 命令,Passport 为此提供了可用于创建客户端的 JSON API。这样你就不用再花时间编写控制器来创建、更新和删除客户端。

然而,你仍旧需要基于 Passport 的 JSON API 开发一套前端界面,为你的用户提供管理客户端的仪表板。下面我们会列出所有用于管理客户端的 API,为了方便起见,我们使用 Axios 来演示对端口发出 HTTP 请求。

{tip} 如果你不想自己实现整个客户端管理的前端界面,可以使用 前端快速上手 在几分钟内组建一套功能齐全的前端界面。

GET /oauth/clients

此路由会返回认证用户的所有客户端。主要用途是列出所有用户的客户端,以便他们可以编辑或删除它们:

axios.get('/oauth/clients')
    .then(response => {
        console.log(response.data);
    });

POST /oauth/clients

此路由用于创建新客户端。它需要两部分数据:客户端的 nameredirect 的链接。在批准或拒绝授权请求后,用户会被重定向 redirect 到这个链接。

创建客户端时,会发出此客户端的 ID 和密钥。客户端可以使用这两个值从你的应用程序请求访问令牌。该路由会返回新的客户端实例:

const data = {
    name: 'Client Name',
    redirect: 'http://example.com/callback'
};

axios.post('/oauth/clients', data)
    .then(response => {
        console.log(response.data);
    })
    .catch (response => {
        // List errors on response...
    });

PUT /oauth/clients/{client-id}

此路由用于更新客户端信息。它需要两部分数据:客户端的 nameredirect 的链接。在批准或拒绝授权请求后,用户会被重定向 redirect 到这个链接。此路由会返回更新的客户端实例:

const data = {
    name: 'New Client Name',
    redirect: 'http://example.com/callback'
};

axios.put('/oauth/clients/' + clientId, data)
    .then(response => {
        console.log(response.data);
    })
    .catch (response => {
        // List errors on response...
    });

DELETE /oauth/clients/{client-id}

此路由用于删除客户端:

axios.delete('/oauth/clients/' + clientId)
    .then(response => {
        //
    });

请求令牌

授权时的重定向

客户端创建之后,开发者会使用此客户端的 ID 和密钥来请求授权代码,并从应用程序访问令牌。首先,接入应用的用户向你应用程序的 /oauth/authorize 路由发出重定向请求,示例如下:

Route::get('/redirect', function () {
    $query = http_build_query([
        'client_id' => 'client-id',
        'redirect_uri' => 'http://example.com/callback',
        'response_type' => 'code',
        'scope' => '',
    ]);

    return redirect('http://your-app.com/oauth/authorize?'.$query);
});

{tip} 注意,路由 /oauth/authorize 已经在 Passport::routes 方法中定义。你不需要手动定义此路由。

批准请求

接收到授权请求时,Passport 会自动向用户显示一个模版页面,允许用户批准或拒绝授权请求。如果用户批准请求,他们会被重定向回接入的应用程序指定的 redirect_uriredirect_uri 必须和客户端创建时指定的 redirect 链接完全一致。

如果你想自定义授权确认页面,可以使用 Artisan 命令 vendor:publish 发布 Passport 的视图。发布后的视图文件存放在 resources/views/vendor/passport

php artisan vendor:publish --tag=passport-views

将授权码转换为访问令牌

用户批准授权请求后,会被重定向回接入的应用程序。然后接入应用应该将通过 POST 请求向你的应用程序申请访问令牌。请求应该包括当用户批准授权请求时由应用程序发出的授权码。在下面的例子中,我们使用 Guzzle HTTP 库来实现这次 POST 请求:

Route::get('/callback', function (Request $request) {
    $http = new GuzzleHttp\Client;

    $response = $http->post('http://your-app.com/oauth/token', [
        'form_params' => [
            'grant_type' => 'authorization_code',
            'client_id' => 'client-id',
            'client_secret' => 'client-secret',
            'redirect_uri' => 'http://example.com/callback',
            'code' => $request->code,
        ],
    ]);

    return json_decode((string) $response->getBody(), true);
});

路由 /oauth/token 返回的 JSON 响应中会包含 access_tokenrefresh_tokenexpires_in 属性。expires_in 属性包含访问令牌的有效期(单位:秒)。

{tip} 像 /oauth/authorize 路由一样,/oauth/token 路由在 Passport::routes 方法中定义了。

刷新令牌

如果你的应用程序发放了短期的访问令牌,用户将需要通过在发出访问令牌时提供给他们的刷新令牌来刷新其访问令牌。在下面的例子中,我们使用 Guzzle HTTP 库来刷新令牌:

$http = new GuzzleHttp\Client;