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认证变得简单而高效,但理解其他方案的特点,能帮助你在遇到特定场景时做出更明智的决策。