The CSRF
plugin based on the Double Submit Cookie
way, protect your API from CSRF attacks. This plugin considers the GET
, HEAD
and OPTIONS
methods to be safe operations. Therefore calls to the GET
, HEAD
and OPTIONS
methods are not checked for interception.
In the following we define GET
, HEAD
and OPTIONS
as the safe-methods
and those other than these as unsafe-methods
.
Name | Type | Requirement | Default | Valid | Description |
---|---|---|---|---|---|
name | string | optional | apisix-csrf-token | The name of the token in the generated cookie. | |
expires | number | optional | 7200 | Expiration time(s) of csrf cookie. | |
key | string | required | The secret key used to encrypt the cookie. |
Note: When expires is set to 0 the plugin will ignore checking if the token is expired or not.
curl -i http://127.0.0.1:9080/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 } } }'
The route is then protected, and if you access it using methods other than GET
, you will see that the request was blocked and receive a 401 status code back.
GET
requests /hello
, a cookie with an encrypted token is received in the response. Token name is the name
field set in the plugin configuration, if not set, the default value is apisix-csrf-token
.Please note: We return a new cookie for each request.
request header
, setting the field name to the name
in the plugin configuration.Direct access to the ‘/hello’ route using a POST
method will return an error:
curl -i http://127.0.0.1:9080/hello -X POST HTTP/1.1 401 Unauthorized ... {"error_msg":"no csrf token in headers"}
When accessed with a GET request, the correct return and a cookie with an encrypted token are obtained:
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
The token needs to be read from the cookie and carried in the request header in subsequent unsafe-methods requests.
For example, use js-cookie read cookie and axios send request in client:
const token = Cookie.get('apisix-csrf-token'); const instance = axios.create({ headers: {'apisix-csrf-token': token} });
You also need to make sure that you carry the cookie.
Use curl send request:
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
Send a request to update the route to disable the plugin:
curl http://127.0.0.1:9080/apisix/admin/routes/1 -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d ' { "uri": "/hello", "upstream": { "type": "roundrobin", "nodes": { "127.0.0.1:1980": 1 } } }'
The CSRF plugin has been disabled.