hf400159 commented on code in PR #7519: URL: https://github.com/apache/apisix/pull/7519#discussion_r931735277
########## docs/zh/latest/plugins/csrf.md: ########## @@ -23,23 +30,21 @@ title: csrf ## 描述 -`CSRF` 插件基于 [`Double Submit Cookie`](https://en.wikipedia.org/wiki/Cross-site_request_forgery#Double_Submit_Cookie) 的方式，保护您的 API 免于 CSRF 攻击。本插件认为 `GET`、`HEAD` 和 `OPTIONS` 方法是安全操作。因此 `GET`、`HEAD` 和 `OPTIONS` 方法的调用不会被检查拦截。 +`csrf` 插件基于 [`Double Submit Cookie`](https://en.wikipedia.org/wiki/Cross-site_request_forgery#Double_Submit_Cookie) 的方式，保护用户的 API 免于 CSRF 攻击。 -在这里我们定义 `GET`, `HEAD` 和 `OPTIONS` 为 `safe-methods`，其他的请求方法为 `unsafe-methods`。 +在此插件运行时，`GET`、`HEAD` 和 `OPTIONS` 会被定义为 `safe-methods`，其他的请求方法则定义为 `unsafe-methods`。因此 `GET`、`HEAD` 和 `OPTIONS` 方法的调用不会被检查拦截。 ## 属性 -| Name | Type | Requirement | Default | Valid | Description | +| 名称 | 类型 | 必选项 | 默认值 | 有效值 | 描述 | | ---------------- | ------- | ----------- | ------- | ----- |---------------------| -| name | string | optional | `apisix-csrf-token` | | 生成的 Cookie 中的 token 的名字，需要使用这个名字在请求头携带 Cookie 中的内容 | -| expires | number | optional | `7200` | | CSRF Cookie 的过期时间（秒）| -| key | string | required | | | 加密 token 的秘钥 | - -**注意：当 expires 设置为 0 时插件将忽略检查 Token 是否过期** +| name | string | 否 | `apisix-csrf-token` | | 生成的 Cookie 中的 Token 名称，需要使用此名称在请求头携带 Cookie 中的内容。 | +| expires | number | 否 | `7200` | | CSRF Cookie 的过期时间，单位为秒。当设置为 `0` 时，会忽略 CSRF Cookie 过期时间检查。| +| key | string | 是 | | | 加密 Token 的秘钥。 | Review Comment: ```suggestion | key | string | 是 | | | 加密 Token 的密钥。 | ``` ########## docs/zh/latest/plugins/csrf.md: ########## @@ -100,19 +114,19 @@ const instance = axios.create({ }); ``` -你还需要确保你的请求携带了 Cookie。 - -使用 curl 发送请求： +使用 `curl` 命令发送请求，确保请求中携带了 Cookie 信息，返回 `200` HTTP 状态码则表示请求成功： ```shell curl -i http://127.0.0.1:9080/hello -X POST -H 'apisix-csrf-token: eyJyYW5kb20iOjAuNjg4OTcyMzA4ODM1NDMsImV4cGlyZXMiOjcyMDAsInNpZ24iOiJcL09uZEF4WUZDZGYwSnBiNDlKREtnbzVoYkJjbzhkS0JRZXVDQm44MG9ldz0ifQ==' -b 'apisix-csrf-token=eyJyYW5kb20iOjAuNjg4OTcyMzA4ODM1NDMsImV4cGlyZXMiOjcyMDAsInNpZ24iOiJcL09uZEF4WUZDZGYwSnBiNDlKREtnbzVoYkJjbzhkS0JRZXVDQm44MG9ldz0ifQ==' +``` +```shell HTTP/1.1 200 OK ``` ## 禁用插件 -发送一个更新路由的请求，以停用该插件： +当你需要禁用 `csrf` 插件时，可以通过以下命令删除相应的 JSON 配置，APISIX 将会自动重新加载相关配置，无需重启服务： Review Comment: ```suggestion 当你需要禁用该插件时，可以通过以下命令删除相应的 JSON 配置，APISIX 将会自动重新加载相关配置，无需重启服务： ``` ########## docs/zh/latest/plugins/csrf.md: ########## @@ -100,19 +114,19 @@ const instance = axios.create({ }); ``` -你还需要确保你的请求携带了 Cookie。 - -使用 curl 发送请求： +使用 `curl` 命令发送请求，确保请求中携带了 Cookie 信息，返回 `200` HTTP 状态码则表示请求成功： Review Comment: ```suggestion 使用 `curl` 命令发送请求，确保请求中携带了 Cookie 信息。如果返回 `200` HTTP 状态码则表示请求成功： ``` ########## docs/zh/latest/plugins/csrf.md: ########## @@ -59,38 +64,47 @@ curl -i http://127.0.0.1:9080/apisix/admin/routes/1 -H 'X-API-KEY: edd1c9f034335 }' ``` -这条路由已经开启保护，当你使用 GET 之外的方法访问，请求会被拦截并返回 401 状态码。 +当你使用 `GET` 之外的方法访问被保护的路由时，请求会被拦截并返回 `401` HTTP 状态码。 + +使用 `GET` 请求 `/hello` 时，在响应中会有一个携带了加密 Token 的 Cookie。Token 字段名称为插件配置中的 `name` 值，默认为 `apisix-csrf-token`。 + +:::note -2. 使用 `GET` 请求 `/hello`，在响应中会有一个携带了加密 `token` 的 `Cookie`。Token 字段的名字为插件配置中的 `name` 值，如果没有配置该值，那么默认值为 `apisix-csrf-token`。 +每一个请求都会返回一个新的 Cookie。 -注意：每一个请求都会返回一个新的 Cookie。 +::: -3. 在后续的对该路由的 `unsafe-methods` 请求中，需要从 Cookie 中读取加密的 token，保证携带 Cookie 并在请求头部中携带该 token，请求头字段的名称为插件配置中的 `name`。 +在后续对该路由进行的 `unsafe-methods` 请求中，需要从 Cookie 中读取加密的 Token，并在请求头中携带该 Token。请求头字段的名称为插件属性中的 `name`。 ## 测试插件 -直接对该路由发起 `POST` 请求会返回错误： +启用插件后，使用 `curl` 命令尝试直接对该路由发起 `POST` 请求，会返回 `Unauthorized` 字样的报错提示： ```shell curl -i http://127.0.0.1:9080/hello -X POST +``` +```shell HTTP/1.1 401 Unauthorized ... {"error_msg":"no csrf token in headers"} ``` -当使用 GET 请求，返回中会有携带 token 的 Cookie： +当发起 `GET` 请求时，返回中会有携带 Token 的 Cookie： Review Comment: ```suggestion 当发起 `GET` 请求时，返回结果中会有携带 Token 的 Cookie： ``` ########## docs/zh/latest/plugins/csrf.md: ########## @@ -59,38 +64,47 @@ curl -i http://127.0.0.1:9080/apisix/admin/routes/1 -H 'X-API-KEY: edd1c9f034335 }' ``` -这条路由已经开启保护，当你使用 GET 之外的方法访问，请求会被拦截并返回 401 状态码。 +当你使用 `GET` 之外的方法访问被保护的路由时，请求会被拦截并返回 `401` HTTP 状态码。 + +使用 `GET` 请求 `/hello` 时，在响应中会有一个携带了加密 Token 的 Cookie。Token 字段名称为插件配置中的 `name` 值，默认为 `apisix-csrf-token`。 + +:::note -2. 使用 `GET` 请求 `/hello`，在响应中会有一个携带了加密 `token` 的 `Cookie`。Token 字段的名字为插件配置中的 `name` 值，如果没有配置该值，那么默认值为 `apisix-csrf-token`。 +每一个请求都会返回一个新的 Cookie。 -注意：每一个请求都会返回一个新的 Cookie。 +::: -3. 在后续的对该路由的 `unsafe-methods` 请求中，需要从 Cookie 中读取加密的 token，保证携带 Cookie 并在请求头部中携带该 token，请求头字段的名称为插件配置中的 `name`。 +在后续对该路由进行的 `unsafe-methods` 请求中，需要从 Cookie 中读取加密的 Token，并在请求头中携带该 Token。请求头字段的名称为插件属性中的 `name`。 ## 测试插件 -直接对该路由发起 `POST` 请求会返回错误： +启用插件后，使用 `curl` 命令尝试直接对该路由发起 `POST` 请求，会返回 `Unauthorized` 字样的报错提示： ```shell curl -i http://127.0.0.1:9080/hello -X POST +``` +```shell HTTP/1.1 401 Unauthorized ... {"error_msg":"no csrf token in headers"} ``` -当使用 GET 请求，返回中会有携带 token 的 Cookie： +当发起 `GET` 请求时，返回中会有携带 Token 的 Cookie： ```shell 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` 请求中的请求头中携带。 +在请求之前，用户需要从 Cookie 中读取 Token，并在后续的 `unsafe-methods` 请求的请求头中携带。 -例如，在客户端使用 [js-cookie](https://github.com/js-cookie/js-cookie) 读取 Cookie，使用 [axios](https://github.com/axios/axios) 发送请求。 +例如，在客户端使用 [js-cookie](https://github.com/js-cookie/js-cookie) 读取 Cookie，使用 [axios](https://github.com/axios/axios) 发送请求： Review Comment: ```suggestion 例如，你可以在客户端使用 [js-cookie](https://github.com/js-cookie/js-cookie) 读取 Cookie，使用 [axios](https://github.com/axios/axios) 发送请求： ``` -- This is an automated message from the Apache Git Service. To respond to the message, please log on to GitHub and use the URL above to go to the specific comment. To unsubscribe, e-mail: [email protected] For queries about this service, please contact Infrastructure at: [email protected]
