Laravel Sanctum如何实现API认证_轻量级API令牌认证

裘德小鎮的故事

发布时间：2025-09-24 14:44:02

1003人浏览过

来源于php中文网

原创

Laravel Sanctum通过API令牌实现轻量级认证，用户登录后生成令牌并用于请求头验证身份。安装需用Composer引入并发布迁移文件，创建personal_access_tokens表存储令牌。User模型需引入HasApiTokens trait以支持令牌管理。登录成功后调用createToken生成明文令牌，返回时仅传递plainTextToken。保护API路由需在api.php中使用auth:sanctum中间件，客户端请求时携带Bearer格式的Authorization头。支持多设备登录，每个令牌关联用户与设备，可撤销当前、指定或全部令牌。相比Passport，Sanctum更适用于SPA和移动应用等简单场景，Passport则适合需要OAuth 2.0的复杂授权。可通过config/sanctum.php设置令牌有效期，重写createToken方法自定义生成逻辑，或编写中间件扩展验证规则，满足高级认证需求。

laravel sanctum如何实现api认证_轻量级api令牌认证

Laravel Sanctum 是一种轻量级的 API 认证方案，它主要通过生成 API 令牌来实现认证。简单来说，用户登录后，可以生成一个或多个令牌，然后在请求 API 时，通过 Authorization 请求头传递令牌，Sanctum 会验证令牌的有效性，从而确定用户身份。

解决方案

安装 Sanctum:

首先，通过 Composer 安装 Sanctum：
```
composer require laravel/sanctum
```
然后，发布 Sanctum 的配置文件和迁移文件：
```
php artisan vendor:publish --provider="Laravel\Sanctum\SanctumServiceProvider"
php artisan migrate
```
这会在数据库中创建一个 personal_access_tokens 表，用于存储 API 令牌。

配置 User 模型:

在 App\Models\User 模型中，引入 HasApiTokens trait：

namespace App\Models;

use Illuminate\Foundation\Auth\User as Authenticatable;
use Laravel\Sanctum\HasApiTokens;

class User extends Authenticatable
{
    use HasApiTokens;

    // ...
}

这个 trait 提供了生成和管理 API 令牌的方法。

生成 API 令牌:

在用户登录或注册后，可以生成 API 令牌。例如，在登录控制器中：

use Illuminate\Support\Facades\Auth;
use App\Models\User;

public function login(Request $request)
{
    $credentials = $request->validate([
        'email' => 'required|email',
        'password' => 'required',
    ]);

    if (Auth::attempt($credentials)) {
        $user = Auth::user();
        $token = $user->createToken('auth_token')->plainTextToken;

        return response()->json([
            'access_token' => $token,
            'token_type' => 'Bearer',
        ]);
    }

    return response()->json(['message' => 'Invalid credentials'], 401);
}

createToken 方法会生成一个令牌，并返回包含令牌值的明文。注意，务必只在生成令牌时返回明文，之后应只存储哈希值。

保护 API 路由:

在 routes/api.php 文件中，使用 auth:sanctum 中间件来保护需要认证的 API 路由：
```
Route::middleware('auth:sanctum')->get('/user', function (Request $request) {
    return $request->user();
});
```
现在，只有携带有效 API 令牌的请求才能访问 /api/user 路由。
发送 API 请求:

在客户端，将 API 令牌添加到 Authorization 请求头中，格式为 Bearer {token}：
```
Authorization: Bearer your_api_token
```
例如，使用 JavaScript 的 fetch API：

知识画家
AI交互知识生成引擎，一句话生成知识视频、动画和应用

下载
```
fetch('/api/user', {
    headers: {
        'Authorization': 'Bearer your_api_token',
    },
})
.then(response => response.json())
.then(data => console.log(data));
```

Sanctum 如何处理多设备登录和令牌撤销？

Sanctum 允许用户在多个设备上生成多个令牌。每个令牌都与特定的用户和设备相关联。用户可以随时撤销某个令牌，例如，在“我的账户”页面上提供一个“注销所有设备”的选项。

撤销令牌可以通过以下方式实现：

// 撤销当前令牌
$request->user()->currentAccessToken()->delete();

// 撤销所有令牌
$request->user()->tokens()->delete();

// 撤销特定令牌
$token = $request->user()->tokens()->find($tokenId);
if ($token) {
    $token->delete();
}

Sanctum 与 Passport 的区别是什么？何时应该选择 Sanctum？

Sanctum 和 Passport 都是 Laravel 提供的 API 认证方案，但它们的应用场景不同。

Sanctum: 适用于单页面应用 (SPA)、移动应用和简单的 API 认证。它使用轻量级的 API 令牌，易于配置和使用。
Passport: 适用于需要 OAuth 2.0 授权的复杂 API 认证场景，例如第三方应用需要访问用户数据。它提供了更强大的功能，但也更复杂。

通常情况下，如果你的应用只需要简单的 API 认证，例如 SPA 或移动应用，那么 Sanctum 是一个更好的选择。如果你的应用需要 OAuth 2.0 授权，那么 Passport 更合适。

如何自定义 Sanctum 的令牌生成和验证过程？

Sanctum 提供了一些自定义选项，可以满足更高级的需求。

自定义令牌有效期:

可以在 config/sanctum.php 文件中设置令牌的有效期：
```
'expiration' => 60 * 24 * 30, // 30 天
```
自定义令牌生成逻辑:

可以重写 HasApiTokens trait 中的 createToken 方法，来实现自定义的令牌生成逻辑。例如，可以添加额外的元数据到令牌中。
自定义令牌验证逻辑:

可以创建自定义的中间件来验证令牌，并根据需要执行额外的检查。例如，可以检查令牌是否属于特定的设备或 IP 地址。