API 认证 · laravel 5.4

<article><h1>Laravel 的 API 认证系统 Passport</h1><ul><li><a href="#introduction">介绍</a></li><li><a href="#installation">安装</a><ul><li><a href="#frontend-quickstart">前端快速上手</a></li></ul></li><li><a href="#configuration">配置</a><ul><li><a href="#token-lifetimes">令牌的使用期限</a></li></ul></li><li><a href="#issuing-access-tokens">发放访问令牌</a><ul><li><a href="#managing-clients">管理客户端</a></li><li><a href="#requesting-tokens">请求令牌</a></li><li><a href="#refreshing-tokens">刷新令牌</a></li></ul></li><li><a href="#password-grant-tokens">密码授权令牌</a><ul><li><a href="#creating-a-password-grant-client">创建密码授权客户端</a></li><li><a href="#requesting-password-grant-tokens">请求密码授权令牌</a></li><li><a href="#requesting-all-scopes">请求所有作用域</a></li></ul></li><li><a href="#implicit-grant-tokens">简化授权令牌</a></li><li><a href="#client-credentials-grant-tokens">客户端授权令牌</a></li><li><a href="#personal-access-tokens">私人访问令牌</a><ul><li><a href="#creating-a-personal-access-client">创建私人访问令牌的客户端</a></li><li><a href="#managing-personal-access-tokens">管理私人访问令牌</a></li></ul></li><li><a href="#protecting-routes">路由保护</a><ul><li><a href="#via-middleware">通过中间件</a></li><li><a href="#passing-the-access-token">传递访问令牌</a></li></ul></li><li><a href="#token-scopes">令牌作用域</a><ul><li><a href="#defining-scopes">定义作用域</a></li><li><a href="#assigning-scopes-to-tokens">给令牌分派作用域</a></li><li><a href="#checking-scopes">检查作用域</a></li></ul></li><li><a href="#consuming-your-api-with-javascript">使用 JavaScript 接入 API</a></li><li><a href="#events">事件</a></li><li><a href="#testing">测试</a></li></ul><a name="introduction"></a><h2><a href="#introduction">介绍</a></h2>在 Laravel 中，实现基于传统表单的登陆和授权已经非常简单，但是如何满足 API 场景下的授权需求呢？在 API 场景里通常通过令牌来实现用户授权，而非维护请求之间的 Session 状态。现在 Laravel 项目中可以使用 Passport 轻而易举地实现 API 授权过程，通过 Passport 可以在几分钟之内为你的应用程序添加完整的 OAuth2 服务端实现。 Passport 基于 <a href="https://github.com/thephpleague/oauth2-server">League OAuth2 server</a> 实现，该项目的维护人是 <a href="https://github.com/alexbilbie">Alex Bilbie</a> 。<blockquote class="has-icon note"><div class="flag"><svg xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:a="http://ns.adobe.com/AdobeSVGViewerExtensions/3.0/" version="1.1" x="0px" y="0px" width="90px" height="90px" viewBox="0 0 90 90" enable-background="new 0 0 90 90" xml:space="preserve"><path fill="#FFFFFF" d="M45 0C20.1 0 0 20.1 0 45s20.1 45 45 45 45-20.1 45-45S69.9 0 45 0zM45 74.5c-3.6 0-6.5-2.9-6.5-6.5s2.9-6.5 6.5-6.5 6.5 2.9 6.5 6.5S48.6 74.5 45 74.5zM52.1 23.9l-2.5 29.6c0 2.5-2.1 4.6-4.6 4.6 -2.5 0-4.6-2.1-4.6-4.6l-2.5-29.6c-0.1-0.4-0.1-0.7-0.1-1.1 0-4 3.2-7.2 7.2-7.2 4 0 7.2 3.2 7.2 7.2C52.2 23.1 52.2 23.5 52.1 23.9z"></path></svg></div> 本文档假定你已熟悉 OAuth2 。如果你并不了解 OAuth2 ，阅读之前请先熟悉下 OAuth2 的常用术语和基本特征。</blockquote><a name="installation"></a><h2><a href="#installation">安装</a></h2>使用 Composer 依赖包管理器安装 Passport ：<pre class=" language-php"><code class=" language-php">composer require laravel/passport</code></pre>接下来，将 Passport 的服务提供者注册到配置文件 <code class=" language-php">config/app.php</code> 的 <code class=" language-php">providers</code> 数组中：<pre class=" language-php"><code class=" language-php">Laravel\Passport\PassportServiceProvider::class,</code></pre>Passport 使用服务提供者注册内部的数据库迁移脚本目录，所以上一步完成后，你需要更新你的数据库结构。Passport 的迁移脚本会自动创建应用程序需要的客户端数据表和令牌数据表：<pre class=" language-php"><code class=" language-php">php artisan migrate</code></pre><blockquote class="has-icon note"><div class="flag"><svg xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:a="http://ns.adobe.com/AdobeSVGViewerExtensions/3.0/" version="1.1" x="0px" y="0px" width="90px" height="90px" viewBox="0 0 90 90" enable-background="new 0 0 90 90" xml:space="preserve"><path fill="#FFFFFF" d="M45 0C20.1 0 0 20.1 0 45s20.1 45 45 45 45-20.1 45-45S69.9 0 45 0zM45 74.5c-3.6 0-6.5-2.9-6.5-6.5s2.9-6.5 6.5-6.5 6.5 2.9 6.5 6.5S48.6 74.5 45 74.5zM52.1 23.9l-2.5 29.6c0 2.5-2.1 4.6-4.6 4.6 -2.5 0-4.6-2.1-4.6-4.6l-2.5-29.6c-0.1-0.4-0.1-0.7-0.1-1.1 0-4 3.2-7.2 7.2-7.2 4 0 7.2 3.2 7.2 7.2C52.2 23.1 52.2 23.5 52.1 23.9z"></path></svg></div> 如果你不打算使用 Passport 的默认迁移，你应该在<code class=" language-php">AppServiceProvider</code>的<code class=" language-php">register</code>方法中调用<code class=" language-php">Passport :: ignoreMigrations</code>方法。你可以导出这个默认迁移用<code class=" language-php">php artisan vendor:publish --tag=passport-migrations</code>命令。</blockquote>接下来，你需要运行 <code class=" language-php">passport:install</code> 命令来创建生成安全访问令牌时用到的加密密钥，同时，这条命令也会创建「私人访问」客户端和「密码授权」客户端：<pre class=" language-php"><code class=" language-php">php artisan passport:install</code></pre>上面命令执行后，请将 <code class=" language-php">Laravel\Passport\HasApiTokens</code> Trait 添加到 <code class=" language-php">App\User</code> 模型中，这个 Trait 会给你的模型提供一些辅助函数，用于检查已认证用户的令牌和使用作用域：<pre class=" language-php"><code class=" language-php"><?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; }</code></pre>接下来，需要在 <code class=" language-php">AuthServiceProvider</code> 的 <code class=" language-php">boot</code> 方法中调用 <code class=" language-php">Passport::routes</code> 函数。这个函数会注册一些在访问令牌、客户端、私人访问令牌的发放和吊销过程中会用到的必要路由：<pre class=" language-php"><code class=" language-php"><?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(); } }</code></pre>最后，需要将配置文件 <code class=" language-php">config/auth.php</code> 中 <code class=" language-php">api</code> 部分的授权保护项（ <code class=" language-php">driver</code> ）改为 <code class=" language-php">passport</code> 。此调整会让你的应用程序在接收到 API 的授权请求时使用 Passport 的 <code class=" language-php">TokenGuard</code> 来处理：<pre class=" language-php"><code class=" language-php">'guards' => [ 'web' => [ 'driver' => 'session', 'provider' => 'users', ], 'api' => [ 'driver' => 'passport', 'provider' => 'users', ], ],</code></pre><a name="frontend-quickstart"></a><h3>前端快速上手</h3><blockquote class="has-icon note"><div class="flag"><svg xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:a="http://ns.adobe.com/AdobeSVGViewerExtensions/3.0/" version="1.1" x="0px" y="0px" width="90px" height="90px" viewBox="0 0 90 90" enable-background="new 0 0 90 90" xml:space="preserve"><path fill="#FFFFFF" d="M45 0C20.1 0 0 20.1 0 45s20.1 45 45 45 45-20.1 45-45S69.9 0 45 0zM45 74.5c-3.6 0-6.5-2.9-6.5-6.5s2.9-6.5 6.5-6.5 6.5 2.9 6.5 6.5S48.6 74.5 45 74.5zM52.1 23.9l-2.5 29.6c0 2.5-2.1 4.6-4.6 4.6 -2.5 0-4.6-2.1-4.6-4.6l-2.5-29.6c-0.1-0.4-0.1-0.7-0.1-1.1 0-4 3.2-7.2 7.2-7.2 4 0 7.2 3.2 7.2 7.2C52.2 23.1 52.2 23.5 52.1 23.9z"></path></svg></div> 如果想要使用 Passport 的 Vue 组件，那么你必须使用 <a href="https://vuejs.org">Vue</a> Javascript 框架，另外这些组件还用到了 Bootstrap CSS 框架。当然你也可以不使用上面的任何工具，但在实现你自己的前端部分时，Passport 的 Vue 组件仍旧有很高的参考价值。</blockquote>Passport 配备了一些可以让你的用户自行创建客户端和私人访问令牌的 JSON API。所以，你可以自己花费时间来编写一些前端代码来使用这些 API。当然在 Passport 中也已经预制了一些 <a href="https://vuejs.org">Vue</a> 组件，你可以直接使用这些示例代码，也可以基于这些代码实现自己的前端部分。使用 Artisan 命令 <code class=" language-php">vendor:publish</code> 来发布 Passport 的 Vue 组件：<pre class=" language-php"><code class=" language-php">php artisan vendor:publish --tag=passport-components</code></pre>已发布的组件将被放置在 <code class=" language-php">resources/assets/js/components</code> 目录中，可以在 <code class=" language-php">resources/assets/js/app.js</code> 文件中注册这些已发布的组件：<pre class=" language-php"><code class=" language-php">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') );</code></pre>这些组件注册后，你可以直接将这些组件直接放入应用程序的模板中，用于创建客户端和私人访问令牌：<pre class=" language-php"><code class=" language-php"><passport-clients></passport-clients> <passport-authorized-clients></passport-authorized-clients> <passport-personal-access-tokens></passport-personal-access-tokens></code></pre><a name="configuration"></a><h2><a href="#configuration">配置</a></h2><a name="token-lifetimes"></a><h3>令牌的有效期</h3>默认情况下，Passport 发放的访问令牌是永久有效的，不需要刷新。但是如果你想给访问令牌配置一个短一些的有效期，那你就需要用到 <code class=" language-php">tokensExpireIn</code> 和 <code class=" language-php">refreshTokensExpireIn</code> 方法了，上述两个方法同样需要在 <code class=" language-php">AuthServiceProvider</code> 的 <code class=" language-php">boot</code> 方法中调用：<pre class=" language-php"><code class=" language-php">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)); }</code></pre><a name="issuing-access-tokens"></a><h2><a href="#issuing-access-tokens">发放访问令牌</a></h2>熟悉 OAuth2 的开发者一定知道， OAuth2 中必不可少的部分就是授权码。在获取授权码时，接入应用会重定向一个用户到你的服务端，用户可以选择允许或拒绝向这个客户端发放访问令牌。<a name="managing-clients"></a><h3>管理客户端</h3>首先，接入应用如果想要与你应用的 API 进行交互，必须先在你的应用程序中注册一个「客户端」。一般来说，这个注册过程需要开发者提供两部分信息：接入应用名称和用户授权后的跳转链接。<h4>命令 <code class=" language-php">passport:client</code></h4>创建客户端最简单的方式是使用 Artisan 命令 <code class=" language-php">passport:client</code> ，你可以使用此命令创建自己的客户端，用于测试 OAuth2 的功能。在你执行 <code class=" language-php">client</code> 命令时，Passport 会提示输入更多关于你的客户端的信息，最终会提供给你生成的客户端的 ID 和密钥：<pre class=" language-php"><code class=" language-php">php artisan passport:client</code></pre><h4>JSON API</h4>考虑到你的用户们并没有办法使用 <code class=" language-php">client</code> 命令，Passport 同时提供了用户创建客户端的 JSON API 。这样你就不用再花时间编码来实现客户端创建、更新和删除的相关控制器逻辑了。然而，你仍旧需要基于 Passport 的 JSON API 开发一套前端界面，方便你的用户管理他们授权的客户端。下面我们会列出所有用于管理客户端的 API，方便起见，我们使用 <a href="https://vuejs.org">Vue</a> 展示对 API 的 HTTP 请求。<blockquote class="has-icon tip"><div class="flag"><svg xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:a="http://ns.adobe.com/AdobeSVGViewerExtensions/3.0/" version="1.1" x="0px" y="0px" width="56.6px" height="87.5px" viewBox="0 0 56.6 87.5" enable-background="new 0 0 56.6 87.5" xml:space="preserve"><path fill="#FFFFFF" d="M28.7 64.5c-1.4 0-2.5-1.1-2.5-2.5v-5.7 -5V41c0-1.4 1.1-2.5 2.5-2.5s2.5 1.1 2.5 2.5v10.1 5 5.8C31.2 63.4 30.1 64.5 28.7 64.5zM26.4 0.1C11.9 1 0.3 13.1 0 27.7c-0.1 7.9 3 15.2 8.2 20.4 0.5 0.5 0.8 1 1 1.7l3.1 13.1c0.3 1.1 1.3 1.9 2.4 1.9 0.3 0 0.7-0.1 1.1-0.2 1.1-0.5 1.6-1.8 1.4-3l-2-8.4 -0.4-1.8c-0.7-2.9-2-5.7-4-8 -1-1.2-2-2.5-2.7-3.9C5.8 35.3 4.7 30.3 5.4 25 6.7 14.5 15.2 6.3 25.6 5.1c13.9-1.5 25.8 9.4 25.8 23 0 4.1-1.1 7.9-2.9 11.2 -0.8 1.4-1.7 2.7-2.7 3.9 -2 2.3-3.3 5-4 8L41.4 53l-2 8.4c-0.3 1.2 0.3 2.5 1.4 3 0.3 0.2 0.7 0.2 1.1 0.2 1.1 0 2.2-0.8 2.4-1.9l3.1-13.1c0.2-0.6 0.5-1.2 1-1.7 5-5.1 8.2-12.1 8.2-19.8C56.4 12 42.8-1 26.4 0.1zM43.7 69.6c0 0.5-0.1 0.9-0.3 1.3 -0.4 0.8-0.7 1.6-0.9 2.5 -0.7 3-2 8.6-2 8.6 -1.3 3.2-4.4 5.5-7.9 5.5h-4.1H28h-0.5 -3.6c-3.5 0-6.7-2.4-7.9-5.7l-0.1-0.4 -1.8-7.8c-0.4-1.1-0.8-2.1-1.2-3.1 -0.1-0.3-0.2-0.5-0.2-0.9 0.1-1.3 1.3-2.1 2.6-2.1H41C42.4 67.5 43.6 68.2 43.7 69.6zM37.7 72.5H26.9c-4.2 0-7.2 3.9-6.3 7.9 0.6 1.3 1.8 2.1 3.2 2.1h4.1 0.5 0.5 3.6c1.4 0 2.7-0.8 3.2-2.1L37.7 72.5z"></path></svg></div> 如果你不想自己重写整个客户端管理的前端界面，可以根据 <a href="#frontend-quickstart">前端快速上手</a> 在几分钟内组建一套功能完备的前端界面。</blockquote><h4><code class=" language-php">GET /oauth/clients</code></h4>此接口会返回当前认证用户的所有客户端。主要用途是列出当前用户所有客户端，方便用户修改或删除：<pre class=" language-php"><code class=" language-php">this.$http.get('/oauth/clients') .then(response => { console.log(response.data); });</code></pre><h4><code class=" language-php">POST /oauth/clients</code></h4>此接口用户创建新的客户端。它需要两部分数据：客户端的名称、客户端的 <code class=" language-php">redirect</code> 链接。当用户允许或拒绝授权请求后，用户都会被重定向到这个 <code class=" language-php">redirect</code> 链接。当客户端创建完成后，会生成此客户端的 ID 和密钥，客户端可以使用这两个值从你的应用程序请求访问令牌。此接口会返回新建客户端实例的信息：<pre class=" language-php"><code class=" language-php">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... });</code></pre><h4><code class=" language-php">PUT /oauth/clients/{client-id}</code></h4>此接口用于更新客户端信息。它需要两部分数据：客户端的名称和 <code class=" language-php">redirect</code> 链接。当用户允许或拒绝授权请求后，用户都会被重定向到这个 <code class=" language-php">redirect</code> 链接。此接口会返回被更新客户端实例的信息：<pre class=" language-php"><code class=" language-php">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... });</code></pre><h4><code class=" language-php">DELETE /oauth/clients/{client-id}</code></h4>此接口用于删除客户端：<pre class=" language-php"><code class=" language-php">axios.delete('/oauth/clients/' + clientId) .then(response => { // });</code></pre><a name="requesting-tokens"></a><h3>请求令牌</h3><h4>授权时的重定向</h4>客户端创建之后，开发者会使用此客户端的 ID 和密钥向你的应用程序请求一个授权码和访问令牌。首先，接入应用会将用户重定向到你应用程序的 <code class=" language-php">/oauth/authorize</code> 路由上，示例如下：<pre class=" language-php"><code class=" language-php">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); });</code></pre><blockquote class="has-icon tip"><div class="flag"><svg xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:a="http://ns.adobe.com/AdobeSVGViewerExtensions/3.0/" version="1.1" x="0px" y="0px" width="56.6px" height="87.5px" viewBox="0 0 56.6 87.5" enable-background="new 0 0 56.6 87.5" xml:space="preserve"><path fill="#FFFFFF" d="M28.7 64.5c-1.4 0-2.5-1.1-2.5-2.5v-5.7 -5V41c0-1.4 1.1-2.5 2.5-2.5s2.5 1.1 2.5 2.5v10.1 5 5.8C31.2 63.4 30.1 64.5 28.7 64.5zM26.4 0.1C11.9 1 0.3 13.1 0 27.7c-0.1 7.9 3 15.2 8.2 20.4 0.5 0.5 0.8 1 1 1.7l3.1 13.1c0.3 1.1 1.3 1.9 2.4 1.9 0.3 0 0.7-0.1 1.1-0.2 1.1-0.5 1.6-1.8 1.4-3l-2-8.4 -0.4-1.8c-0.7-2.9-2-5.7-4-8 -1-1.2-2-2.5-2.7-3.9C5.8 35.3 4.7 30.3 5.4 25 6.7 14.5 15.2 6.3 25.6 5.1c13.9-1.5 25.8 9.4 25.8 23 0 4.1-1.1 7.9-2.9 11.2 -0.8 1.4-1.7 2.7-2.7 3.9 -2 2.3-3.3 5-4 8L41.4 53l-2 8.4c-0.3 1.2 0.3 2.5 1.4 3 0.3 0.2 0.7 0.2 1.1 0.2 1.1 0 2.2-0.8 2.4-1.9l3.1-13.1c0.2-0.6 0.5-1.2 1-1.7 5-5.1 8.2-12.1 8.2-19.8C56.4 12 42.8-1 26.4 0.1zM43.7 69.6c0 0.5-0.1 0.9-0.3 1.3 -0.4 0.8-0.7 1.6-0.9 2.5 -0.7 3-2 8.6-2 8.6 -1.3 3.2-4.4 5.5-7.9 5.5h-4.1H28h-0.5 -3.6c-3.5 0-6.7-2.4-7.9-5.7l-0.1-0.4 -1.8-7.8c-0.4-1.1-0.8-2.1-1.2-3.1 -0.1-0.3-0.2-0.5-0.2-0.9 0.1-1.3 1.3-2.1 2.6-2.1H41C42.4 67.5 43.6 68.2 43.7 69.6zM37.7 72.5H26.9c-4.2 0-7.2 3.9-6.3 7.9 0.6 1.3 1.8 2.1 3.2 2.1h4.1 0.5 0.5 3.6c1.4 0 2.7-0.8 3.2-2.1L37.7 72.5z"></path></svg></div> 注意，路由 <code class=" language-php">/oauth/authorize</code> 已经在 <code class=" language-php">Passport::routes</code> 方法中定义，所以无需再次定义。</blockquote><h4>确认授权请求</h4>接收到授权请求时，Passport 会显示默认的授权确认页面，用户可以允许或拒绝本次授权请求。用户确认后会被重定向回接入应用程序请求中指定的 <code class=" language-php">redirect_uri</code> 链接。<code class=" language-php">redirect_uri</code> 必须和客户端创建时提供的 <code class=" language-php">redirect</code> 完全一致。如果你想自定义授权确认页面，可以使用 Artisan 命令 <code class=" language-php">vendor:publish</code> 发布 Passport 的视图文件。发布后的视图文件存放路径为 <code class=" language-php">resources/views/vendor/passport</code> ：<pre class=" language-php"><code class=" language-php">php artisan vendor:publish --tag=passport-views</code></pre><h4>将授权码转换为访问令牌</h4>用户允许授权请求后，用户将会被重定向会接入应用程序，然后接入应用将通过 <code class=" language-php">POST</code> 请求向你的应用程序申请访问令牌，此次请求需要携带用户允许授权时产生的授权码。在下面的例子中，我们使用 Guzzle HTTP 库来实现这次 <code class=" language-php">POST</code> 请求：<pre class=" language-php"><code class=" language-php">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); });</code></pre>接口 <code class=" language-php">/oauth/token</code> 的 JSON 相应中会包含 <code class=" language-php">access_token</code> 、<code class=" language-php">refresh_token</code> 和 <code class=" language-php">expires_in</code> 属性。<code class=" language-php">expires_in</code> 的值即当前访问令牌的有效期（单位：秒）。<blockquote class="has-icon tip"><div class="flag"><svg xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:a="http://ns.adobe.com/AdobeSVGViewerExtensions/3.0/" version="1.1" x="0px" y="0px" width="56.6px" height="87.5px" viewBox="0 0 56.6 87.5" enable-background="new 0 0 56.6 87.5" xml:space="preserve"><path fill="#FFFFFF" d="M28.7 64.5c-1.4 0-2.5-1.1-2.5-2.5v-5.7 -5V41c0-1.4 1.1-2.5 2.5-2.5s2.5 1.1 2.5 2.5v10.1 5 5.8C31.2 63.4 30.1 64.5 28.7 64.5zM26.4 0.1C11.9 1 0.3 13.1 0 27.7c-0.1 7.9 3 15.2 8.2 20.4 0.5 0.5 0.8 1 1 1.7l3.1 13.1c0.3 1.1 1.3 1.9 2.4 1.9 0.3 0 0.7-0.1 1.1-0.2 1.1-0.5 1.6-1.8 1.4-3l-2-8.4 -0.4-1.8c-0.7-2.9-2-5.7-4-8 -1-1.2-2-2.5-2.7-3.9C5.8 35.3 4.7 30.3 5.4 25 6.7 14.5 15.2 6.3 25.6 5.1c13.9-1.5 25.8 9.4 25.8 23 0 4.1-1.1 7.9-2.9 11.2 -0.8 1.4-1.7 2.7-2.7 3.9 -2 2.3-3.3 5-4 8L41.4 53l-2 8.4c-0.3 1.2 0.3 2.5 1.4 3 0.3 0.2 0.7 0.2 1.1 0.2 1.1 0 2.2-0.8 2.4-1.9l3.1-13.1c0.2-0.6 0.5-1.2 1-1.7 5-5.1 8.2-12.1 8.2-19.8C56.4 12 42.8-1 26.4 0.1zM43.7 69.6c0 0.5-0.1 0.9-0.3 1.3 -0.4 0.8-0.7 1.6-0.9 2.5 -0.7 3-2 8.6-2 8.6 -1.3 3.2-4.4 5.5-7.9 5.5h-4.1H28h-0.5 -3.6c-3.5 0-6.7-2.4-7.9-5.7l-0.1-0.4 -1.8-7.8c-0.4-1.1-0.8-2.1-1.2-3.1 -0.1-0.3-0.2-0.5-0.2-0.9 0.1-1.3 1.3-2.1 2.6-2.1H41C42.4 67.5 43.6 68.2 43.7 69.6zM37.7 72.5H26.9c-4.2 0-7.2 3.9-6.3 7.9 0.6 1.3 1.8 2.1 3.2 2.1h4.1 0.5 0.5 3.6c1.4 0 2.7-0.8 3.2-2.1L37.7 72.5z"></path></svg></div> 如上 <code class=" language-php">/oauth/authorize</code> 路由，<code class=" language-php">/oauth/token</code> 已经在 <code class=" language-php">Passport::routes</code> 方法中定义，所以无需再次定义。</blockquote><a name="refreshing-tokens"></a><h3>刷新令牌</h3>如果你的应用程序发放了短期访问令牌，用户需要刷新访问令牌时，需要提供与访问令牌同时发放的刷新令牌。在下面的例子中，我们使用 Guzzle HTTP 库来刷新令牌：<pre class=" language-php"><code class=" language-php">$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);</code></pre>接口 <code class=" language-php">/oauth/token</code> 会返回一个 JSON 响应，会包含 <code class=" language-php">access_token</code> 、<code class=" language-php">refresh_token</code> 和 <code class=" language-php">expires_in</code> 属性。<code class=" language-php">expires_in</code> 属性值即当前访问令牌的有效时间（单位：秒）。<a name="password-grant-tokens"></a><h2><a href="#password-grant-tokens">密码授权令牌</a></h2>OAuth2 密码授权机制可以让自有应用基于邮箱地址（用户名）和密码获取访问令牌，自有应用比如你的手机客户端。这样就允许自由应用无需跳转步骤即可通过整个 OAuth2 的授权过程。<a name="creating-a-password-grant-client"></a><h3>创建密码授权客户端</h3>如果想要通过密码授权机制来发布令牌，首先你需要创建一个密码授权客户端。你可以使用带有 <code class=" language-php">--password</code> 参数的 <code class=" language-php">passport:client</code> 命令。如果你已经运行了 <code class=" language-php">passport:install</code> 命令，那无需再单独运行此命令：<pre class=" language-php"><code class=" language-php">php artisan passport:client --password</code></pre><a name="requesting-password-grant-tokens"></a><h3>请求密码授权令牌</h3>当你创建密码授权客户端后，你可以向 <code class=" language-php">/oauth/token</code> 接口发起 <code class=" language-php">POST</code> 请求来获取访问令牌，请求时需要带有用户的邮箱地址和密码信息。注意，该接口已经在 <code class=" language-php">Passport::routes</code> 方法中定义，所以无需再次手动定义。请求成功后，服务端返回的 JSON 响应数据中会带有 <code class=" language-php">access_token</code> 和 <code class=" language-php">refresh_token</code> 属性：<pre class=" language-php"><code class=" language-php">$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);</code></pre><blockquote class="has-icon tip"><div class="flag"><svg xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:a="http://ns.adobe.com/AdobeSVGViewerExtensions/3.0/" version="1.1" x="0px" y="0px" width="56.6px" height="87.5px" viewBox="0 0 56.6 87.5" enable-background="new 0 0 56.6 87.5" xml:space="preserve"><path fill="#FFFFFF" d="M28.7 64.5c-1.4 0-2.5-1.1-2.5-2.5v-5.7 -5V41c0-1.4 1.1-2.5 2.5-2.5s2.5 1.1 2.5 2.5v10.1 5 5.8C31.2 63.4 30.1 64.5 28.7 64.5zM26.4 0.1C11.9 1 0.3 13.1 0 27.7c-0.1 7.9 3 15.2 8.2 20.4 0.5 0.5 0.8 1 1 1.7l3.1 13.1c0.3 1.1 1.3 1.9 2.4 1.9 0.3 0 0.7-0.1 1.1-0.2 1.1-0.5 1.6-1.8 1.4-3l-2-8.4 -0.4-1.8c-0.7-2.9-2-5.7-4-8 -1-1.2-2-2.5-2.7-3.9C5.8 35.3 4.7 30.3 5.4 25 6.7 14.5 15.2 6.3 25.6 5.1c13.9-1.5 25.8 9.4 25.8 23 0 4.1-1.1 7.9-2.9 11.2 -0.8 1.4-1.7 2.7-2.7 3.9 -2 2.3-3.3 5-4 8L41.4 53l-2 8.4c-0.3 1.2 0.3 2.5 1.4 3 0.3 0.2 0.7 0.2 1.1 0.2 1.1 0 2.2-0.8 2.4-1.9l3.1-13.1c0.2-0.6 0.5-1.2 1-1.7 5-5.1 8.2-12.1 8.2-19.8C56.4 12 42.8-1 26.4 0.1zM43.7 69.6c0 0.5-0.1 0.9-0.3 1.3 -0.4 0.8-0.7 1.6-0.9 2.5 -0.7 3-2 8.6-2 8.6 -1.3 3.2-4.4 5.5-7.9 5.5h-4.1H28h-0.5 -3.6c-3.5 0-6.7-2.4-7.9-5.7l-0.1-0.4 -1.8-7.8c-0.4-1.1-0.8-2.1-1.2-3.1 -0.1-0.3-0.2-0.5-0.2-0.9 0.1-1.3 1.3-2.1 2.6-2.1H41C42.4 67.5 43.6 68.2 43.7 69.6zM37.7 72.5H26.9c-4.2 0-7.2 3.9-6.3 7.9 0.6 1.3 1.8 2.1 3.2 2.1h4.1 0.5 0.5 3.6c1.4 0 2.7-0.8 3.2-2.1L37.7 72.5z"></path></svg></div> 注意：访问令牌默认是永久有效的。但是如果需要你可以 <a href="#configuration">配置你应用程序的访问令牌有效时间</a>。</blockquote><a name="requesting-all-scopes"></a><h3>请求所有作用域</h3>使用密码授权机制时，你可以通过请求作用域 <code class=" language-php">*</code> 让你的令牌获取应用程序中定义的所有作用域。在处理使用此令牌发起的请求时，<code class=" language-php">can</code> 函数会始终返回 <code class=" language-php">true</code> ，这种作用域的授权最好只应用在使用 <code class=" language-php">password</code> 授权时发放的令牌中：<pre class=" language-php"><code class=" language-php">$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' => '*', ], ]);</code></pre><a name="implicit-grant-tokens"></a><h2><a href="#implicit-grant-tokens">简化授权令牌</a></h2>简化授权和通过授权码授权相似; 区别是, 不需要通过授权码去获取令牌而是把令牌直接返回客户端. 主要用在无法安全存储证书场景中，这种授权在 JavaScript 和移动应用是最常用的. 开启授权, 在 <code class=" language-php">AuthServiceProvider</code> 中调用 <code class=" language-php">enableImplicitGrant</code> 方法:<pre class=" language-php"><code class=" language-php">/** * Register any authentication / authorization services. * * @return void */ public function boot() { $this->registerPolicies(); Passport::routes(); Passport::enableImplicitGrant(); }</code></pre>调用上面方法开启授权后, 开发者可以通过自己的应用把 client ID 当做参数去请求一个令牌. 在你的应用程序 <code class=" language-php">/oauth/authorize</code> 的接口中应该有一个重定向请求像下面这样:<pre class=" language-php"><code class=" language-php">Route::get('/redirect', function () { $query = http_build_query([ 'client_id' => 'client-id', 'redirect_uri' => 'http://example.com/callback', 'response_type' => 'token', 'scope' => '', ]); return redirect('http://your-app.com/oauth/authorize?'.$query); });</code></pre><blockquote class="has-icon tip"><div class="flag"><svg xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:a="http://ns.adobe.com/AdobeSVGViewerExtensions/3.0/" version="1.1" x="0px" y="0px" width="56.6px" height="87.5px" viewBox="0 0 56.6 87.5" enable-background="new 0 0 56.6 87.5" xml:space="preserve"><path fill="#FFFFFF" d="M28.7 64.5c-1.4 0-2.5-1.1-2.5-2.5v-5.7 -5V41c0-1.4 1.1-2.5 2.5-2.5s2.5 1.1 2.5 2.5v10.1 5 5.8C31.2 63.4 30.1 64.5 28.7 64.5zM26.4 0.1C11.9 1 0.3 13.1 0 27.7c-0.1 7.9 3 15.2 8.2 20.4 0.5 0.5 0.8 1 1 1.7l3.1 13.1c0.3 1.1 1.3 1.9 2.4 1.9 0.3 0 0.7-0.1 1.1-0.2 1.1-0.5 1.6-1.8 1.4-3l-2-8.4 -0.4-1.8c-0.7-2.9-2-5.7-4-8 -1-1.2-2-2.5-2.7-3.9C5.8 35.3 4.7 30.3 5.4 25 6.7 14.5 15.2 6.3 25.6 5.1c13.9-1.5 25.8 9.4 25.8 23 0 4.1-1.1 7.9-2.9 11.2 -0.8 1.4-1.7 2.7-2.7 3.9 -2 2.3-3.3 5-4 8L41.4 53l-2 8.4c-0.3 1.2 0.3 2.5 1.4 3 0.3 0.2 0.7 0.2 1.1 0.2 1.1 0 2.2-0.8 2.4-1.9l3.1-13.1c0.2-0.6 0.5-1.2 1-1.7 5-5.1 8.2-12.1 8.2-19.8C56.4 12 42.8-1 26.4 0.1zM43.7 69.6c0 0.5-0.1 0.9-0.3 1.3 -0.4 0.8-0.7 1.6-0.9 2.5 -0.7 3-2 8.6-2 8.6 -1.3 3.2-4.4 5.5-7.9 5.5h-4.1H28h-0.5 -3.6c-3.5 0-6.7-2.4-7.9-5.7l-0.1-0.4 -1.8-7.8c-0.4-1.1-0.8-2.1-1.2-3.1 -0.1-0.3-0.2-0.5-0.2-0.9 0.1-1.3 1.3-2.1 2.6-2.1H41C42.4 67.5 43.6 68.2 43.7 69.6zM37.7 72.5H26.9c-4.2 0-7.2 3.9-6.3 7.9 0.6 1.3 1.8 2.1 3.2 2.1h4.1 0.5 0.5 3.6c1.4 0 2.7-0.8 3.2-2.1L37.7 72.5z"></path></svg></div> 记住, 这个 <code class=" language-php">/oauth/authorize</code> 接口已经定义在 <code class=" language-php">Passport::routes</code> 中. 所以无需再次手动定义.</blockquote><a name="client-credentials-grant-tokens"></a><h2><a href="#client-credentials-grant-tokens">客户端证书授权令牌</a></h2>客户端证书授权适用于机器对机器认证，例如，你可以在通过API执行脚本任务中使用此授权。要获取令牌，向 <code class=" language-php">oauth/token</code> 接口发出请求:<pre class=" language-php"><code class=" language-php">$guzzle = new GuzzleHttp\Client; $response = $guzzle->post('http://your-app.com/oauth/token', [ 'form_params' => [ 'grant_type' => 'client_credentials', 'client_id' => 'client-id', 'client_secret' => 'client-secret', 'scope' => 'your-scope', ], ]); echo json_decode((string) $response->getBody(), true);</code></pre><a name="personal-access-tokens"></a><h2><a href="#personal-access-tokens">私人访问令牌</a></h2>有些时候你的用户可能想发布一个访问令牌自己使用，又不想经历通常的授权跳转流程，这时候如果能让用户在你的应用程序中自行发放访问令牌，也是一个不错的解决方案。<blockquote class="has-icon note"><div class="flag"><svg xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:a="http://ns.adobe.com/AdobeSVGViewerExtensions/3.0/" version="1.1" x="0px" y="0px" width="90px" height="90px" viewBox="0 0 90 90" enable-background="new 0 0 90 90" xml:space="preserve"><path fill="#FFFFFF" d="M45 0C20.1 0 0 20.1 0 45s20.1 45 45 45 45-20.1 45-45S69.9 0 45 0zM45 74.5c-3.6 0-6.5-2.9-6.5-6.5s2.9-6.5 6.5-6.5 6.5 2.9 6.5 6.5S48.6 74.5 45 74.5zM52.1 23.9l-2.5 29.6c0 2.5-2.1 4.6-4.6 4.6 -2.5 0-4.6-2.1-4.6-4.6l-2.5-29.6c-0.1-0.4-0.1-0.7-0.1-1.1 0-4 3.2-7.2 7.2-7.2 4 0 7.2 3.2 7.2 7.2C52.2 23.1 52.2 23.5 52.1 23.9z"></path></svg></div> 私人访问令牌总是永久有效的，<code class=" language-php">tokensExpireIn</code> 和 <code class=" language-php">refreshTokensExpireIn</code> 方法不会影响它的有效期。</blockquote><a name="creating-a-personal-access-client"></a><h3>创建私人访问客户端</h3>发布私人访问令牌之前，你需要先创建对应的客户端。你可以使用带 <code class=" language-php">--personal</code> 参数的 <code class=" language-php">passport:client</code> 命令来创建，如果你已经运行了 <code class=" language-php">passport:install</code> 命令，那无需再运行此命令：<pre class=" language-php"><code class=" language-php">php artisan passport:client --personal</code></pre><a name="managing-personal-access-tokens"></a><h3>管理私人访问令牌</h3>创建私人访问客户端后，你可以使用 <code class=" language-php">User</code> 模型实例上的 <code class=" language-php">createToken</code> 方法来为给定用户发布令牌， <code class=" language-php">createToken</code> 方法的第一个参数为令牌名称，第二个参数（可选）是 <a href="#token-scopes">作用域</a> 列表：<pre class=" language-php"><code class=" language-php">$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;</code></pre><h4>JSON API</h4>Passport 中也有用来管理私人访问令牌的 JSON API，你可以基于这些 API 开发一套前端操作界面供给用户管理自己的私人访问令牌。下面我们会列出所有管理私人访问令牌的 API。方便起见，我们使用 <a href="https://vuejs.org">Vue</a> 展示对 API 的 HTTP 请求。<blockquote class="has-icon tip"><div class="flag"><svg xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:a="http://ns.adobe.com/AdobeSVGViewerExtensions/3.0/" version="1.1" x="0px" y="0px" width="56.6px" height="87.5px" viewBox="0 0 56.6 87.5" enable-background="new 0 0 56.6 87.5" xml:space="preserve"><path fill="#FFFFFF" d="M28.7 64.5c-1.4 0-2.5-1.1-2.5-2.5v-5.7 -5V41c0-1.4 1.1-2.5 2.5-2.5s2.5 1.1 2.5 2.5v10.1 5 5.8C31.2 63.4 30.1 64.5 28.7 64.5zM26.4 0.1C11.9 1 0.3 13.1 0 27.7c-0.1 7.9 3 15.2 8.2 20.4 0.5 0.5 0.8 1 1 1.7l3.1 13.1c0.3 1.1 1.3 1.9 2.4 1.9 0.3 0 0.7-0.1 1.1-0.2 1.1-0.5 1.6-1.8 1.4-3l-2-8.4 -0.4-1.8c-0.7-2.9-2-5.7-4-8 -1-1.2-2-2.5-2.7-3.9C5.8 35.3 4.7 30.3 5.4 25 6.7 14.5 15.2 6.3 25.6 5.1c13.9-1.5 25.8 9.4 25.8 23 0 4.1-1.1 7.9-2.9 11.2 -0.8 1.4-1.7 2.7-2.7 3.9 -2 2.3-3.3 5-4 8L41.4 53l-2 8.4c-0.3 1.2 0.3 2.5 1.4 3 0.3 0.2 0.7 0.2 1.1 0.2 1.1 0 2.2-0.8 2.4-1.9l3.1-13.1c0.2-0.6 0.5-1.2 1-1.7 5-5.1 8.2-12.1 8.2-19.8C56.4 12 42.8-1 26.4 0.1zM43.7 69.6c0 0.5-0.1 0.9-0.3 1.3 -0.4 0.8-0.7 1.6-0.9 2.5 -0.7 3-2 8.6-2 8.6 -1.3 3.2-4.4 5.5-7.9 5.5h-4.1H28h-0.5 -3.6c-3.5 0-6.7-2.4-7.9-5.7l-0.1-0.4 -1.8-7.8c-0.4-1.1-0.8-2.1-1.2-3.1 -0.1-0.3-0.2-0.5-0.2-0.9 0.1-1.3 1.3-2.1 2.6-2.1H41C42.4 67.5 43.6 68.2 43.7 69.6zM37.7 72.5H26.9c-4.2 0-7.2 3.9-6.3 7.9 0.6 1.3 1.8 2.1 3.2 2.1h4.1 0.5 0.5 3.6c1.4 0 2.7-0.8 3.2-2.1L37.7 72.5z"></path></svg></div> 如果你不想自己重写整个私人访问令牌管理的前端界面，可以根据 <a href="#frontend-quickstart">前端快速上手</a> 在几分钟内组建一套功能完备的前端界面。</blockquote><h4><code class=" language-php">GET /oauth/scopes</code></h4>此接口会返回应用程序中定义的所有 <a href="#scopes">作用域</a> 。你可以使用此接口将所有的作用域展示给用户，方便他们授权给需要的私人访问令牌：<pre class=" language-php"><code class=" language-php">this.$http.get('/oauth/scopes') .then(response => { console.log(response.data); });</code></pre><h4><code class=" language-php">GET /oauth/personal-access-tokens</code></h4>此接口返回当前授权用户创建的所有私人访问令牌。主要用途是列出当前用户所有客户端，方便用户修改或删除：<pre class=" language-php"><code class=" language-php">this.$http.get('/oauth/personal-access-tokens') .then(response => { console.log(response.data); });</code></pre><h4><code class=" language-php">POST /oauth/personal-access-tokens</code></h4>此接口用来创建私人访问令牌。需要提供两部分数据：令牌的名称（ <code class=" language-php">name</code> ）作用域（ <code class=" language-php">scopes</code> ）：<pre class=" language-php"><code class=" language-php">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... });</code></pre><h4><code class=" language-php">DELETE /oauth/personal-access-tokens/{token-id}</code></h4>此接口用于删除私人访问令牌：<pre class=" language-php"><code class=" language-php">this.$http.delete('/oauth/personal-access-tokens/' + tokenId);</code></pre><a name="protecting-routes"></a><h2><a href="#protecting-routes">路由保护</a></h2><a name="via-middleware"></a><h3>通过中间件</h3>Passport 包含一个 <a href="/docs/5.4/authentication#adding-custom-guards">验证保护机制</a> 可以验证请求中的的访问令牌。前面将 <code class=" language-php">api</code> 中的保护机制改为为 <code class=" language-php">passport</code> 后，你只要给需要验证访问令牌的路由添加 <code class=" language-php">auth:api</code> 中间件，该机制将发挥作用：<pre class=" language-php"><code class=" language-php">Route::get('/user', function () { // })->middleware('auth:api');</code></pre><a name="passing-the-access-token"></a><h3>传递访问令牌</h3>接入应用在调用 Passport 保护下的路由时，需要将访问令牌作为 <code class=" language-php">Bearer</code> 令牌放在请求头 <code class=" language-php">Authorization</code> 中。在下面的例子中，我们使用 Guzzle HTTP 库来实现这次 <code class=" language-php">POST</code> 请求：<pre class=" language-php"><code class=" language-php">$response = $client->request('GET', '/api/user', [ 'headers' => [ 'Accept' => 'application/json', 'Authorization' => 'Bearer '.$accessToken, ], ]);</code></pre><a name="token-scopes"></a><h2><a href="#token-scopes">令牌作用域</a></h2><a name="defining-scopes"></a><h3>定义作用域</h3>当 API 客户端接入特定用户时，可以通过作用域来限定其访问权限。例如在你编写的电子商务应用中，一些接入应用可以获取订单的发货状态而不能创建订单。换言之，作用域能够让你的用户限制第三方应用的行为，从而保障自身的利益。你可以使用 <code class=" language-php">Passport::tokensCan</code> 方法来定义 API 的作用域，定义代码需要放置在 <code class=" language-php">AuthServiceProvider</code> 的 <code class=" language-php">boot</code> 方法中。<code class=" language-php">tokensCan</code> 方法接受一个包含作用域名称、描述的数组作为参数。作用域描述将会在授权确认页中直接展示给用户，你可以将其定义为任何你需要的内容：<pre class=" language-php"><code class=" language-php">use Laravel\Passport\Passport; Passport::tokensCan([ 'place-orders' => 'Place orders', 'check-status' => 'Check order status', ]);</code></pre><a name="assigning-scopes-to-tokens"></a><h3>给令牌分派作用域</h3><h4>授权码机制</h4>使用授权码机制申请访问令牌时，接入应用可以通过 <code class=" language-php">scope</code> 字符串参数指定他们需要的作用域。<code class=" language-php">scope</code> 包含多个作用域名称时，名称之间使用空格分隔：<pre class=" language-php"><code class=" language-php">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); });</code></pre><h4>私人访问令牌</h4>使用 <code class=" language-php">User</code> 模型的 <code class=" language-php">createToken</code> 方法发放访问令牌时，你可以将需要的作用域数组作为第二个参数传给此方法：<pre class=" language-php"><code class=" language-php">$token = $user->createToken('My Token', ['place-orders'])->accessToken;</code></pre><a name="checking-scopes"></a><h3>检查作用域</h3>Passport 包含两个检查作用域的中间件，通过访问令牌请求时将会使用这两个中间件来检查是否授予了特定作用域。使用之前，需要将下面的中间件添加到 <code class=" language-php">app/Http/Kernel.php</code> 文件的 <code class=" language-php">$routeMiddleware</code> 属性中：<pre class=" language-php"><code class=" language-php">'scopes' => \Laravel\Passport\Http\Middleware\CheckScopes::class, 'scope' => \Laravel\Passport\Http\Middleware\CheckForAnyScope::class,</code></pre><h4>检查所有作用域</h4>路由可以使用 <code class=" language-php">scopes</code> 中间件来检查当前请求是否拥有指定的 所有 作用域：<pre class=" language-php"><code class=" language-php">Route::get('/orders', function () { // Access token has both "check-status" and "place-orders" scopes... })->middleware('scopes:check-status,place-orders');</code></pre><h4>检查任意作用域</h4>路由可以使用 <code class=" language-php">scope</code> 中间件来检查当前请求是否拥有指定的 任意 作用域：<pre class=" language-php"><code class=" language-php">Route::get('/orders', function () { // Access token has either "check-status" or "place-orders" scope... })->middleware('scope:check-status,place-orders');</code></pre><h4>检查特定令牌实例的作用域</h4>接入应用使用访问令牌通过你应用程序的验证后，你仍然可以使用当前授权 <code class=" language-php">User</code> 实例上的 <code class=" language-php">tokenCan</code> 方法来验证此令牌是否拥有指定的作用域：<pre class=" language-php"><code class=" language-php">use Illuminate\Http\Request; Route::get('/orders', function (Request $request) { if ($request->user()->tokenCan('place-orders')) { // } });</code></pre><a name="consuming-your-api-with-javascript"></a><h2><a href="#consuming-your-api-with-javascript">使用 JavaScript 接入 API</a></h2>在构建 API 时，如果能通过 JavaScript 应用接入自己的 API 将会给开发过程带来极大的便利。这样你可以与所用人一样使用你自己的应用程序的 API，同样的 API 可以被你自己的 web 应用、移动应用、第三方应用以及你发布到各个包管理平台的 SDK 共同使用。通常，在你通过 JavaScript 接入你的 API 时，每次请求你的应用程序时都需要手动传递访问令牌，然而，Passport 其中一个中间件可以帮你做这件事，你需要做的仅仅是将 <code class=" language-php">CreateFreshApiToken</code> 中间件添加到你的 <code class=" language-php">web</code> 中间件组中：<pre class=" language-php"><code class=" language-php">'web' => [ // Other middleware... \Laravel\Passport\Http\Middleware\CreateFreshApiToken::class, ],</code></pre>Passport 的这个中间件将会在你所有的对外请求中添加一个 <code class=" language-php">laravel_token</code> cookie ，该 cookie 将包含一个加密后的 <a href="https://jwt.io/">JWT</a> ，Passport 可以根据此数据判断你 JavaScript 应用的授权状态。至此，你可以无需传递访问令牌直接请求应用程序的 API 了：<pre class=" language-php"><code class=" language-php">axios.get('/user') .then(response => { console.log(response.data); });</code></pre>当使用上面方法授权时，Axios 会自动带上 <code class=" language-php">X-CSRF-TOKEN</code> 请求头传递。另外，默认的 Laravel JavaScript 也会带上 <code class=" language-php">X-Requested-With</code> 请求头:<pre class=" language-php"><code class=" language-php">window.axios.defaults.headers.common = { 'X-Requested-With': 'XMLHttpRequest', };</code></pre><blockquote class="has-icon note"><div class="flag"><svg xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:a="http://ns.adobe.com/AdobeSVGViewerExtensions/3.0/" version="1.1" x="0px" y="0px" width="90px" height="90px" viewBox="0 0 90 90" enable-background="new 0 0 90 90" xml:space="preserve"><path fill="#FFFFFF" d="M45 0C20.1 0 0 20.1 0 45s20.1 45 45 45 45-20.1 45-45S69.9 0 45 0zM45 74.5c-3.6 0-6.5-2.9-6.5-6.5s2.9-6.5 6.5-6.5 6.5 2.9 6.5 6.5S48.6 74.5 45 74.5zM52.1 23.9l-2.5 29.6c0 2.5-2.1 4.6-4.6 4.6 -2.5 0-4.6-2.1-4.6-4.6l-2.5-29.6c-0.1-0.4-0.1-0.7-0.1-1.1 0-4 3.2-7.2 7.2-7.2 4 0 7.2 3.2 7.2 7.2C52.2 23.1 52.2 23.5 52.1 23.9z"></path></svg></div> 如果你用了其他 JavaScript 框架，需要确保每次对外请求都会带有 <code class=" language-php">X-CSRF-TOKEN</code> 和 <code class=" language-php">X-Requested-With</code> 请求头。</blockquote><a name="events"></a><h2><a href="#events">事件</a></h2>Passport 在访问令牌和刷新令牌时触发事件。你可以通过触发这些事件来修改或删除数据库中的其他访问令牌。你可以在应用程序的 <code class=" language-php">EventServiceProvider</code> 中为这些事件附加监听器:<pre class=" language-php"><code class=" language-php">/** * The event listener mappings for the application. * * @var array */ protected $listen = [ 'Laravel\Passport\Events\AccessTokenCreated' => [ 'App\Listeners\RevokeOldTokens', ], 'Laravel\Passport\Events\RefreshTokenCreated' => [ 'App\Listeners\PruneOldTokens', ], ];</code></pre><a name="testing"></a><h2><a href="#testing">测试</a></h2>Passport 的 <code class=" language-php">actingAs</code> 方法可以用于指定当前认证的用户及其授权范围。 <code class=" language-php">actingAs</code> 方法第一个参数是一个对象，第二个参数是数组表示申请的授权范围:<pre class=" language-php"><code class=" language-php">public function testServerCreation() { Passport::actingAs( factory(User::class)->create(), ['create-servers'] ); $response = $this->post('/api/create-server'); $response->assertStatus(200); }</code></pre><h2>译者署名</h2><table><thead><tr><th>用户名</th><th>头像</th><th>职能</th><th>签名</th></tr></thead><tbody><tr><td><a href="https://github.com/KevinDiamen">@KevinDiamen</a></td><td><img class="avatar-66 rm-style" src="https://dn-phphub.qbox.me/uploads/avatars/10242_1487138520.jpg?imageView2/1/w/100/h/100"></td><td>翻译</td><td>部分关键字翻译参考 <a href="https://github.com/zhwei">@zhwei</a></td></tr></tbody></table></article>