CakePHP4.1对接Xero API时Missing or incorrect CSRF cookie type错误排查修复

具体触发原因 #

• CakePHP 4.1的CSRF组件默认会校验Cookie的samesite属性和值类型，对接Xero OAuth流程时，Xero的回调跳转属于跨站请求场景，当浏览器的跨站Cookie策略拦截了CakePHP生成的CSRF Cookie时，就会触发该错误，并非单纯的Cookie过期问题
• 部分浏览器（尤其是Safari、移动端Chrome）对第三方Cookie的限制更严格，若用户开启了浏览器的「阻止所有第三方Cookie」设置，Xero回调跳转回你的站点时，原有登录页生成的CSRF Cookie会被判定为第三方Cookie被拦截，就会偶发报错
• 用户在关联Xero的过程中，中途打开同站点的其他标签页执行登出操作，或者后台刷新了会话密钥，导致原有标签页的CSRF Cookie和后端存储的会话不匹配，也会触发该错误
• 少数场景是用户的广告拦截、隐私防护类浏览器插件主动清除了站点的CSRF Cookie，导致提交请求时Cookie缺失

异常检测方法 #

• 在CakePHP的src/Error/ExceptionRenderer.php中重写render方法，捕获Cake\Http\Exception\InvalidCsrfTokenException异常，记录异常发生时的请求上下文：包括用户代理（UA）、请求来源地址、当前登录态、是否是Xero回调请求、Cookie携带情况，不要直接抛出异常给前端
• 给异常日志打上特定标记，统计异常发生的UA占比，确认是否集中在特定浏览器版本
• 在Xero关联的起始和回调节点埋点，记录用户跳转前的CSRF Cookie值和回调时携带的Cookie值，对比两者是否匹配、是否存在缺失

修复措施 #

• 调整CakePHP的CSRF Cookie配置，在config/app.php的Csrf配置段，将samesite设置为'None'同时开启Cookie的secure属性（必须全站HTTPS才能生效），适配跨站回调场景：

// config/app.php 示例配置
'Csrf' => [
    'cookie' => [
        'secure' => true,
        'samesite' => 'None',
        'httponly' => true,
    ]
]

• 针对Xero OAuth回调的路由单独关闭CSRF校验，Xero回调本身会携带OAuth state参数做合法性校验，不需要重复校验CSRF，在config/routes.php中给回调路由添加选项：

$routes->connect('/xero/callback', ['controller' => 'Xero', 'action' => 'callback'], ['csrfCheck' => false]);

• 延长CSRF Cookie的有效期，默认和会话有效期一致，可在CSRF配置中添加expiry参数设置为7天，避免短时间过期：

'Csrf' => [
    'expiry' => new \DateInterval('P7D'),
    // 其他配置同上
]

• 前端捕获CSRF错误后，给用户弹出自动重试提示，静默刷新一次CSRF Cookie后重新发起请求，不需要用户手动刷新页面

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