Laravel Sanctum提供轻量级API认证，支持SPA的会话认证与移动应用的个人访问令牌；其基于数据库验证令牌，适合第一方应用，相比JWT更易撤销，较OAuth2.0更简洁；实际使用中需注意CORS配置、令牌过期管理、权限最小化及HTTPS安全传输；多租户场景下可结合中间件解析租户并用全局作用域实现数据隔离。

Laravel Sanctum，说白了，就是Laravel官方提供的一个轻量级、用起来很顺手的API认证解决方案。它主要解决两种场景下的认证问题：一是单页面应用（SPA）与后端API的交互，二是移动应用或简单的第三方服务通过API进行认证。它不像OAuth2.0那么重，也不像JWT那样需要你操心令牌的自包含性，它更侧重于Laravel生态内的简洁与高效。API认证的实现，Sanctum提供了两种核心方式：一种是基于会话（session）的状态化认证，主要用于SPA；另一种则是基于个人访问令牌（Personal Access Token）的无状态认证，更适合移动应用或非浏览器客户端。

解决方案

要说具体怎么用Sanctum来搞定API认证，其实思路挺清晰的。

对于单页面应用（SPA），Sanctum利用了Laravel原有的session认证机制，但做了一些巧妙的扩展。当你的SPA和Laravel后端部署在同一个主域下（比如SPA在

app.example.com

，API在

api.example.com

），Sanctum会利用同源策略和HTTP-only的session cookie来保持用户的登录状态。你只需要在前端首次请求

sanctum/csrf-cookie

这个端点，Laravel就会给你设置一个CSRF令牌，后续的认证请求（比如登录）就会带上这个cookie，服务器就能识别用户了。这种方式的好处是，你不需要在前端手动管理令牌，一切都像传统的Web应用一样自然。但要注意，如果SPA和API不在同一个域，CORS配置就变得非常关键了。

而对于移动应用或者其他非浏览器客户端，Sanctum则提供了个人访问令牌（Personal Access Token）。这玩意儿的逻辑是这样的：用户通过传统的用户名密码登录后，你的应用可以为他们生成一个或多个令牌。每个令牌都有一串随机字符串，以及可选的“能力”（abilities），也就是这个令牌能干什么事（比如

['read', 'update']

）。这些令牌的哈希值会存储在数据库里。当客户端发起API请求时，它需要把这个令牌放在

Authorization

请求头里，格式是

Bearer {你的令牌}

。Laravel收到请求后，会查找数据库，验证令牌的有效性，并检查它是否拥有请求操作所需的能力。如果一切OK，请求就能继续处理了。这种方式是无状态的，服务器不需要维护会话，每次请求都带着令牌，非常适合分布式或移动场景。

Laravel Sanctum与JWT、OAuth2.0有何不同？我该如何选择？

这问题问得好，很多人在选择API认证方案时都会纠结。简单来说，Sanctum、JWT和OAuth2.0各有各的适用场景，不是非此即彼，更像是工具箱里的不同工具。

Sanctum和JWT（JSON Web Tokens）之间，核心差异在于令牌的“形态”和管理方式。JWT是一种自包含的令牌，它把用户信息、过期时间等数据都编码在令牌本身里，并且通过签名保证数据未被篡改。服务器拿到JWT后，不需要查询数据库就能验证其有效性（只要知道签名密钥）。听起来很酷，对吧？但问题来了，JWT一旦签发，除非过期，否则很难“撤销”——你不能简单地让一个JWT失效，除非维护一个黑名单，这又回到了有状态的麻烦。Sanctum的个人访问令牌则不同，它是“不透明”的，令牌本身不包含用户数据，只是一个随机字符串，服务器每次收到令牌，都需要去数据库里查一下，看看这个令牌是不是真的存在、是不是被撤销了、属于哪个用户。所以，Sanctum的令牌是数据库驱动的，撤销起来非常方便，直接从数据库删除就行。

Sanctum和OAuth2.0，这俩的定位就更不一样了。OAuth2.0是一个授权框架，它解决的核心问题是：如何让第三方应用安全地访问用户在另一个服务上的资源，而不需要用户把自己的账号密码直接给第三方应用。比如你用微信登录某个App，微信就是授权服务器，App是客户端，它只获得了你授权的特定权限（比如获取你的昵称和头像），而不是你的微信密码。OAuth2.0设计复杂，有多种授权模式（授权码、隐式、客户端凭证等），适用于大型、多服务、第三方集成的场景。Sanctum则更侧重于第一方认证，也就是你的SPA、你的移动App，访问你自己的后端API。它假设你对客户端有完全的控制权，不需要那么复杂的授权流程。

