CakePHP升级后CSRF令牌异常：如何让Webhook请求正常通行？

问题背景 #

从CakePHP 3.10升级至4.3并启用CSRF后，出现 Cake\Http\Exception\InvalidCsrfTokenException Missing or incorrect CSRF cookie type. 错误，清理客户端Cookie可临时解决，但核心流量来自Webhook，需无需清理Cookie即可让Webhook正常通行的方案。

当前Application.php中的中间件配置：

public function middleware($middlewareQueue): \Cake\Http\MiddlewareQueue
{
    $middlewareQueue
        ->add(new ErrorHandlerMiddleware(Configure::read('Error')))
        ->add(new AssetMiddleware([
            'cacheTime' => Configure::read('Asset.cacheTime'),
        ]))
        ->add(new RoutingMiddleware($this, '_cake_routes_'))
        ->add(new BodyParserMiddleware())
        ->add(new CsrfProtectionMiddleware([
            'httponly' => false,
        ]));

    return $middlewareQueue;
}

解决方案 #

1. 给Webhook路由跳过CSRF验证（推荐） #

Webhook属于服务端对服务端的请求，不存在浏览器端的跨站风险，完全可以跳过CSRF验证，这是最直接且安全的方案。

方式一：通过CSRF中间件的skipCallback配置

修改CsrfProtectionMiddleware的参数，添加路由判断逻辑：

->add(new CsrfProtectionMiddleware([
    'httponly' => false,
    'skipCallback' => function ($request) {
        // 匹配你的Webhook路由前缀，比如所有/webhooks/开头的请求
        return str_starts_with($request->getPath(), '/webhooks/');
        // 也可以精准匹配特定路由，比如：
        // return in_array($request->getPath(), ['/webhooks/github', '/webhooks/stripe']);
    },
]));

方式二：在路由配置中标记跳过CSRF

在config/routes.php中给Webhook路由添加_skipCsrf标识：

$routes->scope('/webhooks', function (RouteBuilder $builder) {
    // 给该路由下的所有请求跳过CSRF验证
    $builder->connect('/{service}/{action}', [], ['_skipCsrf' => true]);
    // 或者单个路由配置
    $builder->connect('/github/push', ['controller' => 'Webhooks', 'action' => 'githubPush'], ['_skipCsrf' => true]);
});

2. 兼容旧CSRF Cookie（针对需要保留浏览器会话的场景） #

如果错误是因为升级后CakePHP的CSRF Cookie格式/名称变化导致旧Cookie不兼容，可以添加自定义中间件，在CSRF验证前清理旧Cookie，避免触发错误：

在Application.php的middleware方法中，在CsrfProtectionMiddleware之前添加自定义中间件：

// 先添加自定义中间件处理旧CSRF Cookie
$middlewareQueue->add(function (ServerRequestInterface $request, RequestHandlerInterface $handler) {
    $cookies = $request->getCookieParams();
    // 假设旧版本的CSRF Cookie名称是csrfToken，新版本是默认的csrfToken_<hash>
    // 检测到旧Cookie存在时，直接设置过期清除
    if (isset($cookies['csrfToken'])) {
        $response = $handler->handle($request);
        return $response->withCookie(\Cake\Http\Cookie\Cookie::create('csrfToken', '', [
            'expires' => new \DateTime('-1 day'),
            'path' => '/',
            'domain' => Configure::read('App.domain'),
            'secure' => Configure::read('App.secure'),
        ]));
    }
    return $handler->handle($request);
});

// 再添加CSRF中间件
$middlewareQueue->add(new CsrfProtectionMiddleware([
    'httponly' => false,
]));

说明 #

• 优先选择方案1，因为Webhook本身不需要CSRF保护，跳过验证不会引入安全风险。
• 方案2适用于需要兼容旧浏览器会话的场景，避免用户手动清理Cookie。

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