Skip to content

Latest commit

 

History

History
136 lines (102 loc) · 4.81 KB

csrf.md

File metadata and controls

136 lines (102 loc) · 4.81 KB
Raw
title
csrf

Summary

Description

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.

Attributes

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.

How To Enable

  1. Create the route and enable the plugin.
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.

  1. Using 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.

  1. In subsequent unsafe-methods requests to this route, you need to read the encrypted token from the cookie and append the token to the request header, setting the field name to the name in the plugin configuration.

Test Plugin

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

Disable Plugin

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.