URI Blocker
The uri-blocker plugin rejects requests when their URI matches one or more configured regular expressions. It can protect internal paths, block disallowed query options, and return a controlled status and error message without contacting the upstream service.
Examples
The examples first block an internal path and return a custom response. The second example updates the same route to block a query option without regard to letter case.
If Admin API authentication is enabled, export an admin-role key as ADMIN_API_KEY before using the Admin API tab.
Block an Internal Path
Configure one route for an internal path and a public httpbin.org endpoint. Requests that match the internal-path rule are rejected before the upstream is contacted.
- Admin API
- ADC
- Ingress Controller
Create the route:
curl "http://127.0.0.1:9180/apisix/admin/routes/uri-blocker-route" -X PUT \
-H "X-API-KEY: ${ADMIN_API_KEY}" \
-d '{
"uris": [
"/internal/*",
"/anything"
],
"plugins": {
"uri-blocker": {
"block_rules": [
"^/internal(?:/|\\?|$)"
],
"rejected_code": 403,
"rejected_msg": "internal path blocked"
}
},
"upstream": {
"type": "roundrobin",
"nodes": {
"httpbin.org:80": 1
}
}
}'
Configure ADC to connect to the target backend. The remaining ADC commands read the connection settings from these environment variables:
- APISIX
- API7 Gateway
If Admin API authentication is enabled, export an admin-role key as ADMIN_API_KEY before configuring ADC.
export ADC_BACKEND=apisix
export ADC_SERVER="http://127.0.0.1:9180"
export ADC_TOKEN="${ADMIN_API_KEY}"
export ADC_BACKEND=api7ee
export ADC_SERVER="https://{DASHBOARD_ADDR}"
export ADC_TOKEN="{DASHBOARD_TOKEN}"
export ADC_GATEWAY_GROUP="{GATEWAY_GROUP}"
Create the service and route:
services:
- name: uri-blocker-service
labels:
docs-example: uri-blocker
routes:
- name: uri-blocker-route
uris:
- /internal/*
- /anything
plugins:
uri-blocker:
block_rules:
- ^/internal(?:/|\?|$)
rejected_code: 403
rejected_msg: internal path blocked
upstream:
type: roundrobin
nodes:
- host: httpbin.org
port: 80
weight: 1
Preview the changes and confirm that they only affect resources for this example:
adc diff -f adc.yaml \
--include-resource-type service \
--label-selector docs-example=uri-blocker
Review diff.yaml, then synchronize the labeled service:
adc sync -f adc.yaml \
--include-resource-type service \
--label-selector docs-example=uri-blocker
Set up the Ingress Controller and gateway in the aic namespace before continuing.
Create an external-name service for the example upstream:
apiVersion: v1
kind: Service
metadata:
namespace: aic
name: httpbin-external-domain
spec:
type: ExternalName
externalName: httpbin.org
ports:
- port: 80
targetPort: 80
Apply the upstream service:
kubectl apply -f uri-blocker-upstream.yaml
Configure the path rule with the Kubernetes API used by the deployment:
- Gateway API
- APISIX CRD
apiVersion: apisix.apache.org/v1alpha1
kind: PluginConfig
metadata:
namespace: aic
name: uri-blocker-route
spec:
plugins:
- name: uri-blocker
config:
block_rules:
- ^/internal(?:/|\?|$)
rejected_code: 403
rejected_msg: internal path blocked
---
apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
namespace: aic
name: uri-blocker-route
spec:
parentRefs:
- name: apisix
rules:
- matches:
- path:
type: PathPrefix
value: /internal/
- path:
type: Exact
value: /anything
filters:
- type: ExtensionRef
extensionRef:
group: apisix.apache.org
kind: PluginConfig
name: uri-blocker-route
backendRefs:
- name: httpbin-external-domain
port: 80
apiVersion: apisix.apache.org/v2
kind: ApisixPluginConfig
metadata:
namespace: aic
name: uri-blocker-route
spec:
ingressClassName: apisix
plugins:
- name: uri-blocker
enable: true
config:
block_rules:
- ^/internal(?:/|\?|$)
rejected_code: 403
rejected_msg: internal path blocked
---
apiVersion: apisix.apache.org/v2
kind: ApisixRoute
metadata:
namespace: aic
name: uri-blocker-route
spec:
ingressClassName: apisix
http:
- name: uri-blocker-route
match:
paths:
- /internal/*
- /anything
backends:
- serviceName: httpbin-external-domain
servicePort: 80
plugin_config_name: uri-blocker-route
Apply the route configuration:
kubectl apply -f uri-blocker-ic.yaml
Send a request to the blocked path:
curl --include "http://127.0.0.1:9080/internal/report"
The blocked request returns the configured status and message:
HTTP/1.1 403 Forbidden
...
{"error_msg":"internal path blocked"}
Send a request that does not match the rule:
curl "http://127.0.0.1:9080/anything" \
--silent \
--output /dev/null \
--write-out "Allowed response: %{http_code}\n"
The public request reaches the upstream:
Allowed response: 200
Match a Query Option Without Case Sensitivity
Update the plugin on the existing route so that a debug=true query option is blocked regardless of letter case:
- Admin API
- ADC
- Ingress Controller
curl "http://127.0.0.1:9180/apisix/admin/routes/uri-blocker-route" -X PATCH \
-H "X-API-KEY: ${ADMIN_API_KEY}" \
-H "Content-Type: application/json" \
-d '{
"plugins": {
"uri-blocker": {
"block_rules": [
"[?&]debug=true(?:&|$)"
],
"rejected_code": 403,
"rejected_msg": "debug mode blocked",
"case_insensitive": true
}
}
}'
In adc.yaml, replace the plugin configuration on the existing route:
plugins:
uri-blocker:
block_rules:
- '[?&]debug=true(?:&|$)'
rejected_code: 403
rejected_msg: debug mode blocked
case_insensitive: true
Preview and synchronize the updated file:
adc diff -f adc.yaml \
--include-resource-type service \
--label-selector docs-example=uri-blocker
adc sync -f adc.yaml \
--include-resource-type service \
--label-selector docs-example=uri-blocker
Update the existing plugin configuration with the Kubernetes API used by the deployment. The route and upstream service from the first example remain unchanged.
- Gateway API
- APISIX CRD
apiVersion: apisix.apache.org/v1alpha1
kind: PluginConfig
metadata:
namespace: aic
name: uri-blocker-route
spec:
plugins:
- name: uri-blocker
config:
block_rules:
- '[?&]debug=true(?:&|$)'
rejected_code: 403
rejected_msg: debug mode blocked
case_insensitive: true
apiVersion: apisix.apache.org/v2
kind: ApisixPluginConfig
metadata:
namespace: aic
name: uri-blocker-route
spec:
ingressClassName: apisix
plugins:
- name: uri-blocker
enable: true
config:
block_rules:
- '[?&]debug=true(?:&|$)'
rejected_code: 403
rejected_msg: debug mode blocked
case_insensitive: true
Apply the updated plugin configuration:
kubectl apply -f uri-blocker-ic.yaml
Send a request with uppercase query option values:
curl --include "http://127.0.0.1:9080/anything?DEBUG=TRUE"
The case-insensitive rule blocks the request:
HTTP/1.1 403 Forbidden
...
{"error_msg":"debug mode blocked"}
Send a request with a value that does not match the rule:
curl "http://127.0.0.1:9080/anything?debug=false" \
--silent \
--output /dev/null \
--write-out "Allowed response: %{http_code}\n"
The value that does not match reaches the upstream:
Allowed response: 200