You are viewing a plain text version of this content. The canonical link for it is here.
Posted to notifications@apisix.apache.org by me...@apache.org on 2020/10/06 10:20:24 UTC
[apisix] branch master updated: feat: implemented
`referer-restriction` plugin (#2352)
This is an automated email from the ASF dual-hosted git repository.
membphis 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 5b97223 feat: implemented `referer-restriction` plugin (#2352)
5b97223 is described below
commit 5b97223592c9584e5280c397968e9d9c4739e3d4
Author: 罗泽轩 <sp...@gmail.com>
AuthorDate: Tue Oct 6 18:20:17 2020 +0800
feat: implemented `referer-restriction` plugin (#2352)
---
README.md | 1 +
README_CN.md | 1 +
apisix/plugins/referer-restriction.lua | 124 ++++++++++++++++++++
conf/config-default.yaml | 1 +
doc/README.md | 1 +
doc/_sidebar.md | 1 +
doc/plugins/referer-restriction.md | 116 +++++++++++++++++++
doc/zh-cn/README.md | 1 +
doc/zh-cn/plugins/referer-restriction.md | 111 ++++++++++++++++++
t/admin/plugins.t | 2 +-
t/debug/debug-mode.t | 1 +
t/plugin/referer-restriction.t | 189 +++++++++++++++++++++++++++++++
12 files changed, 548 insertions(+), 1 deletion(-)
diff --git a/README.md b/README.md
index c856505..1f4d5e9 100644
--- a/README.md
+++ b/README.md
@@ -86,6 +86,7 @@ A/B testing, canary release, blue-green deployment, limit rate, defense against
- **Security**
- Authentications: [key-auth](doc/plugins/key-auth.md), [JWT](doc/plugins/jwt-auth.md), [basic-auth](doc/plugins/basic-auth.md), [wolf-rbac](doc/plugins/wolf-rbac.md)
- [IP Whitelist/Blacklist](doc/plugins/ip-restriction.md)
+ - [Referer Whitelist/Blacklist](doc/plugins/referer-restriction.md)
- [IdP](doc/plugins/openid-connect.md): Support external authentication services, such as Auth0, okta, etc., users can use this to connect to OAuth 2.0 and other authentication methods.
- [Limit-req](doc/plugins/limit-req.md)
- [Limit-count](doc/plugins/limit-count.md)
diff --git a/README_CN.md b/README_CN.md
index 829633f..28b8136 100644
--- a/README_CN.md
+++ b/README_CN.md
@@ -85,6 +85,7 @@ A/B 测试、金丝雀发布(灰度发布)、蓝绿部署、限流限速、抵
- **安全防护**
- 多种身份认证方式: [key-auth](doc/zh-cn/plugins/key-auth.md), [JWT](doc/zh-cn/plugins/jwt-auth.md), [basic-auth](doc/zh-cn/plugins/basic-auth.md), [wolf-rbac](doc/zh-cn/plugins/wolf-rbac.md)。
- [IP 黑白名单](doc/zh-cn/plugins/ip-restriction.md)
+ - [Referer 白名单](doc/zh-cn/plugins/referer-restriction.md)
- [IdP 支持](doc/plugins/openid-connect.md): 支持外部的身份认证服务，比如 Auth0，Okta，Authing 等，用户可以借此来对接 Oauth2.0 等认证方式。
- [限制速率](doc/zh-cn/plugins/limit-req.md)
- [限制请求数](doc/zh-cn/plugins/limit-count.md)
diff --git a/apisix/plugins/referer-restriction.lua b/apisix/plugins/referer-restriction.lua
new file mode 100644
index 0000000..e67b455
--- /dev/null
+++ b/apisix/plugins/referer-restriction.lua
@@ -0,0 +1,124 @@
+--
+-- Licensed to the Apache Software Foundation (ASF) under one or more
+-- contributor license agreements. See the NOTICE file distributed with
+-- this work for additional information regarding copyright ownership.
+-- The ASF licenses this file to You under the Apache License, Version 2.0
+-- (the "License"); you may not use this file except in compliance with
+-- the License. You may obtain a copy of the License at
+--
+-- http://www.apache.org/licenses/LICENSE-2.0
+--
+-- Unless required by applicable law or agreed to in writing, software
+-- distributed under the License is distributed on an "AS IS" BASIS,
+-- WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+-- See the License for the specific language governing permissions and
+-- limitations under the License.
+--
+local ipairs = ipairs
+local core = require("apisix.core")
+local http = require "resty.http"
+local lrucache = core.lrucache.new({
+ ttl = 300, count = 512
+})
+
+
+local schema = {
+ type = "object",
+ properties = {
+ bypass_missing = {
+ type = "boolean",
+ default = false,
+ },
+ whitelist = {
+ type = "array",
+ items = core.schema.host_def,
+ minItems = 1
+ },
+ },
+ required = {"whitelist"},
+ additionalProperties = false,
+}
+
+
+local plugin_name = "referer-restriction"
+
+
+local _M = {
+ version = 0.1,
+ priority = 2990,
+ name = plugin_name,
+ schema = schema,
+}
+
+
+function _M.check_schema(conf)
+ return core.schema.check(schema, conf)
+end
+
+
+local function match_host(matcher, host)
+ if matcher.map[host] then
+ return true
+ end
+ for _, h in ipairs(matcher.suffixes) do
+ if core.string.has_suffix(host, h) then
+ return true
+ end
+ end
+ return false
+end
+
+
+local function create_host_matcher(hosts)
+ local hosts_suffix = {}
+ local hosts_map = {}
+
+ for _, h in ipairs(hosts) do
+ if h:byte(1) == 42 then -- start with '*'
+ core.table.insert(hosts_suffix, h:sub(2))
+ else
+ hosts_map[h] = true
+ end
+ end
+
+ return {
+ suffixes = hosts_suffix,
+ map = hosts_map,
+ }
+end
+
+
+function _M.access(conf, ctx)
+ local block = false
+ local referer = ctx.var.http_referer
+ if referer then
+ -- parse_uri doesn't support IPv6 literal, it is OK since we only
+ -- expect hostname in the whitelist.
+ -- See https://github.com/ledgetech/lua-resty-http/pull/104
+ local uri = http.parse_uri(nil, referer)
+ if not uri then
+ -- malformed Referer
+ referer = nil
+ else
+ -- take host part only
+ referer = uri[2]
+ end
+ end
+
+
+ if not referer then
+ block = not conf.bypass_missing
+
+ elseif conf.whitelist then
+ local matcher = lrucache(conf.whitelist, nil,
+ create_host_matcher, conf.whitelist)
+ block = not match_host(matcher, referer)
+ end
+
+ if block then
+ return 403, { message = "Your referer host is not allowed" }
+ end
+end
+
+
+return _M
diff --git a/conf/config-default.yaml b/conf/config-default.yaml
index 6e09012..063eb0a 100644
--- a/conf/config-default.yaml
+++ b/conf/config-default.yaml
@@ -166,6 +166,7 @@ plugins: # plugin list
- jwt-auth
- zipkin
- ip-restriction
+ - referer-restriction
- grpc-transcode
- serverless-pre-function
- serverless-post-function
diff --git a/doc/README.md b/doc/README.md
index e4d4023..8323ea0 100644
--- a/doc/README.md
+++ b/doc/README.md
@@ -66,6 +66,7 @@ Plugins
* [cors](plugins/cors.md): Enable CORS(Cross-origin resource sharing) for your API.
* [uri-blocker](plugins/uri-blocker.md): Block client request by URI.
* [ip-restriction](plugins/ip-restriction.md): IP whitelist/blacklist.
+* [referer-restriction](plugins/referer-restriction.md): Referer whitelist.
**Traffic**
* [limit-req](plugins/limit-req.md): Request rate limiting and adjustment based on the "leaky bucket" method.
diff --git a/doc/_sidebar.md b/doc/_sidebar.md
index 8a354cb..e627e0d 100644
--- a/doc/_sidebar.md
+++ b/doc/_sidebar.md
@@ -81,6 +81,7 @@
- [Limit Request](plugins/limit-req.md)
- [CORS](plugins/cors.md)
- [IP Restriction](plugins/ip-restriction.md)
+ - [Referer Restriction](plugins/referer-restriction.md)
- [Keycloak Authorization](plugins/authz-keycloak.md)
- [RBAC Wolf](plugins/wolf-rbac.md)
diff --git a/doc/plugins/referer-restriction.md b/doc/plugins/referer-restriction.md
new file mode 100644
index 0000000..afc66d3
--- /dev/null
+++ b/doc/plugins/referer-restriction.md
@@ -0,0 +1,116 @@
+<!--
+#
+# Licensed to the Apache Software Foundation (ASF) under one or more
+# contributor license agreements. See the NOTICE file distributed with
+# this work for additional information regarding copyright ownership.
+# The ASF licenses this file to You under the Apache License, Version 2.0
+# (the "License"); you may not use this file except in compliance with
+# the License. You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+#
+-->
+
+- [中文](../zh-cn/plugins/referer-restriction.md)
+
+# Summary
+- [**Name**](#name)
+- [**Attributes**](#attributes)
+- [**How To Enable**](#how-to-enable)
+- [**Test Plugin**](#test-plugin)
+- [**Disable Plugin**](#disable-plugin)
+
+
+## Name
+
+The `referer-restriction` can restrict access to a Service or a Route by
+whitelisting request header Referers.
+
+## Attributes
+
+| Name | Type | Requirement | Default | Valid | Description |
+| --------- | ------------- | ----------- | ------- | ----- | ---------------------------------------- |
+| whitelist | array[string] | required | | | List of hostname to whitelist. The hostname can be started with `*` as a wildcard |
+| bypass_missing | boolean | optional | false | | Whether to bypass the check when the Referer header is missing or malformed |
+
+## How To Enable
+
+Creates a route or service object, and enable plugin `referer-restriction`.
+
+```shell
+curl http://127.0.0.1:9080/apisix/admin/routes/1 -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
+{
+ "uri": "/index.html",
+ "upstream": {
+ "type": "roundrobin",
+ "nodes": {
+ "127.0.0.1:1980": 1
+ }
+ },
+ "plugins": {
+ "referer-restriction": {
+ "bypass_missing": true,
+ "whitelist": [
+ "xx.com",
+ "*.xx.com"
+ ]
+ }
+ }
+}'
+```
+
+## Test Plugin
+
+Request with `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`:
+
+```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`:
+
+```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:
+
+```shell
+$ curl http://127.0.0.1:2379/v2/keys/apisix/routes/1 -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d value='
+{
+ "uri": "/index.html",
+ "plugins": {},
+ "upstream": {
+ "type": "roundrobin",
+ "nodes": {
+ "39.97.63.215:80": 1
+ }
+ }
+}'
+```
+
+The `referer-restriction` plugin has been disabled now. It works for other plugins.
+
diff --git a/doc/zh-cn/README.md b/doc/zh-cn/README.md
index 558f1bd..2c45511 100644
--- a/doc/zh-cn/README.md
+++ b/doc/zh-cn/README.md
@@ -53,6 +53,7 @@
* [grpc-transcode](plugins/grpc-transcode.md)：REST <--> gRPC 转码。
* [serverless](plugins/serverless.md)：允许在 APISIX 中的不同阶段动态运行 Lua 代码。
* [ip-restriction](plugins/ip-restriction.md): IP 黑白名单。
+* [referer-restriction](plugins/referer-restriction.md): Referer 白名单。
* [openid-connect](plugins/openid-connect.md)
* [redirect](plugins/redirect.md): URI 重定向。
* [response-rewrite](plugins/response-rewrite.md): 支持自定义修改返回内容的 `status code`、`body`、`headers`。
diff --git a/doc/zh-cn/plugins/referer-restriction.md b/doc/zh-cn/plugins/referer-restriction.md
new file mode 100644
index 0000000..1f5f0ae
--- /dev/null
+++ b/doc/zh-cn/plugins/referer-restriction.md
@@ -0,0 +1,111 @@
+<!--
+#
+# Licensed to the Apache Software Foundation (ASF) under one or more
+# contributor license agreements. See the NOTICE file distributed with
+# this work for additional information regarding copyright ownership.
+# The ASF licenses this file to You under the Apache License, Version 2.0
+# (the "License"); you may not use this file except in compliance with
+# the License. You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+#
+-->
+
+- [English](../../plugins/referer-restriction.md)
+
+# 目录
+- [**名字**](#名字)
+- [**属性**](#属性)
+- [**如何启用**](#如何启用)
+- [**测试插件**](#测试插件)
+- [**禁用插件**](#禁用插件)
+
+## 名字
+
+`referer-restriction` 插件可以根据 Referer 请求头限制访问。
+
+## 属性
+
+| 参数名 | 类型 | 可选项 | 默认值 | 有效值 | 描述 |
+| --------- | ------------- | ------ | ------ | ------ | -------------------------------- |
+| whitelist | array[string] | 必须 | | | 域名列表。域名开头可以用'*'作为通配符 |
+| bypass_missing | boolean | 可选 | false | | 当 Referer 不存在或格式有误时，是否绕过检查 |
+
+## 如何启用
+
+下面是一个示例，在指定的 route 上开启了 `referer-restriction` 插件:
+
+```shell
+curl http://127.0.0.1:9080/apisix/admin/routes/1 -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
+{
+ "uri": "/index.html",
+ "upstream": {
+ "type": "roundrobin",
+ "nodes": {
+ "127.0.0.1:1980": 1
+ }
+ },
+ "plugins": {
+ "referer-restriction": {
+ "bypass_missing": true,
+ "whitelist": [
+ "xx.com",
+ "*.xx.com"
+ ]
+ }
+ }
+}'
+```
+
+## 测试插件
+
+带 `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
+...
+```
+
+带 `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"}
+```
+
+不带 `Referer` 请求:
+
+```shell
+$ curl http://127.0.0.1:9080/index.html
+HTTP/1.1 200 OK
+...
+```
+
+## 禁用插件
+
+当你想去掉 `referer-restriction` 插件的时候，很简单，在插件的配置中把对应的 json 配置删除即可，无须重启服务，即刻生效：
+
+```shell
+$ curl http://127.0.0.1:2379/v2/keys/apisix/routes/1 -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d value='
+{
+ "uri": "/index.html",
+ "plugins": {},
+ "upstream": {
+ "type": "roundrobin",
+ "nodes": {
+ "39.97.63.215:80": 1
+ }
+ }
+}'
+```
+
+现在就已移除 `referer-restriction` 插件，其它插件的开启和移除也类似。
diff --git a/t/admin/plugins.t b/t/admin/plugins.t
index 6c72d25..4caca83 100644
--- a/t/admin/plugins.t
+++ b/t/admin/plugins.t
@@ -30,7 +30,7 @@ __DATA__
--- request
GET /apisix/admin/plugins/list
--- response_body_like eval
-qr/\["request-id","fault-injection","serverless-pre-function","batch-requests","cors","ip-restriction","uri-blocker","request-validation","openid-connect","wolf-rbac","hmac-auth","basic-auth","jwt-auth","key-auth","consumer-restriction","authz-keycloak","proxy-mirror","proxy-cache","proxy-rewrite","limit-conn","limit-count","limit-req","node-status","redirect","response-rewrite","grpc-transcode","prometheus","echo","http-logger","tcp-logger","kafka-logger","syslog","udp-logger","zipkin", [...]
+qr/\["request-id","fault-injection","serverless-pre-function","batch-requests","cors","ip-restriction","referer-restriction","uri-blocker","request-validation","openid-connect","wolf-rbac","hmac-auth","basic-auth","jwt-auth","key-auth","consumer-restriction","authz-keycloak","proxy-mirror","proxy-cache","proxy-rewrite","limit-conn","limit-count","limit-req","node-status","redirect","response-rewrite","grpc-transcode","prometheus","echo","http-logger","tcp-logger","kafka-logger","syslog", [...]
--- no_error_log
[error]
diff --git a/t/debug/debug-mode.t b/t/debug/debug-mode.t
index 442cce1..9ad669f 100644
--- a/t/debug/debug-mode.t
+++ b/t/debug/debug-mode.t
@@ -52,6 +52,7 @@ loaded plugin and sort by priority: 10000 name: serverless-pre-function
loaded plugin and sort by priority: 4010 name: batch-requests
loaded plugin and sort by priority: 4000 name: cors
loaded plugin and sort by priority: 3000 name: ip-restriction
+loaded plugin and sort by priority: 2990 name: referer-restriction
loaded plugin and sort by priority: 2900 name: uri-blocker
loaded plugin and sort by priority: 2800 name: request-validation
loaded plugin and sort by priority: 2599 name: openid-connect
diff --git a/t/plugin/referer-restriction.t b/t/plugin/referer-restriction.t
new file mode 100644
index 0000000..3c765f5
--- /dev/null
+++ b/t/plugin/referer-restriction.t
@@ -0,0 +1,189 @@
+#
+# Licensed to the Apache Software Foundation (ASF) under one or more
+# contributor license agreements. See the NOTICE file distributed with
+# this work for additional information regarding copyright ownership.
+# The ASF licenses this file to You under the Apache License, Version 2.0
+# (the "License"); you may not use this file except in compliance with
+# the License. You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+#
+use t::APISIX 'no_plan';
+
+add_block_preprocessor(sub {
+ my ($block) = @_;
+
+ $block->set_value("no_error_log", "[error]");
+
+ $block;
+});
+
+repeat_each(1);
+no_long_string();
+no_root_location();
+no_shuffle();
+run_tests;
+
+__DATA__
+
+=== TEST 1: set whitelist
+--- config
+ location /t {
+ content_by_lua_block {
+ local t = require("lib.test_admin").test
+ local code, body = t('/apisix/admin/routes/1',
+ ngx.HTTP_PUT,
+ [[{
+ "uri": "/hello",
+ "upstream": {
+ "type": "roundrobin",
+ "nodes": {
+ "127.0.0.1:1980": 1
+ }
+ },
+ "plugins": {
+ "referer-restriction": {
+ "whitelist": [
+ "*.xx.com",
+ "yy.com"
+ ]
+ }
+ }
+ }]]
+ )
+
+ if code >= 300 then
+ ngx.status = code
+ end
+ ngx.say(body)
+ }
+ }
+--- request
+GET /t
+--- response_body
+passed
+
+
+
+=== TEST 2: hit route and in the whitelist (wildcard)
+--- request
+GET /hello
+--- more_headers
+Referer: http://www.xx.com
+--- response_body
+hello world
+
+
+
+=== TEST 3: hit route and in the whitelist
+--- request
+GET /hello
+--- more_headers
+Referer: https://yy.com/am
+--- response_body
+hello world
+
+
+
+=== TEST 4: hit route and not in the whitelist
+--- request
+GET /hello
+--- more_headers
+Referer: https://www.yy.com/am
+--- error_code: 403
+
+
+
+=== TEST 5: hit route and without Referer
+--- request
+GET /hello
+--- error_code: 403
+
+
+
+=== TEST 6: set whitelist, allow Referer missing
+--- config
+ location /t {
+ content_by_lua_block {
+ local t = require("lib.test_admin").test
+ local code, body = t('/apisix/admin/routes/1',
+ ngx.HTTP_PUT,
+ [[{
+ "uri": "/hello",
+ "upstream": {
+ "type": "roundrobin",
+ "nodes": {
+ "127.0.0.1:1980": 1
+ }
+ },
+ "plugins": {
+ "referer-restriction": {
+ "bypass_missing": true,
+ "whitelist": [
+ "*.xx.com",
+ "yy.com"
+ ]
+ }
+ }
+ }]]
+ )
+
+ if code >= 300 then
+ ngx.status = code
+ end
+ ngx.say(body)
+ }
+ }
+--- request
+GET /t
+--- response_body
+passed
+
+
+
+=== TEST 7: hit route and without Referer
+--- request
+GET /hello
+--- response_body
+hello world
+
+
+
+=== TEST 8: malformed Referer is treated as missing
+--- request
+GET /hello
+--- more_headers
+Referer: www.yy.com
+--- response_body
+hello world
+
+
+
+=== TEST 9: invalid schema
+--- config
+ location /t {
+ content_by_lua_block {
+ local plugin = require("apisix.plugins.referer-restriction")
+ local cases = {
+ "x.*",
+ "~y.xn",
+ "::1",
+ }
+ for _, c in ipairs(cases) do
+ local ok, err = plugin.check_schema({
+ whitelist = {c}
+ })
+ if ok then
+ ngx.log(ngx.ERR, c)
+ end
+ end
+ }
+ }
+--- request
+GET /t