Skip to content

Commit 0e97e91

Browse files
dspodspo
authored
feat: add plugin attach-consmer-label (#11604)
1 parent f776d68 commit 0e97e91

File tree

9 files changed

+900
-2
lines changed

9 files changed

+900
-2
lines changed

‎apisix/cli/config.lua‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -208,6 +208,7 @@ local _M = {
208208
"jwe-decrypt",
209209
"key-auth",
210210
"consumer-restriction",
211+
"attach-consumer-label",
211212
"forward-auth",
212213
"opa",
213214
"authz-keycloak",

‎apisix/plugins/attach-consumer-label.lua‎

Lines changed: 68 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,68 @@
1+
--
2+
-- Licensed to the Apache Software Foundation (ASF) under one or more
3+
-- contributor license agreements. See the NOTICE file distributed with
4+
-- this work for additional information regarding copyright ownership.
5+
-- The ASF licenses this file to You under the Apache License, Version 2.0
6+
-- (the "License"); you may not use this file except in compliance with
7+
-- the License. You may obtain a copy of the License at
8+
--
9+
-- http://www.apache.org/licenses/LICENSE-2.0
10+
--
11+
-- Unless required by applicable law or agreed to in writing, software
12+
-- distributed under the License is distributed on an "AS IS" BASIS,
13+
-- WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14+
-- See the License for the specific language governing permissions and
15+
-- limitations under the License.
16+
--
17+
18+
local core = require("apisix.core")
19+
local pairs = pairs
20+
local plugin_name = "attach-consumer-label"
21+
22+
local schema = {
23+
type = "object",
24+
properties = {
25+
headers = {
26+
type = "object",
27+
additionalProperties = {
28+
type = "string",
29+
pattern = "^\\$.*"
30+
},
31+
minProperties = 1
32+
},
33+
},
34+
required = {"headers"},
35+
}
36+
37+
local _M = {
38+
version = 0.1,
39+
priority = 2399,
40+
name = plugin_name,
41+
schema = schema,
42+
}
43+
44+
function _M.check_schema(conf)
45+
return core.schema.check(schema, conf)
46+
end
47+
48+
function _M.before_proxy(conf, ctx)
49+
-- check if the consumer is exists in the context
50+
if not ctx.consumer then
51+
return
52+
end
53+
54+
local labels = ctx.consumer.labels
55+
core.log.info("consumer username: ", ctx.consumer.username, " labels: ",
56+
core.json.delay_encode(labels))
57+
if not labels then
58+
return
59+
end
60+
61+
for header, label_key in pairs(conf.headers) do
62+
-- remove leading $ character
63+
local label_value = labels[label_key:sub(2)]
64+
core.request.set_header(ctx, header, label_value)
65+
end
66+
end
67+
68+
return _M

‎conf/config.yaml.example‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -470,6 +470,7 @@ plugins: # plugin list (sorted by priority)
470470
- jwe-decrypt # priority: 2509
471471
- key-auth # priority: 2500
472472
- consumer-restriction # priority: 2400
473+
- attach-consumer-label # priority: 2399
473474
- forward-auth # priority: 2002
474475
- opa # priority: 2001
475476
- authz-keycloak # priority: 2000

‎docs/en/latest/config.json‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -98,7 +98,8 @@
9898
"plugins/mocking",
9999
"plugins/degraphql",
100100
"plugins/body-transformer",
101-
"plugins/ai-proxy"
101+
"plugins/ai-proxy",
102+
"plugins/attach-consumer-label"
102103
]
103104
},
104105
{

‎docs/en/latest/plugins/attach-consumer-label.md‎

Lines changed: 180 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,180 @@
1+
---
2+
title: attach-consumer-label
3+
keywords:
4+
- Apache APISIX
5+
- API Gateway
6+
- API Consumer
7+
description: This article describes the Apache APISIX attach-consumer-label plugin, which you can use to pass custom consumer labels to upstream services.
8+
---
9+
10+
<!--
11+
#
12+
# Licensed to the Apache Software Foundation (ASF) under one or more
13+
# contributor license agreements. See the NOTICE file distributed with
14+
# this work for additional information regarding copyright ownership.
15+
# The ASF licenses this file to You under the Apache License, Version 2.0
16+
# (the "License"); you may not use this file except in compliance with
17+
# the License. You may obtain a copy of the License at
18+
#
19+
# http://www.apache.org/licenses/LICENSE-2.0
20+
#
21+
# Unless required by applicable law or agreed to in writing, software
22+
# distributed under the License is distributed on an "AS IS" BASIS,
23+
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
24+
# See the License for the specific language governing permissions and
25+
# limitations under the License.
26+
#
27+
-->
28+
29+
## Description
30+
31+
The `attach-consumer-label` plugin attaches custom consumer-related labels, in addition to `X-Consumer-Username` and `X-Credential-Indentifier`, to authenticated requests, for upstream services to differentiate between consumers and implement additional logics.
32+
33+
## Attributes
34+
35+
| Name | Type | Required | Default | Valid values | Description |
36+
|----------|--------|----------|---------|--------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
37+
| headers | object | True | | | Key-value pairs of consumer labels to be attached to request headers, where key is the request header name, such as `X-Consumer-Role`, and the value is a reference to the custom label key, such as `$role`. Note that the value should always start with a dollar sign (`$`). If a referenced consumer value is not configured on the consumer, the corresponding header will not be attached to the request. |
38+
39+
## Enable Plugin
40+
41+
The following example demonstrates how you can attach custom labels to request headers before authenticated requests are forwarded to upstream services. If the request is rejected, you should not see any consumer labels attached to request headers. If a certain label value is not configured on the consumer but referenced in the `attach-consumer-label` plugin, the corresponding header will also not be attached.
42+
43+
:::note
44+
45+
You can fetch the `admin_key` from `config.yaml` and save to an environment variable with the following command:
46+
47+
```bash
48+
admin_key=$(yq '.deployment.admin.admin_key[0].key' conf/config.yaml | sed 's/"//g')
49+
```
50+
51+
:::
52+
53+
Create a consumer `john` with custom labels:
54+
55+
```shell
56+
curl "http://127.0.0.1:9180/apisix/admin/consumers" -X PUT \
57+
-H "X-API-KEY: ${ADMIN_API_KEY}" \
58+
-d '{
59+
"username": "john",
60+
# highlight-start
61+
"labels": {
62+
// Annotate 1
63+
"department": "devops",
64+
// Annotate 2
65+
"company": "api7"
66+
}
67+
# highlight-end
68+
}'
69+
```
70+
71+
❶ Label the `department` information for the consumer.
72+
73+
❷ Label the `company` information for the consumer.
74+
75+
Configure the `key-auth` credential for the consumer `john`:
76+
77+
```shell
78+
curl "http://127.0.0.1:9180/apisix/admin/consumers/john/credentials" -X PUT \
79+
-H "X-API-KEY: ${ADMIN_API_KEY}" \
80+
-d '{
81+
"id": "cred-john-key-auth",
82+
"plugins": {
83+
"key-auth": {
84+
"key": "john-key"
85+
}
86+
}
87+
}'
88+
```
89+
90+
Create a route enabling the `key-auth` and `attach-consumer-label` plugins:
91+
92+
```shell
93+
curl "http://127.0.0.1:9180/apisix/admin/routes" -X PUT \
94+
-H "X-API-KEY: ${ADMIN_API_KEY}" \
95+
-d '{
96+
"id": "attach-consumer-label-route",
97+
"uri": "/get",
98+
"plugins": {
99+
"key-auth": {},
100+
# highlight-start
101+
"attach-consumer-label": {
102+
"headers": {
103+
// Annotate 1
104+
"X-Consumer-Department": "$department",
105+
// Annotate 2
106+
"X-Consumer-Company": "$company",
107+
// Annotate 3
108+
"X-Consumer-Role": "$role"
109+
}
110+
}
111+
# highlight-end
112+
},
113+
"upstream": {
114+
"type": "roundrobin",
115+
"nodes": {
116+
"httpbin.org:80": 1
117+
}
118+
}
119+
}'
120+
```
121+
122+
❶ Attach the `department` consumer label value in the `X-Consumer-Department` request header.
123+
124+
❷ Attach the `company` consumer label value in the `X-Consumer-Company` request header.
125+
126+
❸ Attach the `role` consumer label value in the `X-Consumer-Role` request header. As the `role` label is not configured on the consumer, it is expected that the header will not appear in the request forwarded to the upstream service.
127+
128+
:::tip
129+
130+
The consumer label references must be prefixed by a dollar sign (`$`).
131+
132+
:::
133+
134+
To verify, send a request to the route with the valid credential:
135+
136+
```shell
137+
curl -i "http://127.0.0.1:9080/get" -H 'apikey: john-key'
138+
```
139+
140+
You should see an `HTTP/1.1 200 OK` response similar to the following:
141+
142+
```text
143+
{
144+
"args": {},
145+
"headers": {
146+
"Accept": "*/*",
147+
"Apikey": "john-key",
148+
"Host": "127.0.0.1",
149+
# highlight-start
150+
"X-Consumer-Username": "john",
151+
"X-Credential-Indentifier": "cred-john-key-auth",
152+
"X-Consumer-Company": "api7",
153+
"X-Consumer-Department": "devops",
154+
# highlight-end
155+
"User-Agent": "curl/8.6.0",
156+
"X-Amzn-Trace-Id": "Root=1-66e5107c-5bb3e24f2de5baf733aec1cc",
157+
"X-Forwarded-Host": "127.0.0.1"
158+
},
159+
"origin": "192.168.65.1, 205.198.122.37",
160+
"url": "http://127.0.0.1/get"
161+
}
162+
```
163+
164+
## Delete plugin
165+
166+
To remove the 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.
167+
168+
```shell
169+
curl "http://127.0.0.1:9180/apisix/admin/routes/attach-consumer-label-route" -X PUT \
170+
-H "X-API-KEY: ${ADMIN_API_KEY}" \
171+
-d '{
172+
"uri": "/get",
173+
"upstream": {
174+
"type": "roundrobin",
175+
"nodes": {
176+
"httpbin.org:80": 1
177+
}
178+
}
179+
}'
180+
```

‎docs/zh/latest/config.json‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -81,7 +81,8 @@
8181
"plugins/grpc-transcode",
8282
"plugins/grpc-web",
8383
"plugins/fault-injection",
84-
"plugins/mocking"
84+
"plugins/mocking",
85+
"plugins/attach-consumer-label"
8586
]
8687
},
8788
{

0 commit comments

Comments
 (0)