如何选择呢？

• 选择Sanctum： 如果你主要构建的是Laravel后端API，配合自己的SPA（同域或子域）、自己的移动App，或者是一些简单的、由你完全控制的第三方服务。Sanctum的轻量级和易用性会让你省心不少。它能很好地处理CSRF、session管理，个人访问令牌也足够灵活和安全。
• 选择JWT： 如果你的API需要被多个非Laravel服务使用，或者你需要构建一个真正无状态、可扩展性要求极高的微服务架构，并且你愿意承担JWT带来的令牌撤销管理复杂性，那么JWT可能更合适。但通常情况下，Sanctum已经足够满足大部分Laravel应用的需求了。
• 选择OAuth2.0： 如果你的应用需要与大量第三方服务集成，允许其他开发者构建应用来访问你的用户数据（比如提供一个开放平台），或者你需要实现非常精细的授权粒度控制，那OAuth2.0就是你唯一的选择。但对于一个简单的API或SPA，它会显得过于庞大和复杂。

在实际项目中，使用Laravel Sanctum时常遇到的挑战和最佳实践有哪些？

尽管Sanctum用起来很方便，但在实际项目中，还是会遇到一些小坑和值得注意的地方。

集简云

软件集成平台，快速建立企业自动化与智能化

21

查看详情

首先，一个常见的挑战是令牌的生命周期管理。Sanctum的个人访问令牌默认是永不过期的，除非你手动撤销。这意味着如果一个令牌被泄露，它将一直有效，直到你发现并删除它。所以，一个最佳实践是，你需要主动规划令牌的过期策略。比如，在生成令牌时，你可以给它设置一个

expires_at

字段（虽然Sanctum本身不直接提供这个功能，但你可以通过修改

personal_access_tokens

表结构或在应用层逻辑中实现），定期清理过期令牌。或者，在用户登出时，务必调用API撤销所有相关令牌。

其次，跨域资源共享（CORS）问题，尤其是当你的SPA和API部署在不同域名时，是个绕不开的话题。Sanctum的SPA认证依赖于Cookie，而Cookie有严格的同源策略。如果SPA和API不在同一个域，浏览器会阻止发送Cookie。这时候，你需要确保你的Laravel后端正确配置了CORS。这通常涉及到在

config/cors.php

中设置允许的源（

paths

）、允许的方法（

allowed_methods

）、允许的头（

allowed_headers

），以及最重要的是，设置

supports_credentials

为

true

，这样浏览器才能在跨域请求中发送认证信息（如Cookie）。如果CORS配置不当，前端会遇到各种预检请求失败或者认证头被拦截的问题。

再来，权限（Abilities）的精细化管理。Sanctum允许你为每个令牌分配不同的“能力”，比如

['post:create', 'post:update']

。但有时候，开发者可能会图省事，直接给令牌授予

['*']

，这意味着这个令牌拥有所有权限。这在安全上是非常危险的。最佳实践是，始终坚持最小权限原则，给令牌分配刚好够用的能力。并且，在你的API路由或控制器中，使用

can()

方法或

abilities

中间件来检查用户是否拥有执行特定操作的权限。

最后，一个容易被忽视但至关重要的点是HTTPS。无论是基于Cookie的SPA认证，还是基于Bearer Token的API认证，所有的通信都必须通过HTTPS进行。HTTP是明文传输，令牌或session ID在传输过程中极易被截获，从而导致严重的安全漏洞。所以，确保你的应用部署在HTTPS环境下，这是任何认证方案的基石。

如何为Laravel Sanctum配置多租户（Multi-tenancy）环境下的API认证？

在多租户（Multi-tenancy）环境下使用Laravel Sanctum进行API认证，确实会增加一层复杂性，因为它不仅仅是验证用户身份，还需要确保用户只能访问其所属租户的数据。Sanctum本身并不直接提供多租户的开箱即用支持，但它作为认证层，可以很好地与你的多租户逻辑结合。

核心思路是：Sanctum负责验证“谁”登录了，而你的应用层逻辑则负责验证这个“谁”有权访问“哪个租户”的数据。

