attach-consumer-label

Adds the consumer's labels to request headers for the upstream.

Category TransformationAdd it to Route, Service, Consumer, Consumer group, Global rule, Plugin configEngine plugin attach-consumer-labelPriority 2399

What it does

attach-consumer-label passes the labels of the calling consumer to the backend as request headers. Under Headers, each header name is paired with a dollar sign and the name of a label, for example X-Consumer-Plan with $plan. The labels are the ones set on the consumer under Labels.

It reads the consumer that an authentication plugin on the same route, key-auth in the example, has named. Authentication shows how a request comes to belong to a consumer. A header named here is taken off the request when no consumer signed in, so a client cannot send its own copy.

When to use it

• The backend of the orders API serves each plan differently and should read the caller's plan from one header, set on the consumer once rather than looked up on every call.
• A backend keeps its own count per team and reads the team from a label on the consumer, set once when the consumer is created.
• Partners and your own apps call the same route, and the backend should know which kind of client it answers without a second lookup.
• A backend must trust a header that names the client's tier, so the value has to come from the gateway and never from the client.

Not for letting a consumer through or refusing it by its labels — see acl (Allows or denies consumers by the labels they carry), headers set by rules on the request itself, its address or its headers, whoever calls — see traffic-label (Labels requests for later plugins by match rules) or the same fixed headers on every request a route takes — see proxy-rewrite (Rewrites the request URI, method, host and headers before proxying).

Set it up

Tell the backend which plan the calling consumer is on

Needs an authentication plugin on the same route; the value is the label plan of the consumer that signed in, and a consumer without that label sends no header.

Fill Headers as in the JSON below.

attach-consumer-label · as the console saves it

{
  "headers": {
    "X-Consumer-Plan": "$plan"
  }
}

Things to know

• Headers — A consumer labelled plan with gold that signs in with its key reaches the backend with X-Consumer-Plan set to gold.
• Headers — A name here is taken off the request when the consumer carries no such label, and when no consumer signed in at all, so a client cannot send its own copy of it.
• Headers — A value without the dollar sign, tier alone for example, is refused when you save.
• Headers — At least one header is needed: an empty set is refused when you save.
• Headers — A consumer that carries no plan label sends no X-Consumer-Plan header to the backend, and no client can send one in its place.
• AdviceGive every header this plugin writes one prefix, as X-Consumer-Plan does, so the backend reads them apart from the headers clients send.

Settings

The fields as the console shows them, section by section.

HeadersheadersobjectRequired

Each value is a dollar sign and the name of a label the consumer carries. An object whose keys are a name matching ^.+$, each with a string as its value.

at least 1 key

Every plugin also has Enabled, Priority, Filter, Error response and Pre-function: see Plugin execution settings.