API认证（Passport）

Created 8 years ago by 学院君, Updated 4 years ago Revision #2 59101 views 11 likes 0 collects

1、简介

Laravel通过传统的登录表单已经让用户认证变得很简单，但是API怎么办？API通常使用token进行认证并且在请求之间不维护session状态。Laravel使用Laravel Passport让API认证变得轻而易举，Passport基于Alex Bilbie维护的League OAuth2 server，可以在数分钟内为Laravel应用提供完整的OAuth2服务器实现。

注：本文档假设你已经很熟悉OAuth2，如果你对OAuth2一无所知，那么在开始学习文文档之前，先要去熟悉OAuth2的一些术语和特性（参考阮一峰博客：理解OAuth 2.0）。

2、安装

使用Composer包管理器安装Passport：

composer require laravel/passport

接下来，在配置文件config/app.php的providers数组中注册Passport服务提供者：

Laravel\Passport\PassportServiceProvider::class,

Passport服务提供着为框架注册了自己的数据库迁移目录，所以在注册之后需要迁移数据库，Passport迁移将会为应用生成用于存放客户端和访问令牌的数据表：

php artisan migrate

接下来，需要运行passport:install命令，该命令将会创建生成安全访问令牌（token）所需的加密键，此外，该命令还会创建“personal access”和“password grant”客户端用于生成访问令牌：

php artisan passport:install

运行完这个命令后，添加Laravel\Passport\HasApiTokenstrait到App\User模型，该trait将会为模型类提供一些辅助函数用于检查认证用户的token和scope：

<?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;
}