一种常见的实现方式是基于中间件的租户解析与全局作用域（Global Scopes）。

1. Sanctum认证用户： 首先，让Sanctum像往常一样工作，验证用户的个人访问令牌，确保请求是由一个已知的、有效的用户发起的。这通常通过在你的API路由上应用

   auth:sanctum

   中间件来完成。

2. 租户标识的传递： 客户端在发起API请求时，需要某种方式来告知服务器它希望访问哪个租户的数据。这可以通过几种方式实现：

   • 子域名（Subdomain）： 比如

     tenant1.yourapp.com

     和

     tenant2.yourapp.com

     。

   • 请求头（Request Header）： 例如，

     X-Tenant-ID: tenant_uuid_or_id

     。

   • URL参数（Query Parameter）： 比如

     /api/posts?tenant_id=...

     （不推荐，因为容易忘记或被篡改）。

   请求头通常是比较推荐和清晰的方式。

3. 自定义租户解析中间件： 在

   auth:sanctum

   中间件之后，你需要创建一个自定义的中间件，比如

   ResolveTenantMiddleware

   。这个中间件的任务是：

   • 从请求中（子域名、请求头等）获取租户标识。
   • 根据这个标识，从数据库中查找对应的租户。
   • 验证当前认证用户是否属于或有权访问这个租户。 这是一个关键的安全检查。如果用户不属于请求的租户，应该立即拒绝请求（返回403 Forbidden）。
   • 将解析到的租户实例或其ID存储在某个全局可访问的地方（例如，绑定到Laravel的服务容器，或者使用一个单例类），以便后续的代码可以方便地访问当前租户信息。

   // app/Http/Middleware/ResolveTenantMiddleware.php namespace AppHttpMiddleware;  use Closure; use IlluminateHttpRequest; use AppModelsTenant; // 假设你有Tenant模型 use IlluminateSupportFacadesAuth;  class ResolveTenantMiddleware {     public function handle(Request $request, Closure $next)     {         $tenantId = $request->header('X-Tenant-ID'); // 从请求头获取租户ID          if (!$tenantId) {             // 如果没有提供租户ID，可以根据业务逻辑抛出错误或使用默认租户             abort(400, 'Tenant ID is required.');         }          $tenant = Tenant::find($tenantId);          if (!$tenant) {             abort(404, 'Tenant not found.');         }          // 验证当前认证用户是否属于该租户         if (Auth::check() && !Auth::user()->tenants->contains($tenant)) {             abort(403, 'You do not have access to this tenant.');         }          // 将当前租户绑定到服务容器，方便全局访问         app()->instance('currentTenant', $tenant);          return $next($request);     } }

   别忘了在

   app/Http/Kernel.php

   中注册这个中间件，并将其添加到你的API中间件组中，确保它在

   auth:sanctum

   之后执行。

4. 应用全局作用域（Global Scopes）： 这是实现数据隔离的关键。一旦租户被解析并设置到全局，你可以为所有需要进行租户隔离的模型（如

   Post

   ,

   Order

   ,

   Product

   等）定义一个全局作用域。这个作用域会在每次查询这些模型时，自动添加一个

   where('tenant_id', currentTenantId)

   的条件。

   // app/Scopes/TenantScope.php namespace AppScopes;  use IlluminateDatabaseEloquentBuilder; use IlluminateDatabaseEloquentModel; use IlluminateDatabaseEloquentScope;  class TenantScope implements Scope {     public function apply(Builder $builder, Model $model)     {         if (app()->bound('currentTenant')) {             $builder->where('tenant_id', app('currentTenant')->id);         }     } }  // 在你的模型中应用这个作用域，例如在AppServiceProvider的boot方法中 // AppModelsPost.php protected static function booted() {     static::addGlobalScope(new AppScopesTenantScope); }

通过这种方式，Sanctum专注于用户身份验证，而多租户的逻辑则通过自定义中间件和全局作用域来优雅地处理，确保了数据安全和隔离。记住，确保你的数据库表中都有

tenant_id

字段来关联数据和租户。

以上就是Laravel Sanctum作用？API认证如何实现？的详细内容，更多请关注php laravel js 前端 json cookie cad 微信 浏览器 app access 工具 php laravel 架构 分布式 中间件 json csrf Cookie Session Token 字符串 作用域 数据库 http https Access 开放平台