attach-consumer-label

The attach-consumer-label plugin attaches custom consumer-related labels, in addition to X-Consumer-Username and X-Credential-Identifier, to authenticated requests. The plugin clears each configured header before resolving its label so that a client-supplied value cannot be forwarded as a consumer label. This behavior was introduced in API7 Gateway 3.9.16 and 3.10.2, and in APISIX 3.18.0.

Example

Attach Consumer Labels

The following example demonstrates how you can attach custom labels to request headers before authenticated requests are forwarded to upstream services. If authentication fails, no consumer label is attached. If a configured label reference does not exist on the consumer, its header remains absent even when the client supplied a value with the same name.

Admin API
ADC
Ingress Controller

Create a consumer john with custom labels:

curl "http://127.0.0.1:9180/apisix/admin/consumers" -X PUT \
  -H "X-API-KEY: ${ADMIN_API_KEY}" \
  -d '{
    "username": "john",
    "labels": {
      "department": "devops",
      "company": "api7"
    }
  }'

❶ Label the department information for the consumer.

❷ Label the company information for the consumer.

Configure the key-auth credential for the consumer john:

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:

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": {},
      "attach-consumer-label": {
        "headers": {
          "X-Consumer-Department": "$department",
          "X-Consumer-Company": "$company",
          "X-Consumer-Role": "$role"
        }
      }
    },
    "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.

Create a consumer with custom labels and a route with key-auth and attach-consumer-label plugins:

adc.yaml
consumers:
  - username: john
    labels:
      department: devops
      company: api7
    credentials:
      - name: key-auth
        type: key-auth
        config:
          key: john-key
services:
  - name: attach-consumer-label-service
    routes:
      - name: attach-consumer-label-route
        uris:
          - /get
        plugins:
          key-auth: {}
          attach-consumer-label:
            headers:
              X-Consumer-Department: $department
              X-Consumer-Company: $company
              X-Consumer-Role: $role
    upstream:
      type: roundrobin
      nodes:
        - host: httpbin.org
          port: 80
          weight: 1

❶ Label the department information for the consumer.

❷ Label the company information for the consumer.

Synchronize the configuration to the gateway:

adc sync -f adc.yaml

Create an ApisixConsumer with metadata labels and configure the route plugins through ApisixRoute:

attach-consumer-label.yaml
apiVersion: apisix.apache.org/v2
kind: ApisixConsumer
metadata:
  namespace: aic
  name: john
  labels:
    department: devops
    company: api7
spec:
  ingressClassName: apisix
  authParameter:
    keyAuth:
      value:
        key: john-key
---
apiVersion: apisix.apache.org/v2
kind: ApisixUpstream
metadata:
  namespace: aic
  name: httpbin-external-domain
spec:
  ingressClassName: apisix
  externalNodes:
    - type: Domain
      name: httpbin.org
---
apiVersion: apisix.apache.org/v2
kind: ApisixRoute
metadata:
  namespace: aic
  name: attach-consumer-label-route
spec:
  ingressClassName: apisix
  http:
    - name: get
      match:
        paths:
          - /anything/labels
      upstreams:
        - name: httpbin-external-domain
      plugins:
        - name: key-auth
          config: {}
        - name: attach-consumer-label
          config:
            headers:
              X-Consumer-Department: $department
              X-Consumer-Company: $company
              X-Consumer-Role: $role

Apply the configuration to your cluster:

kubectl apply -f attach-consumer-label.yaml

tip

The consumer label references must be prefixed by a dollar sign ($).

To verify, send a request to the route with the valid credential:

curl -i "http://127.0.0.1:9080/anything/labels" -H 'apikey: john-key'

You should see an HTTP/1.1 200 OK response similar to the following:

{
  "args": {}, 
  "headers": {
    "Accept": "*/*", 
    "Apikey": "john-key", 
    "Host": "127.0.0.1:9080",
    "X-Consumer-Username": "aic_john",
    "X-Consumer-Company": "api7",
    "X-Consumer-Department": "devops",
    "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/anything/labels"
}

Example​

Attach Consumer Labels​

Example

Attach Consumer Labels