官方已修改Airlock
相关信息:
- 类型:文档文章
- 文章: Sanctum 轻量级 API 认证
- 文档: 《Laravel 7 中文文档(7.x)》
此投稿已在 4年前 合并。
标题修改:
内容修改:
Old | New | Differences |
---|---|---|
1 | # Laravel | |
1 | # Laravel Sanctum | |
2 | 2 | |
3 | 3 | - [介绍](#introduction) |
4 | 4 | - [工作原理](#how-it-works) | … | … |
22 | 22 | <a name="introduction"></a> |
23 | 23 | ## 介绍 |
24 | 24 | |
25 | Laravel | |
25 | Laravel Sanctum 为 SPA (单页面应用程序)、移动应用程序和简单的、基于令牌的 API 提供轻量级身份验证系统。Sanctum 允许应用程序的每个用户为他们的帐户生成多个 API 令牌。这些令牌可能被授予指定允许令牌执行哪些操作的能力/范围。 | |
26 | 26 | |
27 | 27 | <a name="how-it-works"></a> |
28 | 28 | ### 工作原理 |
29 | 29 | |
30 | 30 | #### API 令牌 |
31 | 31 | |
32 | Laravel | |
33 |
| |
34 | Laravel | |
32 | Laravel Sanctum 是为了解决两个独立问题而生。 首先,它是一个简单的包,用于向用户发出 API 令牌,而不涉及 OAuth。这个功能的灵感来自 GitHub 的「访问令牌」。例如,假设应用程序的「帐户设置」有一个界面,用户可以在其中为其帐户生成 API 令牌。您可以使用 Sanctum 来生成和管理这些令牌。这些令牌通常有很长的过期时间(以年计),当然用户是可以随时手动撤销它们的。 | |
33 | ||
34 | Laravel Sanctum 的这个特性是通过将用户 API 令牌存储在单个数据库表中,并通过包含了有效 API 令牌的`Authorization`标头对传入请求进行身份验证而实现的。 | |
35 | 35 | |
36 | 36 | |
37 | 37 | |
38 | 38 | |
39 | 39 | #### SPA 身份验证 |
40 | 40 | |
41 | >「提示」 | |
42 |
| |
43 | ||
44 |
| |
45 | 对于此功能, | |
41 | >「提示」Sanctum 适用于 API 令牌认证或 SPA 身份认证,使用 Sanctum 并不意味着你需要用到它所提供全部特性。 | |
42 | ||
43 | Sanctum 提供了一种简单的方法来认证需要与基于 Laravel 的 API 进行通信的单页应用程序 (SPAs)。这些 SPA 可能与 Laravel 应用程序存在于同一仓库中,也可能是一个完全独立的仓库,例如使用 Vue CLI 创建的单页应用程序 | |
44 | ||
45 | 对于此功能,Sanctum 不使用任何类型的令牌。相反,Sanctum 使用 Laravel 内置的基于 cookie 的会话身份验证服务。这提供了CSRF保护,会话身份验证以及防止因 XSS 攻击而泄漏身份验证凭据。仅当传入请求来自您自己的 SPA 前端时,Sanctum 才会尝试使用 Cookie 进行身份验证。 | |
46 | 46 | |
47 | 47 | <a name="installation"></a> |
48 | 48 | ## 安装过程 |
49 | 49 | |
50 | 你可以通过 Composer 安装 Laravel | |
51 |
| |
52 | composer require laravel/ | |
53 |
| |
54 | 接下来,你需要使用 `vendor:publish` Artisan 命令发布 | |
55 |
| |
56 | php artisan vendor:publish --provider="Laravel\ | |
57 |
| |
58 |
| |
59 | 最后,你需要执行数据库迁移文件。 | |
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 令牌: | |
60 | 60 | |
61 | 61 | php artisan migrate |
62 | 62 | |
63 | 假如你需要使用 | |
64 |
| |
65 | use Laravel\ | |
63 | 假如你需要使用 Sanctum 来验证 SPA,你需要在 `app/Http/Kernel.php` 文件中将 Sanctum 的中间件添加到你的 `api` 中间件组中: | |
64 | ||
65 | use Laravel\Sanctum\Http\Middleware\EnsureFrontendRequestsAreStateful; | |
66 | 66 | |
67 | 67 | 'api' => [ |
68 | 68 | EnsureFrontendRequestsAreStateful::class, | … | … |
75 | 75 | <a name="api-token-authentication"></a> |
76 | 76 | ## API 令牌认证 |
77 | 77 | |
78 | > 提示:当需要为SPA应用选择认证方案的时候,应该首选 | |
78 | > 提示:当需要为SPA应用选择认证方案的时候,应该首选 Sanctum 内置的 [SPA认证](#spa-authentication) 而不是API令牌。 | |
79 | 79 | <a name="issuing-api-tokens"></a> |
80 | 80 | |
81 | 81 | ### 发行 API 令牌 |
82 | 82 | |
83 | 可以使用 | |
83 | 可以使用 Sanctum 发行 **API令牌/个人访问令牌** 对你的API请求进行认证。 当使用API令牌进行请求的时,令牌可以以`Bearer`的形式包含在`Authorization` header头里。 | |
84 | 84 | |
85 | 85 | 给用户发行令牌的时候,user模型里应该使用`HasApiTokens` trait: |
86 | 86 | |
87 | use Laravel\ | |
87 | use Laravel\Sanctum\HasApiTokens; | |
88 | 88 | |
89 | 89 | class User extends Authenticatable |
90 | 90 | { |
91 | 91 | use HasApiTokens, Notifiable; |
92 | 92 | } |
93 | 93 | |
94 | 要发行一个令牌,需要使用 `createToken` 方法。 `createToken` 方法返回一个`Laravel\ | |
94 | 要发行一个令牌,需要使用 `createToken` 方法。 `createToken` 方法返回一个`Laravel\Sanctum\NewAccessToken` 实例。在存入数据库之前,API令牌已使用 SHA-256 哈希加密过,但是可以用 `NewAccessToken`实例的 `plainTextToken` 属性访问令牌的纯文本值。令牌创建后,应该立即向用户展示这个纯文本值: | |
95 | 95 | |
96 | 96 | $token = $user->createToken('token-name'); |
97 | 97 | … | … |
109 | 109 | <a name="token-abilities"></a> |
110 | 110 | ### 令牌能力 |
111 | 111 | |
112 | ||
112 | Sanctum可以为令牌分配 "abilities" ,类似于OAuth的 "scopes"。可以将字符串**能力**数组作为第二个参数传递给 `createToken` 方法: | |
113 | 113 | |
114 | 114 | return $user->createToken('token-name', ['server:update'])->plainTextToken; |
115 | 115 | |
116 | 在使用 | |
116 | 在使用Sanctum处理一个请求的时候,可以使用 `tokenCan` 方法来决定令牌是否具有给定的能力: | |
117 | 117 | |
118 | 118 | if ($user->tokenCan('server:update')) { |
119 | 119 | // |
120 | 120 | } |
121 | 121 | |
122 | > 提示: 为了方便,如果你的SPA应用使用了 | |
122 | > 提示: 为了方便,如果你的SPA应用使用了Sanctum内置的[SPA 认证](#spa-authentication),当一个已经认证的请求进来的时候,`tokenCan` 方法将总是返回 `true` | |
123 | 123 | |
124 | 124 | <a name="protecting-routes"></a> |
125 | 125 | ### 保护路由 |
126 | 126 | |
127 | 为了保护路由,所有进来的请求都必须进行认证,应该将 ` | |
128 |
| |
129 | Route::middleware('auth: | |
127 | 为了保护路由,所有进来的请求都必须进行认证,应该将 `Sanctum` 认证守卫附加到 `routes/api.php` 的API路由里。如果一个请求是来自第三方的请求,这个守卫会确保进来的请求既是一个你的SPA应用的有状态的已认证请求,也是一个包含了有效令牌头的已认证请求: | |
128 | ||
129 | Route::middleware('auth:Sanctum')->get('/user', function (Request $request) { | |
130 | 130 | return $request->user(); |
131 | 131 | }); |
132 | 132 | … | … |
149 | 149 | |
150 | 150 | ## SPA 认证 |
151 | 151 | |
152 | ||
153 |
| |
154 | 对于这个特性, | |
152 | Sanctum为单页面应用 (SPAs) 与Laravel支持的API之间进行通信提供了一套简便的认证方法。这些SPAs 可以与你的Laravel 应用在同一个存储层中,也可以完全分离于存储层之外,比如通过 Vue CLI构建的SPA。 | |
153 | ||
154 | 对于这个特性,Sanctum不使用其他任何类型的令牌。相反,Sanctum 使用的是Laravel内置的基于cookie的session认证服务。这带来了诸多好处,比如CSRF保护,以及防止通过XSS泄漏身份验证凭据。Sanctum 只会在传入的请求来自于你自己的SPA前端时尝试使用cookie进行身份验证。 | |
155 | 155 | |
156 | 156 | |
157 | 157 | … | … |
161 | 161 | |
162 | 162 | #### 配置你的第一方域 |
163 | 163 | |
164 | 首先,你应该配置你的单页面应用将从哪个域发出请求。你可以使用` | |
165 |
| |
166 | #### | |
167 |
| |
168 | 接下来,你应该将 | |
169 |
| |
170 | use Laravel\ | |
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; | |
171 | 171 | |
172 | 172 | 'api' => [ |
173 | 173 | EnsureFrontendRequestsAreStateful::class, | … | … |
200 | 200 | <a name="spa-authenticating"></a> |
201 | 201 | ### 验证 |
202 | 202 | |
203 | 要对单页面应用进行身份验证,你的单页面应用的登录页面应首先向`/ | |
204 |
| |
205 | axios.get('/ | |
203 | 要对单页面应用进行身份验证,你的单页面应用的登录页面应首先向`/Sanctum/csrf-cookie`路由发出请求,以初始化应用程序的CSRF保护: | |
204 | ||
205 | axios.get('/Sanctum/csrf-cookie').then(response => { | |
206 | 206 | // 登录... |
207 | 207 | }); |
208 | 208 | … | … |
218 | 218 | <a name="protecting-spa-routes"></a> |
219 | 219 | ### 路由保护 |
220 | 220 | |
221 | 为了保护路由,因此必须对所有传入的请求进行身份验证,你应该在`routes/api.php`文件中为你的API路由附加` | |
222 |
| |
223 | Route::middleware('auth: | |
221 | 为了保护路由,因此必须对所有传入的请求进行身份验证,你应该在`routes/api.php`文件中为你的API路由附加`Sanctum` 授权看守器。如果请求来自你的单页面应用,此看守器会确保传入的请求被验证为有状态的已验证请求,如果请求来自第三方,它将使请求包含有效的API令牌头: | |
222 | ||
223 | Route::middleware('auth:Sanctum')->get('/user', function (Request $request) { | |
224 | 224 | return $request->user(); |
225 | 225 | }); |
226 | 226 | … | … |
232 | 232 | |
233 | 233 | 如果你的单页面应用需要通过[private / presence broadcast channels](/docs/{{version}}/broadcasting#authorizing-channels)进行身份认证,你需要在你的`routes/api.php`文件中调用`Broadcast::routes`方法: |
234 | 234 | |
235 | Broadcast::routes(['middleware' => ['auth: | |
235 | Broadcast::routes(['middleware' => ['auth:Sanctum']]); | |
236 | 236 | |
237 | 237 | 接下来, 为了使Pusher的授权请求成功, 你需要在初始化[Laravel Echo](/docs/{{version}}/broadcasting#installing-laravel-echo)时提供自定义的Pusher`authorizer`。这可以让你的应用程序将Pusher配置为 [为了跨域请求正确配置的](#cors-and-cookies)`axios`实例: |
238 | 238 | … | … |
266 | 266 | <a name="mobile-application-authentication"></a> |
267 | 267 | ## 移动应用身份验证 |
268 | 268 | |
269 | 你可以使用 | |
269 | 你可以使用Sanctum令牌的对你移动应用程序的路由请求进行身份认证。验证移动应用程序请求的过程与验证第三方接口请求的过程类似,但是,他们在颁发API令牌的方式上存在细微的差异。 | |
270 | 270 | |
271 | 271 | <a name="issuing-mobile-api-tokens"></a> |
272 | 272 | ### 颁发API令牌 |
273 | 273 | |
274 | 开始时,创建接受用户的电子邮件/用户名、密码和设备名称的路由,然后将这些凭据交换为新的 | |
274 | 开始时,创建接受用户的电子邮件/用户名、密码和设备名称的路由,然后将这些凭据交换为新的Sanctum令牌。终端将返回纯文本Sanctum令牌,然后该令牌可以存储在移动设备上,并用于发出其他API请求: | |
275 | 275 | |
276 | 276 | use App\User; |
277 | 277 | use Illuminate\Http\Request; |
278 | 278 | use Illuminate\Support\Facades\Hash; |
279 | 279 | use Illuminate\Validation\ValidationException; |
280 | 280 | |
281 | Route::post('/ | |
281 | Route::post('/Sanctum/token', function (Request $request) { | |
282 | 282 | $request->validate([ |
283 | 283 | 'email' => 'required|email', |
284 | 284 | 'password' => 'required', | … | … |
303 | 303 | <a name="protecting-mobile-api-routes"></a> |
304 | 304 | ### 路由保护 |
305 | 305 | |
306 | 如前所述,您需要保护路由,因此必须通过在路由上附加` | |
307 |
| |
308 | Route::middleware('auth: | |
306 | 如前所述,您需要保护路由,因此必须通过在路由上附加`Sanctum`身份验证看守器来对所有传入请求进行身份验证。一般来说,你会将此看守器附加到`routes/api.php`文件中定义的路由上: | |
307 | ||
308 | Route::middleware('auth:Sanctum')->get('/user', function (Request $request) { | |
309 | 309 | return $request->user(); |
310 | 310 | }); |
311 | 311 | … | … |
326 | 326 | <a name="testing"></a> |
327 | 327 | ## 测试 |
328 | 328 | |
329 | 在测试期间,` | |
329 | 在测试期间,`Sanctum::actingAs`方法可用于验证用户身份并指定授予其令牌的能力: | |
330 | 330 | |
331 | 331 | use App\User; |
332 | use Laravel\ | |
332 | use Laravel\Sanctum\Sanctum; | |
333 | 333 | |
334 | 334 | public function test_task_list_can_be_retrieved() |
335 | 335 | { |
336 | | |
336 | Sanctum::actingAs( | |
337 | 337 | factory(User::class)->create(), |
338 | 338 | ['view-tasks'] |
339 | 339 | ); | … | … |
345 | 345 | |
346 | 346 | 如果要授予令牌所有功能,则应在`actingAs`方法提供的功能列表中加入`*`: |
347 | 347 | |
348 | | |
348 | Sanctum::actingAs( | |
349 | 349 | factory(User::class)->create(), |
350 | 350 | ['*'] |
351 | 351 | ); |