[ Laravel 5.3 文档 ] 安全 ―― API认证（Passport）保障安全性。

1、简介

Laravel通过传统的登录表单已经让用户认证变得很简单，但是API怎么办？API通常使用token进行认证并且在请求之间不维护session状态。Laravel使用LaravelPassport让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\HasApiTokens trait到 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,
],