laravel中实现api认证的首选方案是使用laravel sanctum，它轻量且适用于spa、移动应用及简单api令牌需求。1. 安装sanctum并发布配置文件和迁移表；2. 在user模型中引入hasapiTokens trait；3. 使用auth:sanctum中间件保护api路由；4. 通过createtoken生成带能力的令牌并在客户端请求头中携带；5. 对spa可配置会话Cookie认证方式。相比passport，sanctum更简洁，适合多数场景；而jwt、Session认证和basic auth则适用于特定用例。
在Laravel中实现API认证，最常见也最推荐的方式是使用Laravel Sanctum。它能很好地处理单页面应用（SPA）、移动应用以及简单的API令牌认证需求，轻量且高效。如果你需要更复杂的OAuth2功能，比如允许第三方应用访问你的API，那么Laravel Passport会是你的选择。绝大多数情况下，Sanctum就能满足日常开发所需。
解决方案
要在Laravel中实现API认证，我们通常会选择Laravel Sanctum。它为SPA、移动应用和简单的API令牌提供了简洁的认证系统。
1. 安装与配置Sanctum 首先，把Sanctum请到你的项目里：
composer require laravel/sanctum
然后发布其配置文件和运行数据库迁移：
php artisan vendor:publish --provider="LaravelSanctumSanctumServiceProvider" php artisan migrate
这会创建一张 personal_access_tokens 表，用来存储用户的API令牌。
2. 用户模型准备 在你的 AppModelsUser 模型中，引入 HasApiTokens trait：
// app/Models/User.php use LaravelSanctumHasApiTokens; use IlluminateNotificationsNotifiable; use IlluminateFoundationAuthUser as Authenticatable; class User extends Authenticatable { use HasApiTokens, Notifiable; // ... 其他模型内容 }
这个trait会为你的用户模型添加管理API令牌的方法。
3. API路由保护 在 routes/api.php 文件中，你可以使用 auth:sanctum 中间件来保护你的API路由：
// routes/api.php use IlluminatehttpRequest; use IlluminateSupportFacadesRoute; Route::middleware('auth:sanctum')->get('/user', function (Request $request) { return $request->user(); }); Route::post('/logout', function (Request $request) { $request->user()->currentAccessToken()->delete(); return response()->noContent(); })->middleware('auth:sanctum'); // 你的其他受保护API路由 Route::middleware('auth:sanctum')->group(function () { Route::get('/projects', function () { // ... }); Route::post('/projects', function () { // ... }); });
任何访问 /user 或 /projects 路由的请求，都需要携带有效的Sanctum令牌或通过会话认证。
4. 令牌的生成与使用 对于移动应用或第三方API调用，你需要为用户生成API令牌。这通常在一个认证控制器中完成：
// 例如：app/Http/Controllers/Api/AuthController.php use IlluminateHttpRequest; use IlluminateSupportFacadesAuth; use AppModelsUser; use IlluminateSupportFacadesHash; class AuthController extends Controller { public function login(Request $request) { $request->validate([ 'email' => 'required|email', 'password' => 'required', 'device_name' => 'required', // 例如：'iphone 15 Pro' ]); $user = User::where('email', $request->email)->first(); if (! $user || ! Hash::check($request->password, $user->password)) { return response()->json(['message' => '凭据不匹配'], 401); } // 创建令牌，可以指定能力（abilities） $token = $user->createToken($request->device_name, ['server:update', 'server:delete'])->plainTextToken; return response()->json(['token' => $token]); } public function revokeToken(Request $request) { // 撤销当前使用的令牌 $request->user()->currentAccessToken()->delete(); return response()->noContent(); } public function revokeAllTokens(Request $request) { // 撤销用户所有令牌 $request->user()->tokens()->delete(); return response()->noContent(); } }
客户端在后续请求中，需要将这个令牌放在 Authorization 请求头的 Bearer 方案中： Authorization: Bearer YOUR_GENERATED_TOKEN
5. SPA认证 (可选但推荐) 如果你在构建SPA，Sanctum还能通过会话Cookie提供认证，而无需手动管理令牌。这需要一些额外的配置：
- 确保你的SPA和API运行在同一个顶级域名下（例如：app.example.com 和 api.example.com）。
- 在SPA中，使用axios等HTTP客户端配置 withCredentials 为 true，并确保后端CORS配置允许你的SPA域名。
- 配置 sanctum.stateful 数组，将你的SPA域名添加到其中。
- 确保SPA在登录时，向Laravel后端发送POST请求到 /sanctum/csrf-cookie 路由，以获取CSRF令牌，然后进行登录。
Laravel API认证，为什么Sanctum是首选？
我个人觉得，对于绝大多数我们日常会遇到的API认证场景，Sanctum简直是为我们量身定制的。它最大的魅力在于它的简洁性和多功能性。你想想看，一个包就能同时搞定SPA的会话认证（就像传统的Web应用那样，用Cookie），又能搞定移动端或者第三方应用需要的API令牌认证，这多省事儿！
跟Passport比起来，Sanctum简直是轻量级的典范。Passport那套OAuth2的玩意儿，虽然强大，但它为的是解决更宏大的问题——比如你要让Google、facebook这种第三方服务通过OAuth2协议来访问你的API。它涉及客户端管理、授权码、刷新令牌等一系列复杂流程，搭建起来就挺费劲的。而我们平时写个App后端，或者给vue、React前端提供API，根本用不着那么重型的武器。Sanctum就是那个“小而美”的解决方案，它直接给你一个纯粹的API令牌管理能力，或者利用Laravel自带的Session机制，让SPA感觉就像在用传统的Web应用一样，省去了令牌存储、刷新等一系列前端的心智负担。
所以，除非你明确知道你的API需要支持OAuth2那种复杂的第三方授权流程，否则，直接上Sanctum，它能让你少掉很多头发。
如何在Laravel中安全地管理API令牌？
管理API令牌可不是生成一个扔给前端就完事儿了，这里面学问还挺多的，稍不留神就可能留下安全隐患。
1. 令牌的生命周期与能力 生成令牌时，考虑它的生命周期。如果是给一次性任务或者短期使用的，可以设置短一点的过期时间。Sanctum默认是不设过期时间的，但你可以通过在 config/sanctum.php 中设置 expiration 来控制。
更重要的是，利用Sanctum的“能力”（abilities）特性。你可以为每个令牌分配特定的权限，比如一个令牌只能读取数据，另一个才能写入。
$token = $user->createToken('admin-token', ['user:read', 'user:create', 'user:update', 'user:delete'])->plainTextToken; // 另一个令牌可能只有读取权限 $readOnlyToken = $user->createToken('guest-token', ['user:read'])->plainTextToken;
然后在你的API路由或控制器中，通过 tokenCan 方法来检查：
if ($request->user()->tokenCan('user:create')) { // 允许创建用户 }
这比简单的“有权限”或“没权限”要精细得多。
2. 客户端令牌存储 前端拿到令牌后，怎么存是个大问题。
- Web端（SPA）: 尽量避免直接存在 localStorage 里，因为它容易受到xss攻击。更安全的做法是使用 HttpOnly 的 Cookie。Sanctum在SPA模式下就是这么干的，它利用了Laravel的Session机制，并将Session ID存在HttpOnly Cookie中，前端无需直接操作令牌。
- 移动端: 存储在设备的安全存储区域，比如iOS的Keychain或android的Keystore，而不是明文存在应用沙盒里。
3. 令牌的撤销机制 用户退出登录时，务必撤销当前使用的令牌。Sanctum提供了 currentAccessToken()->delete() 方法来撤销正在使用的令牌。如果用户设备丢失，或者怀疑令牌泄露，你应该提供一个接口让用户可以撤销所有已颁发的令牌（$user->tokens()->delete()）。这就像你手机丢了，可以在电脑上远程抹掉所有数据一样。
4. 令牌的安全性 Sanctum会将令牌的哈希值存储在数据库中，而不是明文。这是基本要求。确保你的数据库连接是安全的，并且数据库本身也受到保护。
5. 速率限制 对API接口进行速率限制（Rate Limiting）是防止暴力破解令牌的有效手段。Laravel自带的速率限制中间件非常好用，可以限制每个IP或每个用户在特定时间内的请求次数。
// routes/api.php Route::middleware(['auth:sanctum', 'throttle:60,1'])->group(function () { Route::get('/user', function (Request $request) { return $request->user(); }); });
这表示每分钟只能请求 /user 60次。
除了Sanctum，Laravel还有哪些API认证方案，各自适用场景是什么？
除了Sanctum，Laravel生态里还有几种常见的API认证方案，每种都有它最适合的场景。
1. Laravel Passport (OAuth2)
- 是什么？ Laravel官方提供的OAuth2服务器实现。它完全遵循OAuth2协议，可以让你轻松地为自己的API提供完整的OAuth2认证流程，包括授权码、隐式、客户端凭据和密码授权等多种模式。
- 适用场景： 当你的API需要被第三方应用访问时，Passport是首选。比如，你想构建一个开放平台，允许其他开发者注册他们的应用，并通过OAuth2协议来获取用户授权，进而访问你的API数据。它提供了客户端管理、作用域（scopes）定义等高级功能，适合构建大型、开放的API平台。如果你只是为自己的前端或移动应用提供API，Passport可能会显得过于复杂。
2. 基于Session的认证 (Web认证)
- 是什么？ 这是Laravel默认的Web认证方式，依赖于HTTP Session和Cookie。用户登录后，服务器会创建一个Session，并在Cookie中存储Session ID。后续请求带着这个Cookie，服务器就能识别用户。
- 适用场景： 主要用于传统的Web应用，即前后端不分离或弱分离的项目。当你用Blade模板渲染页面，或者Vue/React应用和Laravel后端在同一个域名下，且前端每次请求都带上Cookie时，这种方式是自然的。但对于纯粹的、无状态的API（尤其是跨域或移动应用），Session认证就不太合适了，因为API通常需要无状态，不依赖服务器Session。
3. Basic Auth (HTTP基本认证)
- 是什么？ 一种非常简单的HTTP认证方式，通过在HTTP请求头中发送用户名和密码的Base64编码字符串进行认证。
- 适用场景： 通常用于内部API、调试或低安全性要求的场景。它简单易实现，但因为每次请求都发送明文（虽然是Base64编码，但很容易解码）的用户名和密码，所以必须在https环境下使用，否则极不安全。不适合公开或高安全性的API。
4. 第三方JWT包 (如 tymondesigns/jwt-auth)
- 是什么？ JSON Web Token（JWT）是一种开放标准（RFC 7519），定义了一种紧凑且自包含的方式，用于在各方之间安全地传输信息作为JSON对象。Laravel本身没有内置JWT认证，但有非常流行的第三方包如 tymondesigns/jwt-auth。
- 适用场景： 在Sanctum出现之前，JWT在无状态API认证中非常流行。它适用于需要完全无状态的API，并且可能需要跨多个服务共享认证状态的场景。JWT令牌包含用户身份信息，并经过签名，服务器无需查询数据库即可验证令牌的有效性。然而，JWT的令牌撤销相对复杂（因为它是无状态的），通常需要额外的黑名单机制。Sanctum的API令牌模式在很多方面可以替代JWT，并且与Laravel的集成度更高。
选择哪种方案，最终还是要看你的项目需求和安全考量。Sanctum的出现，确实让大多数Laravel API认证变得简单而高效，但理解其他方案的特点，能帮助你在遇到特定场景时做出更明智的决策。
