You are viewing a plain text version of this content. The canonical link for it is here.
Posted to notifications@apisix.apache.org by sp...@apache.org on 2022/04/28 03:57:51 UTC
[apisix] branch master updated: docs: update "Security" docs (#6911)
This is an automated email from the ASF dual-hosted git repository.
spacewander pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/apisix.git
The following commit(s) were added to refs/heads/master by this push:
new 0c8267341 docs: update "Security" docs (#6911)
0c8267341 is described below
commit 0c8267341415e63e10b2bf1b61775f526c42a73d
Author: Navendu Pottekkat <na...@gmail.com>
AuthorDate: Thu Apr 28 09:27:46 2022 +0530
docs: update "Security" docs (#6911)
---
docs/en/latest/plugins/consumer-restriction.md | 109 +++++++++++++++----------
docs/en/latest/plugins/csrf.md | 62 ++++++++------
docs/en/latest/plugins/public-api.md | 91 +++++++++++++--------
docs/en/latest/plugins/referer-restriction.md | 63 ++++++++------
4 files changed, 198 insertions(+), 127 deletions(-)
diff --git a/docs/en/latest/plugins/consumer-restriction.md b/docs/en/latest/plugins/consumer-restriction.md
index a8ca55c9e..e2c5dd066 100644
--- a/docs/en/latest/plugins/consumer-restriction.md
+++ b/docs/en/latest/plugins/consumer-restriction.md
@@ -1,5 +1,11 @@
---
title: consumer-restriction
+keywords:
+ - APISIX
+ - Plugin
+ - Consumer restriction
+ - consumer-restriction
+description: This document contains information about the Apache APISIX consumer-restriction Plugin.
---
<!--
@@ -23,29 +29,36 @@ title: consumer-restriction
## Description
-The `consumer-restriction` makes corresponding access restrictions based on different objects selected.
+The `consumer-restriction` Plugin allows users to set access restrictions based on Consumer, Route, or Service.
## Attributes
-|Name | Type | Requirement | Default | Valid | Description |
-|-----------|-------------|--------------|---------------|---------------------------------|-------------------------------------------------------------------------------------------------------------------- |
-| type | string | optional | consumer_name | ["consumer_name", "service_id", "route_id"] | According to different objects, corresponding restrictions, support `consumer_name`, `service_id`, `route_id`. |
-| whitelist | array[string] | required | | | Grant full access to all users specified in the provided list , **has the priority over `allowed_by_methods`** |
-| blacklist | array[string] | required | | | Reject connection to all users specified in the provided list , **has the priority over `whitelist`** |
-| rejected_code | integer | optional | 403 | [200,...] | The HTTP status code returned when the request is rejected. |
-| rejected_msg | string | optional | | | The message returned when the request is rejected. |
-| allowed_by_methods | array[object] | optional | | | Set a list of allowed HTTP methods for the selected user , HTTP methods can be `["GET", "POST", "PUT", "DELETE", "PATCH", "HEAD", "OPTIONS", "CONNECT", "TRACE", "PURGE"]` |
+| Name | Type | Required | Default | Valid values | Description |
+|--------------------|---------------|----------|---------------|-------------------------------------------------------------------------------------------|--------------------------------------------------------------------------------|
+| type | string | False | consumer_name | ["consumer_name", "service_id", "route_id"] | Type of object to base the restriction on. |
+| whitelist | array[string] | True | | | List of objects to whitelist. Has a higher priority than `allowed_by_methods`. |
+| blacklist | array[string] | True | | | List of objects to blacklist. Has a higher priority than `whitelist`. |
+| rejected_code | integer | False | 403 | [200,...] | HTTP status code returned when the request is rejected. |
+| rejected_msg | string | False | | | Message returned when the request is rejected. |
+| allowed_by_methods | array[object] | False | | ["GET", "POST", "PUT", "DELETE", "PATCH", "HEAD", "OPTIONS", "CONNECT", "TRACE", "PURGE"] | List of allowed HTTP methods for a Consumer. |
-For the `type` field is an enumerated type, it can be `consumer_name` or `service_id`. They stand for the following meanings:
+:::note
-* **consumer_name**: Add the `username` of `consumer` to a whitelist or blacklist (supporting single or multiple consumers) to restrict access to services or routes.
-* **service_id**: Add the `id` of the `service` to a whitelist or blacklist (supporting one or more services) to restrict access to the service. It needs to be used in conjunction with authorized plugins.
+The different values in the `type` attribute have these meanings:
-## Example
+- `consumer_name`: Username of the Consumer to restrict access to a Route or a Service.
+- `service_id`: ID of the Service to restrict access from a Consumer. Need to be used with an Authentication Plugin.
+- `route_id`: ID of the Route to restrict access from a Consumer.
-### How to restrict `consumer_name`
+:::
-The following is an example. The `consumer-restriction` plugin is enabled on the specified route to restrict consumer access.
+## Example usage
+
+### Restricting by `consumer_name`
+
+The example below shows how you can use the `consumer-restriction` Plugin on a Route to restrict specific consumers.
+
+You can first create two consumers `jack1` and `jack2`:
```shell
curl http://127.0.0.1:9080/apisix/admin/consumers -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -i -d '
@@ -69,7 +82,11 @@ curl http://127.0.0.1:9080/apisix/admin/consumers -H 'X-API-KEY: edd1c9f034335f1
}
}
}'
+```
+Next, you can configure the Plugin to the Route:
+
+```shell
curl http://127.0.0.1:9080/apisix/admin/routes/1 -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
{
"uri": "/index.html",
@@ -90,28 +107,32 @@ curl http://127.0.0.1:9080/apisix/admin/routes/1 -H 'X-API-KEY: edd1c9f034335f13
}'
```
-**Test Plugin**
-
-Requests from jack1:
+Now, this configuration will only allow `jack1` to access your Route:
```shell
curl -u jack2019:123456 http://127.0.0.1:9080/index.html
+```
+
+```shell
HTTP/1.1 200 OK
...
```
-Requests from jack2:
+And requests from `jack2` are blocked:
```shell
curl -u jack2020:123456 http://127.0.0.1:9080/index.html -i
+```
+
+```shell
HTTP/1.1 403 Forbidden
...
{"message":"The consumer_name is forbidden."}
```
-### How to restrict `allowed_by_methods`
+### Restricting by `allowed_by_methods`
-This example restrict the user `jack1` to only `POST` on the resource
+The example below configures the Plugin to a Route to restrict `jack1` to only make `POST` requests:
```shell
curl http://127.0.0.1:9080/apisix/admin/routes/1 -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
@@ -135,18 +156,19 @@ curl http://127.0.0.1:9080/apisix/admin/routes/1 -H 'X-API-KEY: edd1c9f034335f13
}'
```
-**Test Plugin**
-
-Requests from jack1:
+Now if `jack1` makes a `GET` request, the access is restricted:
```shell
curl -u jack2019:123456 http://127.0.0.1:9080/index.html
+```
+
+```shell
HTTP/1.1 403 Forbidden
...
{"message":"The consumer_name is forbidden."}
```
-Add the capability for `jack1` to get the resource
+To also allow `GET` requests, you can update the Plugin configuration and it would be reloaded automatically:
```shell
curl http://127.0.0.1:9080/apisix/admin/routes/1 -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
@@ -170,18 +192,21 @@ curl http://127.0.0.1:9080/apisix/admin/routes/1 -H 'X-API-KEY: edd1c9f034335f13
}'
```
-Requests from jack1:
+Now, if a `GET` request is made:
```shell
curl -u jack2019:123456 http://127.0.0.1:9080/index.html
+```
+
+```shell
HTTP/1.1 200 OK
```
-### How to restrict `service_id`
+### Restricting by `service_id`
-The `service_id` method needs to be used together with the authorization plug-in. Here, the key-auth authorization plug-in is taken as an example.
+To restrict a Consumer from accessing a Service, you also need to use an Authentication Plugin. The example below uses the [key-auth](./key-auth.md) Plugin.
-1. Create two services.
+First, you can create two services:
```shell
curl http://127.0.0.1:9080/apisix/admin/services/1 -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
@@ -207,7 +232,7 @@ curl http://127.0.0.1:9080/apisix/admin/services/2 -H 'X-API-KEY: edd1c9f034335f
}'
```
-2. Bind the `consumer-restriction` plugin on the `consumer` (need to cooperate with an authorized plugin to bind), and add the `service_id` whitelist list.
+Then configure the `consumer-restriction` Plugin on the Consumer with the `key-auth` Plugin and the `service_id` to whitelist.
```shell
curl http://127.0.0.1:9080/apisix/admin/consumers -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
@@ -228,7 +253,7 @@ curl http://127.0.0.1:9080/apisix/admin/consumers -H 'X-API-KEY: edd1c9f034335f1
}'
```
-3. Open the `key-auth` plugin on the route and bind the `service_id` to `1`.
+Finally, you can configure the `key-auth` Plugin and bind the service to the Route:
```shell
curl http://127.0.0.1:9080/apisix/admin/routes/1 -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
@@ -248,17 +273,18 @@ curl http://127.0.0.1:9080/apisix/admin/routes/1 -H 'X-API-KEY: edd1c9f034335f13
}'
```
-**Test Plugin**
+Now, if you test the Route, you should be able to access the Service:
```shell
curl http://127.0.0.1:9080/index.html -H 'apikey: auth-jack' -i
+```
+
+```shell
HTTP/1.1 200 OK
...
```
-The `service_id` in the whitelist column allows access, and the plug-in configuration takes effect.
-
-4. Open the `key-auth` plugin on the route and bind the `service_id` to `2`.
+Now, if the Route is configured to the Service with `service_id` `2`:
```shell
curl http://127.0.0.1:9080/apisix/admin/routes/1 -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
@@ -278,22 +304,21 @@ curl http://127.0.0.1:9080/apisix/admin/routes/1 -H 'X-API-KEY: edd1c9f034335f13
}'
```
-**Test Plugin**
+Since the Service is not in the whitelist, it cannot be accessed:
```shell
curl http://127.0.0.1:9080/index.html -H 'apikey: auth-jack' -i
+```
+
+```shell
HTTP/1.1 403 Forbidden
...
{"message":"The service_id is forbidden."}
```
-It means that the `service_id` that is not in the whitelist is denied access, and the plug-in configuration takes effect.
-
## Disable Plugin
-When you want to disable the `consumer-restriction` plugin, it is very simple,
-you can delete the corresponding json configuration in the plugin configuration,
-no need to restart the service, it will take effect immediately:
+To disable the `consumer-restriction` Plugin, you can delete the corresponding JSON configuration from the Plugin configuration. APISIX will automatically reload and you do not have to restart for this to take effect.
```shell
curl http://127.0.0.1:9080/apisix/admin/routes/1 -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
@@ -310,5 +335,3 @@ curl http://127.0.0.1:9080/apisix/admin/routes/1 -H 'X-API-KEY: edd1c9f034335f13
}
}'
```
-
-The `consumer-restriction` plugin has been disabled now. It works for other plugins.
diff --git a/docs/en/latest/plugins/csrf.md b/docs/en/latest/plugins/csrf.md
index 5300d6e74..3285f5121 100644
--- a/docs/en/latest/plugins/csrf.md
+++ b/docs/en/latest/plugins/csrf.md
@@ -1,5 +1,11 @@
---
title: csrf
+keywords:
+ - APISIX
+ - Plugin
+ - Cross-site request forgery
+ - csrf
+description: This document contains information about the Apache APISIX csrf Plugin.
---
<!--
@@ -23,23 +29,21 @@ title: csrf
## Description
-The `CSRF` plugin based on the [`Double Submit Cookie`](https://en.wikipedia.org/wiki/Cross-site_request_forgery#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.
+The `csrf` Plugin can be used to protect your API against [CSRF attacks](https://en.wikipedia.org/wiki/Cross-site_request_forgery) using the [Double Submit Cookie](https://en.wikipedia.org/wiki/Cross-site_request_forgery#Double_Submit_Cookie) method.
-In the following we define `GET`, `HEAD` and `OPTIONS` as the `safe-methods` and those other than these as `unsafe-methods`.
+This Plugin considers the `GET`, `HEAD` and `OPTIONS` methods to be safe operations (`safe-methods`) and such requests are not checked for interception by an attacker. Other methods are termed 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. |
+| Name | Type | Required | Default | Description |
+|---------|--------|----------|---------------------|---------------------------------------------------------------------------------------------|
+| name | string | False | `apisix-csrf-token` | Name of the token in the generated cookie. |
+| expires | number | False | `7200` | Expiration time in seconds of the CSRF cookie. Set to `0` to skip checking expiration time. |
+| key | string | True | | 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.**
+## Enabling the Plugin
-## How To Enable
-
-1. Create the route and enable the plugin.
+The example below shows how you can enable the Plugin on a specific Route:
```shell
curl -i http://127.0.0.1:9080/apisix/admin/routes/1 -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT-d '
@@ -59,38 +63,46 @@ curl -i http://127.0.0.1:9080/apisix/admin/routes/1 -H 'X-API-KEY: edd1c9f034335
}'
```
-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.
+The Route is now protected and trying to access it with methods other than `GET` will be blocked with a 401 status code.
+
+Sending a `GET` request to the `/hello` endpoint will send back a cookie with an encrypted token. The name of the token can be set through the `name` attribute of the Plugin configuration and if unset, it defaults to `apisix-csrf-token`.
+
+:::note
-2. 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`.
+A new cookie is returned for each request.
-Please note: We return a new cookie for each request.
+:::
-3. 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.
+For subsequent requests with `unsafe-methods`, you need to read the encrypted token from the cookie and append the token to the request header by setting the field name to the `name` attribute in the Plugin configuration.
-## Test Plugin
+## Example usage
-Direct access to the '/hello' route using a `POST` method will return an error:
+After you have configured the Plugin as shown above, trying to directly make a `POST` request to the `/hello` Route will result in an error:
```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"}
```
-When accessed with a GET request, the correct return and a cookie with an encrypted token are obtained:
+To get the cookie with the encrypted token, you can make a `GET` request:
```shell
curl -i http://127.0.0.1:9080/hello
+```
+```shell
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.
+This token must then be read from the cookie and added to the request header for subsequent `unsafe-methods` requests.
-For example, use [js-cookie](https://github.com/js-cookie/js-cookie) read cookie and [axios](https://github.com/axios/axios) send request in client:
+For example, you can use [js-cookie](https://github.com/js-cookie/js-cookie) to read the cookie and [axios](https://github.com/axios/axios) to send requests:
```js
const token = Cookie.get('apisix-csrf-token');
@@ -100,19 +112,21 @@ const instance = axios.create({
});
```
-You also need to make sure that you carry the cookie.
+Also make sure that you carry the cookie.
-Use curl send request:
+You can also use curl to send the request:
```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
```
## Disable Plugin
-Send a request to update the route to disable the plugin:
+To disable the `csrf` Plugin, you can delete the corresponding JSON configuration from the Plugin configuration. APISIX will automatically reload and you do not have to restart for this to take effect.
```shell
curl http://127.0.0.1:9080/apisix/admin/routes/1 -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
@@ -126,5 +140,3 @@ curl http://127.0.0.1:9080/apisix/admin/routes/1 -H 'X-API-KEY: edd1c9f034335f13
}
}'
```
-
-The CSRF plugin has been disabled.
diff --git a/docs/en/latest/plugins/public-api.md b/docs/en/latest/plugins/public-api.md
index cc80f3469..b0d438166 100644
--- a/docs/en/latest/plugins/public-api.md
+++ b/docs/en/latest/plugins/public-api.md
@@ -1,5 +1,11 @@
---
title: public-api
+keywords:
+ - APISIX
+ - Plugin
+ - Public API
+ - public-api
+description: This document contains information about the Apache APISIX public-api Plugin.
---
<!--
@@ -23,31 +29,28 @@ title: public-api
## Description
-The `public-api` plugin is used to enhance the plugin public API access control.
-When current users develop custom plugins, they can register some public APIs for fixed functionality, such as the `/apisix/plugin/jwt/sign` API in `jwt-auth`. These APIs can only apply limited plugins for access control (currently only `ip-restriction`) by way of plugin interceptors.
+The `public-api` is used for exposing an API endpoint through a general HTTP API router.
-With the `public-api` plugin, we put all public APIs into the general HTTP API router, which is consistent with the normal Route registered by the user and can apply any plugin. The public API added in the user plugin is no longer expose by default by APISIX, and the user has to manually configure the Route for it, the user can configure any uri and plugin.
+When you are using custom Plugins, you can use the `public-api` Plugin to define a fixed, public API for a particular functionality. For example, you can create a public API endpoint `/apisix/plugin/jwt/sign` for JWT authentication using the [jwt-auth](./jwt-auth.md) Plugin.
-## Attributes
-
-| Name | Type | Requirement | Default | Valid | Description |
-| -- | -- | -- | -- | -- | -- |
-| uri | string | optional | "" | | The uri of the public API. When you set up the route, you can use this to configure the original API uri if it is used in a way that is inconsistent with the original public API uri. |
+The public API added in a custom Plugin is not exposed by default and the user should manually configure a Route and enable the `public-api` Plugin on it.
-## Example
+## Attributes
-We take the `jwt-auth` token sign API as an example to show how to configure the `public-api` plugin. Also, the `key-auth` will be used to show how to configure the protection plugin for the public API.
+| Name | Type | Required | Default | Description |
+|------|--------|----------|---------|--------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| uri | string | False | "" | URI of the public API. When setting up a Route, use this attribute to configure the original public API URI. |
-### Prerequisites
+## Example usage
-The use of key-auth and jwt-auth requires the configuration of a consumer that contains the configuration of these plugins, and you need to create one in advance, the process will be omitted here.
+The example below uses the [jwt-auth](./jwt-auth.md) Plugin and the [key-auth](./key-auth.md) Plugin along with the `public-api` Plugin. Refer to their documentation for it configuration. This step is omitted below and only explains the configuration of the `public-api` Plugin.
-### Basic Use Case
+### Basic usage
-First we will setup a route.
+You can enable the Plugin on a specific Route as shown below:
```shell
-$ curl -X PUT 'http://127.0.0.1:9080/apisix/admin/routes/r1' \
+curl -X PUT 'http://127.0.0.1:9080/apisix/admin/routes/r1' \
-H 'X-API-KEY: <api-key>' \
-H 'Content-Type: application/json' \
-d '{
@@ -58,20 +61,18 @@ $ curl -X PUT 'http://127.0.0.1:9080/apisix/admin/routes/r1' \
}'
```
-Let's test it.
+Now, if you make a request to the configured URI, you will receive a JWT response:
```shell
-$ curl 'http://127.0.0.1:9080/apisix/plugin/jwt/sign?key=user-key'
+curl 'http://127.0.0.1:9080/apisix/plugin/jwt/sign?key=user-key'
```
-It will respond to a text JWT.
+### Using custom URI
-### Customize URI
-
-Let's setup another route.
+You can also use a custom URI for exposing the API as shown below:
```shell
-$ curl -X PUT 'http://127.0.0.1:9080/apisix/admin/routes/r2' \
+curl -X PUT 'http://127.0.0.1:9080/apisix/admin/routes/r2' \
-H 'X-API-KEY: <api-key>' \
-H 'Content-Type: application/json' \
-d '{
@@ -84,20 +85,18 @@ $ curl -X PUT 'http://127.0.0.1:9080/apisix/admin/routes/r2' \
}'
```
-Let's test it.
+Now you can make requests to this new endpoint:
```shell
-$ curl 'http://127.0.0.1:9080/gen_token?key=user-key'
+curl 'http://127.0.0.1:9080/gen_token?key=user-key'
```
-It will still respond to a text JWT. We can see that users are free to configure URI for the public API to match.
-
-### Protect Route
+### Securing the Route
-Let's modify the last route and add `key-auth` authentication to it.
+You can use the `key-auth` Plugin to add authentication and secure the Route:
```shell
-$ curl -X PUT 'http://127.0.0.1:9080/apisix/admin/routes/r2' \
+curl -X PUT 'http://127.0.0.1:9080/apisix/admin/routes/r2' \
-H 'X-API-KEY: <api-key>' \
-H 'Content-Type: application/json' \
-d '{
@@ -111,16 +110,40 @@ $ curl -X PUT 'http://127.0.0.1:9080/apisix/admin/routes/r2' \
}'
```
-Let's test it.
+Now, only authenticated requests are allowed:
```shell
-$ curl -i 'http://127.0.0.1:9080/gen_token?key=user-key'
+curl -i 'http://127.0.0.1:9080/gen_token?key=user-key'
-H "apikey: test-apikey"
+```
+
+```shell
HTTP/1.1 200 OK
+```
+
+The below request will fail:
-# Failed request
-$ curl -i 'http://127.0.0.1:9080/gen_token?key=user-key'
+```shell
+curl -i 'http://127.0.0.1:9080/gen_token?key=user-key'
+```
+
+```shell
HTTP/1.1 401 UNAUTHORIZED
```
-It will still respond to a text JWT. If we don't add `apikey` to the request header, it will respond with a 401 block request. In this way, we have implemented a plugin approach to protect the public API.
+## Disable Plugin
+
+To disable the `public-api` Plugin, you can delete the corresponding JSON configuration from the Plugin configuration. APISIX will automatically reload and you do not have to restart for this to take effect.
+
+```shell
+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
+ }
+ }
+}'
+```
diff --git a/docs/en/latest/plugins/referer-restriction.md b/docs/en/latest/plugins/referer-restriction.md
index f52955d1a..2fa6a1b3b 100644
--- a/docs/en/latest/plugins/referer-restriction.md
+++ b/docs/en/latest/plugins/referer-restriction.md
@@ -1,5 +1,11 @@
---
title: referer-restriction
+keywords:
+ - APISIX
+ - Plugin
+ - Referer restriction
+ - referer-restriction
+description: This document contains information about the Apache APISIX referer-restriction Plugin.
---
<!--
@@ -23,24 +29,26 @@ title: referer-restriction
## Description
-The `referer-restriction` can restrict access to a Service or a Route by
-whitelisting/blacklisting request header Referrers.
+The `referer-restriction` Plugin can be used to restrict access to a Service or a Route by whitelisting/blacklisting the `Referer` request header.
## Attributes
-| Name | Type | Requirement | Default | Valid | Description |
-| --------- | ------------- | ----------- | ------- | ----- | ---------------------------------------- |
-| whitelist | array[string] | optional | | | List of hostname to whitelist. The hostname can be started with `*` as a wildcard |
-| blacklist | array[string] | optional | | | List of hostname to blacklist. The hostname can be started with `*` as a wildcard |
-| message | string | optional | Your referer host is not allowed | [1, 1024] | Message returned in case access is not allowed. |
-| bypass_missing | boolean | optional | false | | Whether to bypass the check when the Referer header is missing or malformed |
+| Name | Type | Required | Default | Valid values | Description |
+|----------------|---------------|----------|----------------------------------|--------------|---------------------------------------------------------------------------------------------------|
+| whitelist | array[string] | False | | | List of hostnames to whitelist. A hostname can start with `*` for wildcard. |
+| blacklist | array[string] | False | | | List of hostnames to blacklist. A hostname can start with `*` for wildcard. |
+| message | string | False | Your referer host is not allowed | [1, 1024] | Message returned when access is not allowed. |
+| bypass_missing | boolean | False | false | | When set to `true`, bypasses the check when the `Referer` request header is missing or malformed. |
-One of `whitelist` or `blacklist` must be specified, and they can not work together.
-The message can be user-defined.
+:::info IMPORTANT
-## How To Enable
+Only one of `whitelist` or `blacklist` attribute must be specified. They cannot work together.
-Creates a route or service object, and enable plugin `referer-restriction`.
+:::
+
+## Enabling the Plugin
+
+You can enable the Plugin on a specific Route or a Service as shown below:
```shell
curl http://127.0.0.1:9080/apisix/admin/routes/1 -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
@@ -64,41 +72,48 @@ curl http://127.0.0.1:9080/apisix/admin/routes/1 -H 'X-API-KEY: edd1c9f034335f13
}'
```
-## Test Plugin
+## Example usage
-Request with `Referer: http://xx.com/x`:
+Once you have configured the Plugin as shown above, you can test it by setting `Referer: http://xx.com/x`:
+
+```shell
+curl http://127.0.0.1:9080/index.html -H 'Referer: http://xx.com/x'
+```
```shell
-$ curl http://127.0.0.1:9080/index.html -H 'Referer: http://xx.com/x'
HTTP/1.1 200 OK
...
```
-Request with `Referer: http://yy.com/x`:
+Now, if you make a request with `Referer: http://yy.com/x`, the request will be blocked:
+
+```shell
+curl http://127.0.0.1:9080/index.html -H 'Referer: http://yy.com/x'
+```
```shell
-$ curl http://127.0.0.1:9080/index.html -H 'Referer: http://yy.com/x'
HTTP/1.1 403 Forbidden
...
{"message":"Your referer host is not allowed"}
```
-Request without `Referer`:
+Since we have set `bypass_missing` to `true` a request without the `Referer` header will be successful as the check is skipped:
+
+```shell
+curl http://127.0.0.1:9080/index.html
+```
```shell
-$ curl http://127.0.0.1:9080/index.html
HTTP/1.1 200 OK
...
```
## Disable Plugin
-When you want to disable the `referer-restriction` plugin, it is very simple,
-you can delete the corresponding json configuration in the plugin configuration,
-no need to restart the service, it will take effect immediately:
+To disable the `referer-restriction` Plugin, you can delete the corresponding JSON configuration from the Plugin configuration. APISIX will automatically reload and you do not have to restart for this to take effect.
```shell
-$ curl http://127.0.0.1:9080/apisix/admin/routes/1 -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
+curl http://127.0.0.1:9080/apisix/admin/routes/1 -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
{
"uri": "/index.html",
"plugins": {},
@@ -110,5 +125,3 @@ $ curl http://127.0.0.1:9080/apisix/admin/routes/1 -H 'X-API-KEY: edd1c9f034335f
}
}'
```
-
-The `referer-restriction` plugin has been disabled now. It works for other plugins.