diff --git a/README.md b/README.md index c8565050..1f4d5e9f 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 829633fb..28b8136a 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 00000000..e67b4558 --- /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 6e090120..063eb0a4 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 e4d40233..8323ea09 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 8a354cb3..e627e0de 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 00000000..afc66d3a --- /dev/null +++ b/doc/plugins/referer-restriction.md @@ -0,0 +1,116 @@ + + +- [中文](../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 558f1bdd..2c45511e 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 00000000..1f5f0ae7 --- /dev/null +++ b/doc/zh-cn/plugins/referer-restriction.md @@ -0,0 +1,111 @@ + + +- [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 6c72d25a..4caca835 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","skywalking","serverless-post-function"\]/ +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","udp-logger","zipkin","skywalking","serverless-post-function"\]/ --- no_error_log [error] diff --git a/t/debug/debug-mode.t b/t/debug/debug-mode.t index 442cce1c..9ad669f6 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 00000000..3c765f56 --- /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