接下来，你需要在AuthServiceProvider的boot方法中调用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
{
    /**
     * The policy mappings for the application.
     *
     * @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中，需要设置api认证guard的driver选项为passport。这将告知应用在认证输入的API请求时使用Passport的TokenGuard：

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

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

前端快速上手

注：为了使用Passport的Vue组件，前端JavaScript必须使用Vue框架，这些组件同时也使用了Bootstrap CSS框架。不过，即使你不使用这些工具，这些组件同样可以为你实现自己的前端组件提供有价值的参考。

Passport附带了JSON API以便用户创建客户端和私人访问令牌（access token）。不过，考虑到编写前端代码与这些API交互是一件很花费时间的事，Passport还预置了Vue组件作为示例以供使用（或者作为自己实现的参考）。

要发布Passport Vue组件，可以使用 vendor:publish 命令：

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')
);

注册完成后，就可以将它们放到应用的某个模板中以便创建客户端和私人访问令牌：

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

3、配置

令牌生命周期

默认情况下，Passport颁发的访问令牌（access token）是长期有效的，如果你想要配置更短的令牌生命周期，可以使用 tokensExpireIn 和 refreshTokensExpireIn 方法，这些方法需要在 AuthServiceProvider 的 boot 方法中调用：

/**
 * 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));
}

精简撤销令牌

默认情况下，Passport不会从数据库删除撤销的访问令牌，随着时间的推移，在数据库中会累积大量的撤销令牌，如果你希望Passport可以自动删除撤销的令牌，可以在 AuthServiceProvider 的 boot 方法中调用 pruneRevokedTokens 方法：

use Laravel\Passport\Passport;

Passport::pruneRevokedTokens();

该方法不会立即删除所有的撤销令牌，而是当用户请求一个新的访问令牌或者刷新已存在令牌的时候才会删除撤销的令牌。

4、颁发访问令牌

通过授权码使用OAuth2是大多数开发者属性的方式。使用授权码的时候，客户端应用会将用户重定向到你的服务器，服务器将会通过或决绝颁发访问令牌到客户端的请求。

管理客户端

首先，开发构建和你的应用API交互的应用时，需要通过创建一个“客户端”以便将他们的应用注册到你的应用。通常，这一过程包括提供应用的名称以及用户授权请求通过后重定向到的URL。

passport:client命令

创建客户端最简单的方式就是使用Artisan命令 passport:client ，该命令可用于创建你自己的客户端以方便测试OAuth2功能。当你运行 client 命令时，Passport会提示你关于客户端的更多信息，并且为你提供client ID和secret：

php artisan passport:client

JSON API

由于用户不能使用client命令，Passport提供了一个JSON API用于创建客户端，这省去了你手动编写控制器用于创建、更新以及删除客户端的麻烦。

不过，你需要配对Passport的JSON API和自己的前端以便为用户提供一个可以管理他们自己客户端的后台，下面，我们来回顾下所有用于管理客户端的API，为了方便，我们将会使用Vue来演示发送HTTP请求到API：

注：如果你不想要自己实现整个客户端管理前端，可以使用前端快速上手教程在数分钟内拥有完整功能的前端。

GET /oauth/clients

这个路由为认证用户返回所有客户端，这在展示用户客户端列表时很有用，可以让用户很容易编辑或删除客户端：

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

POST /oauth/clients

这个路由用于创建新的客户端，要求传入两个数据：客户端的 name 和 redirect URL， redirect URL是用户授权请求通过或拒绝后重定向到的位置。

当客户端被创建后，会附带一个client ID和secret，这两个值会在请求访问令牌时用到。客户端创建路由会返回新的客户端实例：

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

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

PUT /oauth/clients/{client-id}

这个路由用于更新客户端，要求传入两个参数：客户端的 name 和 redirect URL。 redirect URL是用户授权请求通过或拒绝后重定向到的位置。该路由将会返回更新后的客户端实例：

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

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

DELETE /oauth/clients/{client-id}

这个路由用于删除客户端：

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

请求令牌

授权重定向

客户端被创建后，开发者就可以使用相应的client ID和secret从应用请求授权码和访问令牌。首先，消费者应用要生成一个重定向请求到应用的 /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);
});

注：记住， /oauth/authorize 路由已经通过 Passport::routes 方法定义了，不需要手动定义这个路由。

通过请求

接收授权请求的时候，Passport会自动显示一个视图模板给用户从而允许他们通过或拒绝授权请求，如果用户通过请求，就会被重定向回消费者应用指定的 redirect_uri ，这个 redirect_uri 必须和客户端创建时指定的 redirect URL一致。

如果你想要自定义授权通过界面，可以使用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 路由会返回一个包含 access_token 、 refresh_token 和 expires_in 属性的JSON响应。 expires_in 属性包含访问令牌的过期时间（s）。

注：和 /oauth/authorize 路由一样， /oauth/token 路由已经通过 Passport::routes 方法定义过了，不需要手动定义这个路由。

刷新令牌

如果应用颁发的是短期有效的访问令牌，那么用户需要通过访问令牌颁发时提供的 refresh_token 刷新访问令牌，在这个例子中，我们使用Guzzle HTTP库来刷新令牌：

$http = new GuzzleHttp\Client;

$response = $http->post('http://your-app.com/oauth/token', [
    'form_params' => [
        'grant_type' => 'refresh_token',
        'refresh_token' => 'the-refresh-token',
        'client_id' => 'client-id',
        'client_secret' => 'client-secret',
        'scope' => '',
    ],
]);

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

/oauth/token 路由会返回一个包含 access_token 、 refresh_token 和 expires_in 属性的JSON响应，同样， expires_in 属性包含访问令牌过期时间（s）。

5、密码发放令牌

OAuth2 密码发放允许你的其他第一方客户端，例如移动应用，使用邮箱地址/用户名+密码获取访问令牌。这使得你可以安全地颁发访问令牌给第一方客户端而不必要求你的用户走整个OAuth2授权码重定向流程。

创建一个密码发放客户端

在应用可以通过密码发放颁发令牌之前，需要创建一个密码发放客户端，你可以通过使用带 --password 选项的 passport:client 命令来实现。如果你已经运行了 passport:install 命令，则不必再运行这个命令：

php artisan passport:client --password

请求令牌

创建完密码发放客户端后，可以通过发送POST请求到 /oauth/token 路由（带上用户邮箱地址和密码参数）获取访问令牌。这个路由已经通过 Passport::routes 方法注册过了，不需要手动定义。如果请求成功，就可以从服务器返回的JSON响应中获取 access_token 和 refresh_token ：

$http = new GuzzleHttp\Client;

$response = $http->post('http://your-app.com/oauth/token', [
    'form_params' => [
        'grant_type' => 'password',
        'client_id' => 'client-id',
        'client_secret' => 'client-secret',
        'username' => 'taylor@laravel.com',
        'password' => 'my-password',
        'scope' => '',
    ],
]);

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

注：记住，访问令牌默认长期有效，不过，如果需要的话你也可以配置访问令牌的最长生命周期。

请求所有域

使用密码发放的时候，你可能想要授权应用所支持的所有域的令牌，这可以通过请求 * 域来实现。如果你请求的是 * 域，则令牌实例上的can方法总是返回true，这个域只会分配给使用 password 发放的令牌：

$response = $http->post('http://your-app.com/oauth/token', [
    'form_params' => [
        'grant_type' => 'password',
        'client_id' => 'client-id',
        'username' => 'taylor@laravel.com',
        'password' => 'my-password',
        'scope' => '*',
    ],
]);

6、私人访问令牌

有时候，你的用户可能想要颁发访问令牌给自己而不走典型的授权码重定向流程。允许用户通过应用的UI颁发令牌给自己在用户体验你的API或者作为更简单的颁发访问令牌方式时会很有用。

注：私人访问令牌总是一直有效的，它们的生命周期在使用 tokensExpireIn 或 refreshTokensExpireIn 方法时不会修改。

创建一个私人访问客户端

在你的应用可以颁发私人访问令牌之前，需要创建一个私人的访问客户端。你可以通过带 --personal 选项的 passport:client 命令来实现，如果你已经运行过了 passport:install 命令，则不必再运行此命令：

php artisan passport:client --personal

管理私人访问令牌

创建好私人访问客户端之后，就可以使用User模型实例上的 createToken 方法为给定用户颁发令牌。 createToken 方法接收令牌名称作为第一个参数，以及一个可选的域数组作为第二个参数：

$user = App\User::find(1);

// Creating a token without scopes...
$token = $user->createToken('Token Name')->accessToken;

// Creating a token with scopes...
$token = $user->createToken('My Token', ['place-orders'])->accessToken;

JSON API

Passport还提供了一个JSON API用于管理私人访问令牌，你可以将其与自己的前端配对以便为用户提供管理私人访问令牌的后台。下面，我们来回顾用于管理私人访问令牌的所有API。为了方便起见，我们使用Vue来演示发送HTTP请求到API。

注：如果你不想要实现自己的私人访问令牌前端，可以使用前端快速上手教程在数分钟内打造拥有完整功能的前端。

GET /oauth/scopes

这个路由会返回应用所定义的所有域。你可以使用这个路由来列出用户可以分配给私人访问令牌的所有域：

this.$http.get('/oauth/scopes')
    .then(response => {
        console.log(response.data);
    });

GET /oauth/personal-access-tokens

这个路由会返回该认证用户所创建的所有私人访问令牌，这在列出用户的所有令牌以便编辑或删除时很有用：

this.$http.get('/oauth/personal-access-tokens')
    .then(response => {
        console.log(response.data);
    });

POST /oauth/personal-access-tokens

这个路由会创建一个新的私人访问令牌，该路由要求传入两个参数：令牌的 name 和需要分配到这个令牌的 scopes ：

const data = {
    name: 'Token Name',
    scopes: []
};

this.$http.post('/oauth/personal-access-tokens', data)
    .then(response => {
        console.log(response.data.accessToken);
    })
    .catch (response => {
        // List errors on response...
    });

DELETE /oauth/personal-access-tokens/{token-id}

这个路由可以用于删除私人访问令牌：

this.$http.delete('/oauth/personal-access-tokens/' + tokenId);

7、路由保护

通过中间件

Passport提供了一个认证guard用于验证输入请求的访问令牌，当你使用 passport 驱动配置好 api guard后，只需要在所有路由上指定需要传入有效访问令牌的 auth:api 中间件即可：

Route::get('/user', function () {
    //
})->middleware('auth:api');

传递访问令牌

调用被Passport保护的路由时，应用的API消费者需要在请求的 Authorization 头中指定它们的访问令牌作为 Bearer 令牌。例如：

$response = $client->request('GET', '/api/user', [
    'headers' => [
        'Accept' => 'application/json',
        'Authorization' => 'Bearer '.$accessToken,
    ],
]);

8、令牌作用域

定义作用域

作用域（Scope）允许API客户端在请求账户授权的时候请求特定的权限集合。例如，如果你在构建一个电子商务应用，不是所有的API消费者都需要下订单的能力，取而代之地，你可以让这些消费者只请求访问订单物流状态的权限，换句话说，作用域允许你的应用用户限制第三方应用自身可以执行的操作。

你可以在 AuthServiceProvider 的 boot 方法中使用 Passport::tokensCan 方法定义API的作用域。 tokensCan 方法接收作用域名称数组和作用域描述，作用域描述可以是任何你想要在授权通过页面展示给用户的东西：

use Laravel\Passport\Passport;

Passport::tokensCan([
    'place-orders' => 'Place orders',
    'check-status' => 'Check order status',
]);

分配作用域到令牌

请求授权码时

当使用授权码请求访问令牌时，消费者应该指定他们期望的作用域作为 scope 查询字符串参数， scope 参数是通过空格分隔的作用域列表：

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

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

颁发私人访问令牌时

如果你使用 User 模型的 createToken 方法颁发私人访问令牌，可以传递期望的作用域数组作为该方法的第二个参数：

$token = $user->createToken('My Token', ['place-orders'])->accessToken;

检查作用域

Passport提供两个可用于验证输入请求是否经过已发放作用域的令牌认证的中间件。开始之前，添加下面的中间件到 app/Http/Kernel.php 文件的 $routeMiddleware 属性：

'scopes' => \Laravel\Passport\Http\Middleware\CheckScopes::class,
'scope' => \Laravel\Passport\Http\Middleware\CheckForAnyScope::class,

检查所有作用域

scopes 中间件会分配给一个用于验证输入请求的访问令牌拥有所有列出作用域的路由：

Route::get('/orders', function () {
    // Access token has both "check-status" and "place-orders" scopes...
})->middleware('scopes:check-status,place-orders');

检查任意作用域

scope 中间件会分配给一个用于验证输入请求的访问令牌拥有至少一个列出作用域的路由：

Route::get('/orders', function () {
    // Access token has either "check-status" or "place-orders" scope...
})->middleware('scope:check-status,place-orders');

检查令牌实例上的作用域

当一个访问令牌认证过的请求进入应用后，你仍然可以使用经过认证的 User 实例上的 tokenCan 方法来检查这个令牌是否拥有给定作用域：

use Illuminate\Http\Request;

Route::get('/orders', function (Request $request) {
    if ($request->user()->tokenCan('place-orders')) {
        //
    }
});

9、使用JavaScript消费API

构建API时，能够从你的JavaScript应用消费你自己的API非常有用。这种API开发方式允许你自己的应用消费你和其他人分享的同一个API，这个API可以被你的Web应用消费，也可以被你的移动应用分配，还可以被第三方应用消费，以及任何你可能发布在多个包管理器上的SDK消费。

通常，如果你想要从你的JavaScript应用消费自己的API，需要手动发送访问令牌到应用并在应用的每一个请求中传递它。不过，Passport提供了一个中间件用于处理这一操作。你所需要做的只是添加这个中间件 CreateFreshApiToken 到 web 中间件组：

'web' => [
    // Other middleware...
    \Laravel\Passport\Http\Middleware\CreateFreshApiToken::class,
],

这个Passport中间件将会附加 laravel_token cookie到输出响应，这个cookie包含加密过的JWT，Passport将使用这个JWT来认证来自JavaScript应用的API请求，现在，你可以发送请求到应用的API，而不必显示传递访问令牌：

this.$http.get('/user')
    .then(response => {
        console.log(response.data);
    });

使用认证的这个方法时，你需要在每个请求中通过 X-CSRF-TOKEN 头发送CSRF令牌，如果你使用的是框架提供的默认Vue配置的话，Laravel会自动发送这个头：

Vue.http.interceptors.push((request, next) => {
    request.headers['X-CSRF-TOKEN'] = Laravel.csrfToken;

    next();
});

注：如果你使用的是其它JavaScript框架，需要确保每个请求都被配置为发送这个请求头。

Vote Vote Cancel

Collect Collect Cancel

Donate

发行版本说明

升级指南

贡献代码

安装

配置

目录结构

Laravel Homestead

Laravel Valet

服务提供者

服务容器

门面（Facades）

契约（Contracts）

路由

中间件

CSRF保护

控制器

请求

响应

Session

验证

视图

Blade模板

本地化

起步

编译资源（Laravel Elixir）

用户认证

API认证（Passport）

用户授权

密码重置

加密

哈希

事件广播

缓存

错误&日志

事件

文件存储

邮件

通知

队列

起步

查询构建器

分页

迁移

填充数据

Redis

起步

关联关系

集合

访问器&修改器

序列化

控制台命令

任务调度

起步

应用测试

数据库

模拟

Laravel Cashier

Envoy Task Runner

Laravel Scout

Laravel Socialite

集合

辅助函数

包开发

API认证（Passport）

1、简介

2、安装

前端快速上手

3、配置

令牌生命周期

精简撤销令牌

4、颁发访问令牌

管理客户端

请求令牌

刷新令牌

5、密码发放令牌

创建一个密码发放客户端

请求令牌

请求所有域

6、私人访问令牌

创建一个私人访问客户端