Laravel 11 Sanctum为何不再校验XSRF Cookie？相关疑问

问题描述 #

我在使用Laravel 11搭配Laravel Sanctum时，已按官方文档完成配置。首次通过Postman调用登录接口时返回419 CSRF token mismatch错误，添加预请求脚本获取XSRF-TOKEN后可正常请求。但清理Cookie并注释预请求代码后，仍能正常调用登录接口，无419错误。想了解该现象的原因，以及POST请求何时需在请求头中携带xsrf-cookie。

相关配置 #

1. .env配置 #

SESSION_DOMAIN=.mydomain.local:4433,localhost,localhost:3000,127.0.0.1,127.0.0.1:8000
SANCTUM_STATEFUL_DOMAINS=.mydomain.local:4433,localhost,localhost:3000,127.0.0.1,127.0.0.1:8000

2. config/sanctum.php配置 #

'guard' => ['api'],
'middleware' => [
        'authenticate_session' => Laravel\Sanctum\Http\Middleware\AuthenticateSession::class,
        'encrypt_cookies' => Illuminate\Cookie\Middleware\EncryptCookies::class,
        'validate_csrf_token' => Illuminate\Foundation\Http\Middleware\ValidateCsrfToken::class,
    ],

3. bootstrap/app.php配置 #

return Application::configure(basePath: dirname(__DIR__))
    ->withRouting(
        web: __DIR__.'/../routes/web.php',
        api: __DIR__.'/../routes/api.php',
        commands: __DIR__.'/../routes/console.php',
        health: '/up',
    )
    ->withMiddleware(function (Middleware $middleware) {
        $middleware->statefulApi();
        $middleware->appendToGroup('api',[
            \Laravel\Sanctum\Http\Middleware\EnsureFrontendRequestsAreStateful::class,
//            'throttle:api',
            \Illuminate\Routing\Middleware\SubstituteBindings::class,
        ]);

    })

4. routes/api.php配置 #

Route::prefix('auth')->group(function () {
    Route::post('login', [\App\Http\Controllers\AuthController::class, 'login']);
});

问题解答 #

一、清理Cookie后仍能正常请求的原因 #

• Postman自动会话关联：Postman会自动保存响应中的Cookie，即使手动清理，后续请求时，Laravel的EnsureFrontendRequestsAreStateful中间件会识别请求来自SANCTUM_STATEFUL_DOMAINS配置的可信域名，自动为请求创建会话并关联CSRF Token，无需手动携带。
• Sanctum的CSRF自动处理：对于登录这类核心认证接口，当请求来自可信有状态域名时，Sanctum会跳过强制要求请求头携带Token的校验，转而通过会话Cookie自动完成CSRF验证。
• 服务器会话残留：若服务器端的会话尚未过期，清理客户端Cookie后再次请求，Laravel可能通过其他标识（如IP）临时关联会话，不过这种情况概率较低。

二、POST请求需要携带xsrf-cookie头的场景 #

• 跨域无状态请求：前后端不在同一域名，且不依赖会话Cookie时，需先发送带xsrf-cookie头的GET请求获取XSRF-TOKEN，再在POST请求中携带该Token。
• 前端未自动处理Token注入：如果前端框架未自动将XSRF-TOKEN Cookie的值注入到X-XSRF-TOKEN请求头，需手动用xsrf-cookie头触发Token获取流程。
• 非浏览器工具首次请求：Postman、curl这类工具首次请求时无会话Cookie，也不会自动处理CSRF逻辑，需先通过xsrf-cookie头获取Token，或添加预请求脚本。
• 请求未被识别为有状态：若请求域名不在SANCTUM_STATEFUL_DOMAINS中，Laravel将其视为无状态请求，必须携带CSRF Token，此时需先通过xsrf-cookie获取。

内容的提问来源于stack exchange，提问作者Dang Hung