csrf
#
描述csrf
插件基于 Double Submit Cookie
的方式,保护用户的 API 免于 CSRF 攻击。
在此插件运行时,GET
、HEAD
和 OPTIONS
会被定义为 safe-methods
,其他的请求方法则定义为 unsafe-methods
。因此 GET
、HEAD
和 OPTIONS
方法的调用不会被检查拦截。
#
属性名称 | 类型 | 必选项 | 默认值 | 有效值 | 描述 |
---|---|---|---|---|---|
name | string | 否 | apisix-csrf-token | 生成的 Cookie 中的 Token 名称,需要使用此名称在请求头携带 Cookie 中的内容。 | |
expires | number | 否 | 7200 | CSRF Cookie 的过期时间,单位为秒。当设置为 0 时,会忽略 CSRF Cookie 过期时间检查。 | |
key | string | 是 | 加密 Token 的密钥。 |
注意:schema 中还定义了 encrypt_fields = {"key"}
,这意味着该字段将会被加密存储在 etcd 中。具体参考 加密存储字段。
#
启用插件以下示例展示了如何在指定路由上启用并配置 csrf
插件:
curl -i http://127.0.0.1:9180/apisix/admin/routes/1 -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
{
"uri": "/hello",
"plugins": {
"csrf": {
"key": "edd1c9f034335f136f87ad84b625c8f1"
}
},
"upstream": {
"type": "roundrobin",
"nodes": {
"127.0.0.1:9001": 1
}
}
}'
当你使用 GET
之外的方法访问被保护的路由时,请求会被拦截并返回 401
HTTP 状态码。
使用 GET
请求 /hello
时,在响应中会有一个携带了加密 Token 的 Cookie。Token 字段名称为插件配置中的 name
值,默认为 apisix-csrf-token
。
note
每一个请求都会返回一个新的 Cookie。
在后续对该路由进行的 unsafe-methods
请求中,需要从 Cookie 中读取加密的 Token,并在请求头中携带该 Token。请求头字段的名称为插件属性中的 name
。
#
测试插件启用插件后,使用 curl
命令尝试直接对该路由发起 POST
请求,会返回 Unauthorized
字样的报错提示:
curl -i http://127.0.0.1:9080/hello -X POST
HTTP/1.1 401 Unauthorized
...
{"error_msg":"no csrf token in headers"}
当发起 GET
请求时,返回结果中会有携带 Token 的 Cookie:
curl -i http://127.0.0.1:9080/hello
HTTP/1.1 200 OK
...
Set-Cookie: apisix-csrf-token=eyJyYW5kb20iOjAuNjg4OTcyMzA4ODM1NDMsImV4cGlyZXMiOjcyMDAsInNpZ24iOiJcL09uZEF4WUZDZGYwSnBiNDlKREtnbzVoYkJjbzhkS0JRZXVDQm44MG9ldz0ifQ==;path=/;Expires=Mon, 13-Dec-21 09:33:55 GMT
在请求之前,用户需要从 Cookie 中读取 Token,并在后续的 unsafe-methods
请求的请求头中携带。
例如,你可以在客户端使用 js-cookie 读取 Cookie,使用 axios 发送请求:
const token = Cookie.get('apisix-csrf-token');
const instance = axios.create({
headers: {'apisix-csrf-token': token}
});
使用 curl
命令发送请求,确保请求中携带了 Cookie 信息,如果返回 200
HTTP 状态码则表示请求成功:
curl -i http://127.0.0.1:9080/hello -X POST -H 'apisix-csrf-token: eyJyYW5kb20iOjAuNjg4OTcyMzA4ODM1NDMsImV4cGlyZXMiOjcyMDAsInNpZ24iOiJcL09uZEF4WUZDZGYwSnBiNDlKREtnbzVoYkJjbzhkS0JRZXVDQm44MG9ldz0ifQ==' -b 'apisix-csrf-token=eyJyYW5kb20iOjAuNjg4OTcyMzA4ODM1NDMsImV4cGlyZXMiOjcyMDAsInNpZ24iOiJcL09uZEF4WUZDZGYwSnBiNDlKREtnbzVoYkJjbzhkS0JRZXVDQm44MG9ldz0ifQ=='
HTTP/1.1 200 OK
#
禁用插件当你需要禁用该插件时,可以通过以下命令删除相应的 JSON 配置,APISIX 将会自动重新加载相关配置,无需重启服务:
curl http://127.0.0.1:9180/apisix/admin/routes/1 -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
{
"uri": "/hello",
"upstream": {
"type": "roundrobin",
"nodes": {
"127.0.0.1:1980": 1
}
}
}'