justmd5 4年前

修改理由:

官方已修改Airlock

详细描述:

Airlock 改名为 Sanctum

相关信息:


此投稿已在 4年前 合并。

标题修改:

- Airlock 轻量级 API 认证
+ Sanctum 轻量级 API 认证

内容修改:

红色背景 为原始内容

绿色背景 为新增或者修改的内容

OldNewDifferences
1 # Laravel Airlock
 1# Laravel Sanctum
22
33- [介绍](#introduction)
44   - [工作原理](#how-it-works)
 
2222<a name="introduction"></a>
2323## 介绍
2424
25 Laravel Airlock 为 SPA (单页面应用程序)、移动应用程序和简单的、基于令牌的 API 提供轻量级身份验证系统。Airlock 允许应用程序的每个用户为他们的帐户生成多个 API 令牌。这些令牌可能被授予指定允许令牌执行哪些操作的能力/范围。
 25Laravel Sanctum 为 SPA (单页面应用程序)、移动应用程序和简单的、基于令牌的 API 提供轻量级身份验证系统。Sanctum 允许应用程序的每个用户为他们的帐户生成多个 API 令牌。这些令牌可能被授予指定允许令牌执行哪些操作的能力/范围。
2626
2727<a name="how-it-works"></a>
2828### 工作原理
2929
3030#### API 令牌
3131
32 Laravel Airlock 是为了解决两个独立问题而生。 首先,它是一个简单的包,用于向用户发出 API 令牌,而不涉及 OAuth。这个功能的灵感来自 GitHub 的「访问令牌」。例如,假设应用程序的「帐户设置」有一个界面,用户可以在其中为其帐户生成 API 令牌。您可以使用 Airlock 来生成和管理这些令牌。这些令牌通常有很长的过期时间(以年计),当然用户是可以随时手动撤销它们的。
33 
34 Laravel Airlock 的这个特性是通过将用户 API 令牌存储在单个数据库表中,并通过包含了有效 API 令牌的`Authorization`标头对传入请求进行身份验证而实现的。
 32Laravel Sanctum 是为了解决两个独立问题而生。 首先,它是一个简单的包,用于向用户发出 API 令牌,而不涉及 OAuth。这个功能的灵感来自 GitHub 的「访问令牌」。例如,假设应用程序的「帐户设置」有一个界面,用户可以在其中为其帐户生成 API 令牌。您可以使用 Sanctum 来生成和管理这些令牌。这些令牌通常有很长的过期时间(以年计),当然用户是可以随时手动撤销它们的。
 33
 34Laravel Sanctum 的这个特性是通过将用户 API 令牌存储在单个数据库表中,并通过包含了有效 API 令牌的`Authorization`标头对传入请求进行身份验证而实现的。
3535
3636
3737
3838
3939#### SPA 身份验证
4040
41 >「提示」Airlock 适用于 API 令牌认证或 SPA 身份认证,使用 Airlock 并不意味着你需要用到它所提供全部特性。
42 
43 Airlock 提供了一种简单的方法来认证需要与基于 Laravel 的 API 进行通信的单页应用程序 (SPAs)。这些 SPA 可能与 Laravel 应用程序存在于同一仓库中,也可能是一个完全独立的仓库,例如使用 Vue CLI 创建的单页应用程序
44 
45 对于此功能,Airlock 不使用任何类型的令牌。相反,Airlock 使用 Laravel 内置的基于 cookie 的会话身份验证服务。这提供了CSRF保护,会话身份验证以及防止因 XSS 攻击而泄漏身份验证凭据。仅当传入请求来自您自己的 SPA 前端时,Airlock 才会尝试使用 Cookie 进行身份验证。
 41>「提示」Sanctum 适用于 API 令牌认证或 SPA 身份认证,使用 Sanctum 并不意味着你需要用到它所提供全部特性。
 42
 43Sanctum 提供了一种简单的方法来认证需要与基于 Laravel 的 API 进行通信的单页应用程序 (SPAs)。这些 SPA 可能与 Laravel 应用程序存在于同一仓库中,也可能是一个完全独立的仓库,例如使用 Vue CLI 创建的单页应用程序
 44
 45对于此功能,Sanctum 不使用任何类型的令牌。相反,Sanctum 使用 Laravel 内置的基于 cookie 的会话身份验证服务。这提供了CSRF保护,会话身份验证以及防止因 XSS 攻击而泄漏身份验证凭据。仅当传入请求来自您自己的 SPA 前端时,Sanctum 才会尝试使用 Cookie 进行身份验证。
4646
4747<a name="installation"></a>
4848## 安装过程
4949
50 你可以通过 Composer 安装 Laravel Airlock
51 
52    composer require laravel/airlock
53 
54 接下来,你需要使用 `vendor:publish` Artisan 命令发布 Airlock 的配置和迁移文件。Airlock 的配置文件将会保存在 `config` 文件夹中
55 
56    php artisan vendor:publish --provider="Laravel\Airlock\AirlockServiceProvider"
57 
58 
59 最后,你需要执行数据库迁移文件。Airlock 将创建一个数据库表用于存储 API 令牌:
 50你可以通过 Composer 安装 Laravel Sanctum
 51
 52   composer require laravel/Sanctum
 53
 54接下来,你需要使用 `vendor:publish` Artisan 命令发布 Sanctum 的配置和迁移文件。Sanctum 的配置文件将会保存在 `config` 文件夹中
 55
 56   php artisan vendor:publish --provider="Laravel\Sanctum\SanctumServiceProvider"
 57
 58
 59最后,你需要执行数据库迁移文件。Sanctum 将创建一个数据库表用于存储 API 令牌:
6060
6161   php artisan migrate
6262
63 假如你需要使用 Airlock 来验证 SPA,你需要在 `app/Http/Kernel.php` 文件中将 Airlock 的中间件添加到你的 `api` 中间件组中:
64 
65    use Laravel\Airlock\Http\Middleware\EnsureFrontendRequestsAreStateful;
 63假如你需要使用 Sanctum 来验证 SPA,你需要在 `app/Http/Kernel.php` 文件中将 Sanctum 的中间件添加到你的 `api` 中间件组中:
 64
 65   use Laravel\Sanctum\Http\Middleware\EnsureFrontendRequestsAreStateful;
6666
6767   'api' => [
6868       EnsureFrontendRequestsAreStateful::class,
 
7575<a name="api-token-authentication"></a>
7676## API 令牌认证
7777
78 > 提示:当需要为SPA应用选择认证方案的时候,应该首选 Airlock 内置的 [SPA认证](#spa-authentication) 而不是API令牌。
 78> 提示:当需要为SPA应用选择认证方案的时候,应该首选 Sanctum 内置的 [SPA认证](#spa-authentication) 而不是API令牌。
7979<a name="issuing-api-tokens"></a>
8080
8181### 发行 API 令牌
8282
83 可以使用 Airlock 发行 **API令牌/个人访问令牌** 对你的API请求进行认证。 当使用API令牌进行请求的时,令牌可以以`Bearer`的形式包含在`Authorization` header头里。
 83可以使用 Sanctum 发行 **API令牌/个人访问令牌** 对你的API请求进行认证。 当使用API令牌进行请求的时,令牌可以以`Bearer`的形式包含在`Authorization` header头里。
8484
8585给用户发行令牌的时候,user模型里应该使用`HasApiTokens` trait:
8686
87    use Laravel\Airlock\HasApiTokens;
 87   use Laravel\Sanctum\HasApiTokens;
8888
8989   class User extends Authenticatable
9090   {
9191       use HasApiTokens, Notifiable;
9292   }
9393
94 要发行一个令牌,需要使用 `createToken` 方法。 `createToken` 方法返回一个`Laravel\Airlock\NewAccessToken` 实例。在存入数据库之前,API令牌已使用 SHA-256 哈希加密过,但是可以用 `NewAccessToken`实例的 `plainTextToken` 属性访问令牌的纯文本值。令牌创建后,应该立即向用户展示这个纯文本值:
 94要发行一个令牌,需要使用 `createToken` 方法。 `createToken` 方法返回一个`Laravel\Sanctum\NewAccessToken` 实例。在存入数据库之前,API令牌已使用 SHA-256 哈希加密过,但是可以用 `NewAccessToken`实例的 `plainTextToken` 属性访问令牌的纯文本值。令牌创建后,应该立即向用户展示这个纯文本值:
9595
9696   $token = $user->createToken('token-name');
9797
 
109109<a name="token-abilities"></a>
110110### 令牌能力
111111
112 Airlock可以为令牌分配 "abilities" ,类似于OAuth的 "scopes"。可以将字符串**能力**数组作为第二个参数传递给 `createToken` 方法:
 112Sanctum可以为令牌分配 "abilities" ,类似于OAuth的 "scopes"。可以将字符串**能力**数组作为第二个参数传递给 `createToken` 方法:
113113
114114   return $user->createToken('token-name', ['server:update'])->plainTextToken;
115115
116 在使用Airlock处理一个请求的时候,可以使用 `tokenCan` 方法来决定令牌是否具有给定的能力:
 116在使用Sanctum处理一个请求的时候,可以使用 `tokenCan` 方法来决定令牌是否具有给定的能力:
117117
118118   if ($user->tokenCan('server:update')) {
119119       //
120120   }
121121
122 > 提示: 为了方便,如果你的SPA应用使用了Airlock内置的[SPA 认证](#spa-authentication),当一个已经认证的请求进来的时候,`tokenCan` 方法将总是返回 `true`
 122> 提示: 为了方便,如果你的SPA应用使用了Sanctum内置的[SPA 认证](#spa-authentication),当一个已经认证的请求进来的时候,`tokenCan` 方法将总是返回 `true`
123123
124124<a name="protecting-routes"></a>
125125### 保护路由
126126
127 为了保护路由,所有进来的请求都必须进行认证,应该将 `airlock` 认证守卫附加到 `routes/api.php` 的API路由里。如果一个请求是来自第三方的请求,这个守卫会确保进来的请求既是一个你的SPA应用的有状态的已认证请求,也是一个包含了有效令牌头的已认证请求:
128 
129    Route::middleware('auth:airlock')->get('/user', function (Request $request) {
 127为了保护路由,所有进来的请求都必须进行认证,应该将 `Sanctum` 认证守卫附加到 `routes/api.php` 的API路由里。如果一个请求是来自第三方的请求,这个守卫会确保进来的请求既是一个你的SPA应用的有状态的已认证请求,也是一个包含了有效令牌头的已认证请求:
 128
 129   Route::middleware('auth:Sanctum')->get('/user', function (Request $request) {
130130       return $request->user();
131131   });
132132
 
149149
150150## SPA 认证
151151
152 Airlock为单页面应用 (SPAs) 与Laravel支持的API之间进行通信提供了一套简便的认证方法。这些SPAs 可以与你的Laravel 应用在同一个存储层中,也可以完全分离于存储层之外,比如通过 Vue CLI构建的SPA。
153 
154 对于这个特性,Airlock不使用其他任何类型的令牌。相反,Airlock 使用的是Laravel内置的基于cookie的session认证服务。这带来了诸多好处,比如CSRF保护,以及防止通过XSS泄漏身份验证凭据。Airlock 只会在传入的请求来自于你自己的SPA前端时尝试使用cookie进行身份验证。
 152Sanctum为单页面应用 (SPAs) 与Laravel支持的API之间进行通信提供了一套简便的认证方法。这些SPAs 可以与你的Laravel 应用在同一个存储层中,也可以完全分离于存储层之外,比如通过 Vue CLI构建的SPA。
 153
 154对于这个特性,Sanctum不使用其他任何类型的令牌。相反,Sanctum 使用的是Laravel内置的基于cookie的session认证服务。这带来了诸多好处,比如CSRF保护,以及防止通过XSS泄漏身份验证凭据。Sanctum 只会在传入的请求来自于你自己的SPA前端时尝试使用cookie进行身份验证。
155155
156156
157157
 
161161
162162#### 配置你的第一方域
163163
164 首先,你应该配置你的单页面应用将从哪个域发出请求。你可以使用`airlock`配置文件中的`stateful`配置选项配置这些域。此配置设置确定在向你的API发出请求时,哪些域将使用Laravel会话cookie来维持“有状态的”身份验证。
165 
166 #### Airlock 中间件
167 
168 接下来,你应该将Airlock的中间件添加到`app/Http/Kernel.php`文件中的`api`中间件组中。该中间件负责确保来自单页面应用的传入请求可以使用Laravel的会话cookie进行身份验证,同时仍允许来自第三方或移动应用程序的请求使用API令牌进行身份验证:
169 
170    use Laravel\Airlock\Http\Middleware\EnsureFrontendRequestsAreStateful;
 164首先,你应该配置你的单页面应用将从哪个域发出请求。你可以使用`Sanctum`配置文件中的`stateful`配置选项配置这些域。此配置设置确定在向你的API发出请求时,哪些域将使用Laravel会话cookie来维持“有状态的”身份验证。
 165
 166#### Sanctum 中间件
 167
 168接下来,你应该将Sanctum的中间件添加到`app/Http/Kernel.php`文件中的`api`中间件组中。该中间件负责确保来自单页面应用的传入请求可以使用Laravel的会话cookie进行身份验证,同时仍允许来自第三方或移动应用程序的请求使用API令牌进行身份验证:
 169
 170   use Laravel\Sanctum\Http\Middleware\EnsureFrontendRequestsAreStateful;
171171
172172   'api' => [
173173       EnsureFrontendRequestsAreStateful::class,
 
200200<a name="spa-authenticating"></a>
201201### 验证
202202
203 要对单页面应用进行身份验证,你的单页面应用的登录页面应首先向`/airlock/csrf-cookie`路由发出请求,以初始化应用程序的CSRF保护:
204 
205    axios.get('/airlock/csrf-cookie').then(response => {
 203要对单页面应用进行身份验证,你的单页面应用的登录页面应首先向`/Sanctum/csrf-cookie`路由发出请求,以初始化应用程序的CSRF保护:
 204
 205   axios.get('/Sanctum/csrf-cookie').then(response => {
206206       // 登录...
207207   });
208208
 
218218<a name="protecting-spa-routes"></a>
219219### 路由保护
220220
221 为了保护路由,因此必须对所有传入的请求进行身份验证,你应该在`routes/api.php`文件中为你的API路由附加`airlock` 授权看守器。如果请求来自你的单页面应用,此看守器会确保传入的请求被验证为有状态的已验证请求,如果请求来自第三方,它将使请求包含有效的API令牌头:
222 
223    Route::middleware('auth:airlock')->get('/user', function (Request $request) {
 221为了保护路由,因此必须对所有传入的请求进行身份验证,你应该在`routes/api.php`文件中为你的API路由附加`Sanctum` 授权看守器。如果请求来自你的单页面应用,此看守器会确保传入的请求被验证为有状态的已验证请求,如果请求来自第三方,它将使请求包含有效的API令牌头:
 222
 223   Route::middleware('auth:Sanctum')->get('/user', function (Request $request) {
224224       return $request->user();
225225   });
226226
 
232232
233233如果你的单页面应用需要通过[private / presence broadcast channels](/docs/{{version}}/broadcasting#authorizing-channels)进行身份认证,你需要在你的`routes/api.php`文件中调用`Broadcast::routes`方法:
234234
235    Broadcast::routes(['middleware' => ['auth:airlock']]);
 235   Broadcast::routes(['middleware' => ['auth:Sanctum']]);
236236
237237接下来, 为了使Pusher的授权请求成功, 你需要在初始化[Laravel Echo](/docs/{{version}}/broadcasting#installing-laravel-echo)时提供自定义的Pusher`authorizer`。这可以让你的应用程序将Pusher配置为 [为了跨域请求正确配置的](#cors-and-cookies)`axios`实例:
238238
 
266266<a name="mobile-application-authentication"></a>
267267## 移动应用身份验证
268268
269 你可以使用Airlock令牌的对你移动应用程序的路由请求进行身份认证。验证移动应用程序请求的过程与验证第三方接口请求的过程类似,但是,他们在颁发API令牌的方式上存在细微的差异。
 269你可以使用Sanctum令牌的对你移动应用程序的路由请求进行身份认证。验证移动应用程序请求的过程与验证第三方接口请求的过程类似,但是,他们在颁发API令牌的方式上存在细微的差异。
270270
271271<a name="issuing-mobile-api-tokens"></a>
272272### 颁发API令牌
273273
274 开始时,创建接受用户的电子邮件/用户名、密码和设备名称的路由,然后将这些凭据交换为新的Airlock令牌。终端将返回纯文本Airlock令牌,然后该令牌可以存储在移动设备上,并用于发出其他API请求:
 274开始时,创建接受用户的电子邮件/用户名、密码和设备名称的路由,然后将这些凭据交换为新的Sanctum令牌。终端将返回纯文本Sanctum令牌,然后该令牌可以存储在移动设备上,并用于发出其他API请求:
275275
276276   use App\User;
277277   use Illuminate\Http\Request;
278278   use Illuminate\Support\Facades\Hash;
279279   use Illuminate\Validation\ValidationException;
280280
281    Route::post('/airlock/token', function (Request $request) {
 281   Route::post('/Sanctum/token', function (Request $request) {
282282       $request->validate([
283283           'email' => 'required|email',
284284           'password' => 'required',
 
303303<a name="protecting-mobile-api-routes"></a>
304304### 路由保护
305305
306 如前所述,您需要保护路由,因此必须通过在路由上附加`airlock`身份验证看守器来对所有传入请求进行身份验证。一般来说,你会将此看守器附加到`routes/api.php`文件中定义的路由上:
307 
308    Route::middleware('auth:airlock')->get('/user', function (Request $request) {
 306如前所述,您需要保护路由,因此必须通过在路由上附加`Sanctum`身份验证看守器来对所有传入请求进行身份验证。一般来说,你会将此看守器附加到`routes/api.php`文件中定义的路由上:
 307
 308   Route::middleware('auth:Sanctum')->get('/user', function (Request $request) {
309309       return $request->user();
310310   });
311311
 
326326<a name="testing"></a>
327327## 测试
328328
329 在测试期间,`Airlock::actingAs`方法可用于验证用户身份并指定授予其令牌的能力:
 329在测试期间,`Sanctum::actingAs`方法可用于验证用户身份并指定授予其令牌的能力:
330330
331331   use App\User;
332    use Laravel\Airlock\Airlock;
 332   use Laravel\Sanctum\Sanctum;
333333
334334   public function test_task_list_can_be_retrieved()
335335   {
336        Airlock::actingAs(
 336       Sanctum::actingAs(
337337           factory(User::class)->create(),
338338           ['view-tasks']
339339       );
 
345345
346346如果要授予令牌所有功能,则应在`actingAs`方法提供的功能列表中加入`*`:
347347
348    Airlock::actingAs(
 348   Sanctum::actingAs(
349349       factory(User::class)->create(),
350350       ['*']
351351   );