feat: add plugin attach-consmer-label (#11604)

apisix/cli/config.lua

@@ -208,6 +208,7 @@ local _M = {
     "jwe-decrypt",
     "key-auth",
     "consumer-restriction",
+    "attach-consumer-label",
     "forward-auth",
     "opa",
     "authz-keycloak",

apisix/plugins/attach-consumer-label.lua

@@ -0,0 +1,68 @@
+--
+-- 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 core = require("apisix.core")
+local pairs = pairs
+local plugin_name = "attach-consumer-label"
+
+local schema = {
+    type = "object",
+    properties = {
+        headers = {
+            type = "object",
+            additionalProperties = {
+                type = "string",
+                pattern = "^\\$.*"
+            },
+            minProperties = 1
+        },
+    },
+    required = {"headers"},
+}
+
+local _M = {
+    version = 0.1,
+    priority = 2399,
+    name = plugin_name,
+    schema = schema,
+}
+
+function _M.check_schema(conf)
+    return core.schema.check(schema, conf)
+end
+
+function _M.before_proxy(conf, ctx)
+    -- check if the consumer is exists in the context
+    if not ctx.consumer then
+        return
+    end
+
+    local labels = ctx.consumer.labels
+    core.log.info("consumer username: ", ctx.consumer.username, " labels: ",
+            core.json.delay_encode(labels))
+    if not labels then
+        return
+    end
+
+    for header, label_key in pairs(conf.headers) do
+        -- remove leading $ character
+        local label_value = labels[label_key:sub(2)]
+        core.request.set_header(ctx, header, label_value)
+    end
+end
+
+return _M

conf/config.yaml.example

@@ -470,6 +470,7 @@ plugins:                           # plugin list (sorted by priority)
   - jwe-decrypt                    # priority: 2509
   - key-auth                       # priority: 2500
   - consumer-restriction           # priority: 2400
+  - attach-consumer-label          # priority: 2399
   - forward-auth                   # priority: 2002
   - opa                            # priority: 2001
   - authz-keycloak                 # priority: 2000

docs/en/latest/config.json

@@ -98,7 +98,8 @@
             "plugins/mocking",
             "plugins/degraphql",
             "plugins/body-transformer",
-            "plugins/ai-proxy"
+            "plugins/ai-proxy",
+            "plugins/attach-consumer-label"
           ]
         },
         {

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

@@ -0,0 +1,180 @@
+---
+title: attach-consumer-label
+keywords:
+  - Apache APISIX
+  - API Gateway
+  - API Consumer
+description: This article describes the Apache APISIX attach-consumer-label plugin, which you can use to pass custom consumer labels to upstream services.
+---
+
+<!--
+#
+# 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.
+#
+-->
+
+## Description
+
+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.
+
+## Attributes
+
+| Name     | Type   | Required | Default | Valid values | Description                                                                                                                                                                                                                                                                                                                                                                                                     |
+|----------|--------|----------|---------|--------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| 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. |
+
+## Enable Plugin
+
+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.
+
+:::note
+
+You can fetch the `admin_key` from `config.yaml` and save to an environment variable with the following command:
+
+```bash
+admin_key=$(yq '.deployment.admin.admin_key[0].key' conf/config.yaml | sed 's/"//g')
+```
+
+:::
+
+Create a consumer `john` with custom labels:
+
+```shell
+curl "http://127.0.0.1:9180/apisix/admin/consumers" -X PUT \
+  -H "X-API-KEY: ${ADMIN_API_KEY}" \
+  -d '{
+    "username": "john",
+    # highlight-start
+    "labels": {
+      // Annotate 1
+      "department": "devops",
+      // Annotate 2
+      "company": "api7"
+    }
+    # highlight-end
+  }'
+```
+
+❶ Label the `department` information for the consumer.
+
+❷ Label the `company` information for the consumer.
+
+Configure the `key-auth` credential for the consumer `john`:
+
+```shell
+curl "http://127.0.0.1:9180/apisix/admin/consumers/john/credentials" -X PUT \
+  -H "X-API-KEY: ${ADMIN_API_KEY}" \
+  -d '{
+    "id": "cred-john-key-auth",
+    "plugins": {
+      "key-auth": {
+        "key": "john-key"
+      }
+    }
+  }'
+```
+
+Create a route enabling the `key-auth` and `attach-consumer-label` plugins:
+
+```shell
+curl "http://127.0.0.1:9180/apisix/admin/routes" -X PUT \
+  -H "X-API-KEY: ${ADMIN_API_KEY}" \
+  -d '{
+    "id": "attach-consumer-label-route",
+    "uri": "/get",
+    "plugins": {
+      "key-auth": {},
+      # highlight-start
+      "attach-consumer-label": {
+        "headers": {
+          // Annotate 1
+          "X-Consumer-Department": "$department",
+          // Annotate 2
+          "X-Consumer-Company": "$company",
+          // Annotate 3
+          "X-Consumer-Role": "$role"
+        }
+      }
+      # highlight-end
+    },
+    "upstream": {
+      "type": "roundrobin",
+      "nodes": {
+        "httpbin.org:80": 1
+      }
+    }
+  }'
+```
+
+❶ Attach the `department` consumer label value in the `X-Consumer-Department` request header.
+
+❷ Attach the `company` consumer label value in the `X-Consumer-Company` request header.
+
+❸ 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.
+
+:::tip
+
+The consumer label references must be prefixed by a dollar sign (`$`).
+
+:::
+
+To verify, send a request to the route with the valid credential:
+
+```shell
+curl -i "http://127.0.0.1:9080/get" -H 'apikey: john-key'
+```
+
+You should see an `HTTP/1.1 200 OK` response similar to the following:
+
+```text
+{
+  "args": {},
+  "headers": {
+    "Accept": "*/*",
+    "Apikey": "john-key",
+    "Host": "127.0.0.1",
+    # highlight-start
+    "X-Consumer-Username": "john",
+    "X-Credential-Indentifier": "cred-john-key-auth",
+    "X-Consumer-Company": "api7",
+    "X-Consumer-Department": "devops",
+    # highlight-end
+    "User-Agent": "curl/8.6.0",
+    "X-Amzn-Trace-Id": "Root=1-66e5107c-5bb3e24f2de5baf733aec1cc",
+    "X-Forwarded-Host": "127.0.0.1"
+  },
+  "origin": "192.168.65.1, 205.198.122.37",
+  "url": "http://127.0.0.1/get"
+}
+```
+
+## Delete plugin
+
+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.
+
+```shell
+curl "http://127.0.0.1:9180/apisix/admin/routes/attach-consumer-label-route" -X PUT \
+  -H "X-API-KEY: ${ADMIN_API_KEY}" \
+  -d '{
+    "uri": "/get",
+    "upstream": {
+      "type": "roundrobin",
+      "nodes": {
+        "httpbin.org:80": 1
+      }
+    }
+  }'
+```

docs/zh/latest/config.json

@@ -81,7 +81,8 @@
             "plugins/grpc-transcode",
             "plugins/grpc-web",
             "plugins/fault-injection",
-            "plugins/mocking"
+            "plugins/mocking",
+            "plugins/attach-consumer-label"
           ]
         },
         {