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>