Skip to content

feat(forward-auth): support attaching consumer by response header#13268

Open
panxiaoquan wants to merge 1 commit intoapache:masterfrom
panxiaoquan:attach-consumer
Open

feat(forward-auth): support attaching consumer by response header#13268
panxiaoquan wants to merge 1 commit intoapache:masterfrom
panxiaoquan:attach-consumer

Conversation

@panxiaoquan
Copy link
Copy Markdown

@panxiaoquan panxiaoquan commented Apr 21, 2026

Description

This PR extends the forward-auth plugin to support attaching an existing APISIX Consumer from a
successful authorization response header.

Today, forward-auth can forward request headers to the auth service and propagate selected response
headers back to the upstream or client, but it cannot turn a successful auth response into APISIX
Consumer context. That means Consumer-scoped plugins and Consumer Group plugins cannot participate in
requests authenticated by an external auth service.

This change adds an opt-in consumer_header attribute to forward-auth. When it is configured and the
auth service returns a 2xx response, APISIX reads the configured response header as a Consumer
username, looks up the existing Consumer locally, and attaches it to the current request. This allows
downstream Consumer-related plugins to work with forward-auth-authenticated traffic.

The implementation also moves the auth execution into rewrite and uses ctx.forward_auth_processed to
avoid running the auth flow twice in access. This keeps the request authenticated once while making the
attached Consumer available early enough for Consumer plugins to take effect.

Behavior on invalid auth-to-consumer mapping is explicit:

  • If the configured response header is missing, APISIX returns 403.
  • If the referenced Consumer does not exist, APISIX returns 403.

Additional changes included in this PR:

  • Expose a helper in apisix.consumer to fetch an existing Consumer by name from local cache.
  • Add English and Chinese documentation for the new consumer_header attribute and example usage.
  • Add plugin tests covering schema validation, successful Consumer attachment, execution of Consumer
    plugins after attachment, missing header, and unknown Consumer.
  • Add a .luarc.json workspace config to improve local LuaLS path/global resolution for development.

Checklist

  • I have explained the need for this PR and the problem it solves
  • I have explained the changes or the new features added to this PR
  • I have added tests corresponding to this change
  • I have updated the documentation to reflect this change
  • I have verified that this change is backward compatible (If not, please discuss on the APISIX
    mailing list
    first)

@dosubot dosubot Bot added size:L This PR changes 100-499 lines, ignoring generated files. enhancement New feature or request labels Apr 21, 2026
@panxiaoquan panxiaoquan force-pushed the attach-consumer branch 2 times, most recently from 2dd4fe9 to 7721b19 Compare April 21, 2026 07:51
Comment thread apisix/plugins/forward-auth.lua Outdated
-- if header_value is nil, the client header's value will be removed if it exists
core.request.set_header(ctx, header, header_value)
if header_value then
core.request.set_header(ctx, header, header_value)
Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

upstream_headers security regression: The original code intentionally clears client-supplied headers when the auth response does not include a configured upstream header (prevents header spoofing). The new if header_value then guard in the loop breaks this behavior — a malicious client can now inject headers that the upstream trusts (e.g., X-User-Id). Please revert to the original unconditional set_header logic.

Copy link
Copy Markdown
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Fixed in latest commit.

Comment thread apisix/plugins/forward-auth.lua
@panxiaoquan panxiaoquan force-pushed the attach-consumer branch 2 times, most recently from 703c48c to a307236 Compare April 28, 2026 03:17
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

enhancement New feature or request size:L This PR changes 100-499 lines, ignoring generated files.

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants