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 <[email protected]>
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.
