CSRF跨站请求伪造攻击是指攻击者诱导已登录的用户访问恶意页面，利用用户的登录态发起非预期的请求，比如修改用户密码、转账等操作。Yii框架内置了成熟的CSRF防护机制，通过令牌验证的方式可以有效拦截这类恶意请求。
Yii框架CSRF防护的核心原理
Yii的CSRF防护基于令牌机制实现，核心逻辑分为三个步骤：首先服务端生成唯一的CSRF令牌，然后将令牌传递到前端页面，最后当前端发起POST、PUT、DELETE等非GET请求时，携带该令牌，服务端校验令牌的合法性，不合法的请求直接拒绝。
令牌的生成规则
Yii默认使用Yii::app()->request->csrfToken生成令牌，令牌是基于用户会话和随机字符串生成的，每个用户会话对应唯一的令牌，会话过期后令牌也会失效，避免令牌被长期盗用。
如何开启Yii框架的CSRF验证
Yii框架默认是开启CSRF验证的，如果需要手动配置，可以在配置文件protected/config/main.php中修改请求组件的配置：
<?php
return array(
'components' => array(
'request' => array(
// 开启CSRF验证，默认值为true
'enableCsrfValidation' => true,
// 自定义CSRF令牌名称，默认是YII_CSRF_TOKEN
'csrfTokenName' => 'custom_csrf_token',
),
),
);
前端传递CSRF令牌的两种方式
前端需要在提交非GET请求时携带CSRF令牌，常见的有两种传递方式：
- 通过表单隐藏字段传递，适用于普通表单提交
- 通过HTTP请求头传递，适用于Ajax异步请求
表单提交携带令牌示例
Yii的CHtml类会自动生成携带CSRF令牌的隐藏字段，不需要手动拼接：
<!-- 使用Yii的表单组件生成表单 -->
<?php $form = $this->beginWidget('CActiveForm'); ?>
<!-- 表单其他输入项 -->
<input type="text" name="username" />
<?php $this->endWidget(); ?>
上面的代码会自动生成类似下面的隐藏字段：
<input type="hidden" name="YII_CSRF_TOKEN" value="生成的令牌字符串" />
Ajax请求携带令牌示例
如果是使用jQuery发起Ajax请求，可以从页面的meta标签或者隐藏字段中获取令牌，添加到请求头中：
// 从meta标签获取CSRF令牌，Yii默认会在页面head中生成对应的meta标签
var csrfToken = $('meta[name="csrf-token"]').attr('content');
$.ajax({
url: '/site/submit',
type: 'POST',
data: {username: 'test'},
headers: {
// 将令牌添加到请求头，键名需要和后端配置一致
'X-CSRF-Token': csrfToken
},
success: function(res) {
console.log(res);
}
});
自定义CSRF验证逻辑
如果需要自定义CSRF验证的规则，比如部分接口不需要验证，可以重写CController的validateCsrfToken方法：
<?php
class BaseController extends CController {
protected function validateCsrfToken($event) {
// 排除不需要CSRF验证的接口
$excludeRoutes = array('site/api', 'site/callback');
$currentRoute = $this->getRoute();
if (in_array($currentRoute, $excludeRoutes)) {
return true;
}
// 调用父类的验证方法
return parent::validateCsrfToken($event);
}
}
常见CSRF验证失败问题排查
如果遇到CSRF验证失败的错误，可以从以下几个方面排查：
- 检查
enableCsrfValidation是否开启，配置是否生效 - 确认前端传递的令牌名称和服务端配置的
csrfTokenName一致 - 检查用户会话是否正常，令牌是基于会话生成的，会话失效会导致令牌校验失败
- 确认非GET请求都携带了正确的令牌，GET请求默认不需要CSRF验证
注意：CSRF防护只能拦截跨站伪造请求，无法防御XSS攻击，开发时还需要配合XSS过滤机制共同保障应用安全。
关闭CSRF验证的注意事项
不建议全局关闭CSRF验证，如果部分接口确实需要关闭，可以在对应的控制器中设置：
<?php
class SiteController extends CController {
public function init() {
parent::init();
// 仅当前控制器关闭CSRF验证，不影响其他控制器
$this->enableCsrfValidation = false;
}
}
如果只关闭单个动作的验证，可以在动作方法中临时修改配置，避免影响其他接口的安全性。