Title: BearerTokenAuthMiddleware: Authorization: Bearer should be the default; legacy header should be opt-in alias · Issue #720 · adcontextprotocol/adcp-client-python · GitHub
Open Graph Title: BearerTokenAuthMiddleware: Authorization: Bearer should be the default; legacy header should be opt-in alias · Issue #720 · adcontextprotocol/adcp-client-python
X Title: BearerTokenAuthMiddleware: Authorization: Bearer should be the default; legacy header should be opt-in alias · Issue #720 · adcontextprotocol/adcp-client-python
Description: Summary BearerTokenAuthMiddleware is named after the spec-canonical RFC 6750 Authorization: Bearer header but ships with a single configurable header_name that defaults to "authorization" and accepts no aliases. Adopters with early clien...
Open Graph Description: Summary BearerTokenAuthMiddleware is named after the spec-canonical RFC 6750 Authorization: Bearer header but ships with a single configurable header_name that defaults to "authorization" and accep...
X Description: Summary BearerTokenAuthMiddleware is named after the spec-canonical RFC 6750 Authorization: Bearer header but ships with a single configurable header_name that defaults to "authorization"...
Opengraph URL: https://github.com/adcontextprotocol/adcp-client-python/issues/720
X: @github
Domain: github.com
{"@context":"https://schema.org","@type":"DiscussionForumPosting","headline":"BearerTokenAuthMiddleware: Authorization: Bearer should be the default; legacy header should be opt-in alias","articleBody":"## Summary\n\n``BearerTokenAuthMiddleware`` is named after the spec-canonical RFC 6750 ``Authorization: Bearer`` header but ships with a single configurable ``header_name`` that defaults to ``\"authorization\"`` and accepts no aliases. Adopters with early clients sending tokens via a custom header (``x-adcp-auth``, ``X-Api-Key``, etc.) face a forced binary choice during migration: lock the middleware to the legacy header (breaks every spec-compliant new client, including ``@adcp/sdk`` ``comply()``'s api_key probe path) OR switch to ``Authorization: Bearer`` (breaks every early adopter still on the legacy header).\n\nThe right model is: **``Authorization: Bearer`` is always accepted (the spec-canonical default), legacy aliases are an opt-in additive list.** Both work simultaneously; migration is a one-way drift from legacy clients to spec-compliant ones without flag days.\n\n## Concrete adopter pain (Prebid salesagent)\n\nThe Prebid salesagent ships ``mcp_header_name=\"x-adcp-auth\"`` because early adopters were sending tokens that way before the protocol settled on ``Authorization: Bearer``. Every authenticated MCP call works fine for those clients. But every spec-compliant client — including the SDK's own ``security_baseline`` api_key probe, which sends ``Authorization: Bearer`` per RFC 6750 — gets 401 against the same valid token:\n\n```bash\n$ curl -i -X POST \u003cagent>/mcp \\\n -H \"Authorization: Bearer \u003cTOKEN>\" \\\n -H \"Content-Type: application/json\" -d '\u003cjsonrpc body>'\nHTTP/2 401\nwww-authenticate: Bearer\n{\"error\":\"unauthenticated\"}\n\n$ curl -i -X POST \u003cagent>/mcp \\\n -H \"x-adcp-auth: \u003cTOKEN>\" \\\n -H \"Content-Type: application/json\" -d '\u003cjsonrpc body>'\nHTTP/2 200\n```\n\nNet consequence: the salesagent fails the ``security_baseline/probe_api_key`` and ``assert_mechanism`` storyboard steps despite having RFC-correct auth — its auth path simply doesn't read the spec header. Filed locally as ``bokelley/salesagent#386`` with a wrapper-middleware workaround that normalizes ``Authorization: Bearer`` → ``x-adcp-auth`` before delegating to ``BearerTokenAuthMiddleware``. Every adopter mid-migration is going to write the same wrapper.\n\n## Proposed API\n\nReplace the singular ``header_name: str`` with a list shape, with ``Authorization: Bearer`` baked in as always-accepted (cannot be turned off — it's the spec, and it's the class's own name).\n\n```python\nclass BearerTokenAuthMiddleware(BaseHTTPMiddleware):\n def __init__(\n self,\n app: Any,\n *,\n validate_token: TokenValidator,\n unauthenticated_response: dict[str, Any] | None = None,\n # NEW: opt-in additional aliases for legacy clients. The\n # spec-canonical ``Authorization: Bearer ...`` is ALWAYS\n # accepted; this is purely additive.\n legacy_header_aliases: list[str] | None = None,\n # NEW: bearer_prefix_required applies only to the legacy\n # aliases (``Authorization`` is RFC 6750 — always requires\n # the ``Bearer `` prefix).\n legacy_aliases_bearer_prefix_required: bool = False,\n ) -> None: ...\n```\n\nPre-request resolution order:\n1. ``Authorization: Bearer \u003ctoken>`` (RFC 6750 §2.1) — always checked first.\n2. Each entry in ``legacy_header_aliases`` in order — first non-empty wins.\n3. Missing / empty → 401.\n\nAdopters with strict requirements can pin a single header by passing ``legacy_header_aliases=None`` (default) — they get spec-canonical only. Adopters migrating clients add ``legacy_header_aliases=[\"x-adcp-auth\"]`` and both paths work simultaneously.\n\n## Backward-compat strategy\n\nThe existing ``header_name`` / ``bearer_prefix_required`` params should be:\n\n1. **Deprecated** with a ``DeprecationWarning`` on construction. Map to the new shape internally — passing ``header_name=\"x-adcp-auth\"`` produces ``legacy_header_aliases=[\"x-adcp-auth\"]`` AND keeps ``Authorization: Bearer`` accepted (this is the **behaviour change**: legacy header config currently EXCLUDES the canonical header; the new shape makes them ADDITIVE).\n\n2. **Removed in the next major** (6.0 / 7.0 depending on release cadence).\n\nThe behaviour change is a strict improvement for every adopter — no one wants to actively reject the spec-canonical header on a middleware named ``BearerTokenAuth``. But it deserves a major-bump entry in the changelog because adopters who relied on header_name acting as an EXCLUSIVE filter (likely zero, but possible) will see ``Authorization: Bearer`` start arriving.\n\n## Why ``WWW-Authenticate: Bearer`` already says so\n\nThe 401 response already advertises ``WWW-Authenticate: Bearer`` (per adcp-client-python#712 once that ships, or already in ``_send_unauthenticated`` for the ASGI path). The middleware is telling buyers \"send me a Bearer token\" while only accepting it on a non-standard header. That's the inconsistency this issue resolves.\n\n## Migration shape for adopters\n\nToday (broken for spec-compliant clients):\n\n```python\nBearerTokenAuth(\n validate_token=...,\n mcp_header_name=\"x-adcp-auth\",\n mcp_bearer_prefix_required=False,\n)\n```\n\nAfter this issue ships (works for both legacy and spec clients):\n\n```python\nBearerTokenAuth(\n validate_token=...,\n legacy_header_aliases=[\"x-adcp-auth\"],\n)\n```\n\nAdopters who never had legacy clients (greenfield deployments) drop the kwarg entirely and inherit pure spec compliance.\n\n## Tests\n\nThe upstream test suite for ``BearerTokenAuthMiddleware`` already covers the single-header path. New tests:\n\n- ``Authorization: Bearer X`` accepted by default (no legacy_header_aliases configured)\n- Legacy alias accepted when ``Authorization: Bearer`` absent\n- ``Authorization: Bearer`` wins when both headers present with different tokens (or hand the divergence to a downstream audit hook — same shape as the existing dual-credential audit story).\n- Empty ``Authorization`` value falls through to legacy aliases (not auto-401).\n- Deprecation warning fires on ``header_name=`` construction.\n\n## Severity / urgency\n\nSpec compliance. Not security-critical (the agent still rejects unauthenticated requests correctly via the legacy header path), but every adopter that exposes its endpoint to spec-compliant buyer clients sees gratuitous 401s on calls that carry valid credentials. Compliance probe surfaces it as ``security_baseline/probe_api_key`` failure.\n\n## Related\n\n- adcp-client-python#712 — adjacent ``BearerTokenAuthMiddleware`` defect (``WWW-Authenticate`` header omitted on 401). Same module, same auth path.\n- adcp-client-python#714 — same \"upstream-vs-local workaround\" pattern for ``IdempotencyStore.wrap``.\n- bokelley/salesagent#386 — local workaround (wrapper middleware that normalizes ``Authorization: Bearer`` → ``x-adcp-auth``). Will be deleted when this issue ships.\n\n🤖 Generated with [Claude Code](https://claude.com/claude-code)","author":{"url":"https://github.com/bokelley","@type":"Person","name":"bokelley"},"datePublished":"2026-05-13T11:31:41Z","url":"https://github.com/adcontextprotocol/adcp-client-python/issues/720"}
| react-profiling | 0 |
| react-import-map | react,react-dom,react-dom/client,react-dom/profiling,react-is,react/compiler-runtime,react/jsx-dev-runtime,react/jsx-runtime,scheduler@b8488ee2c322 |
| route-pattern | /_view_fragments/issues/show/:user_id/:repository/:id/issue_layout(.:format) |
| route-controller | voltron_issues_fragments |
| route-action | issue_layout |
| fetch-nonce | v2:b898fadc-d345-0043-128b-cf9012e8209b |
| current-catalog-service-hash | 81bb79d38c15960b92d99bca9288a9108c7a47b18f2423d0f6438c5b7bcd2114 |
| request-id | 96DA:65478:C90BEA:10C9449:6B00F976 |
| html-safe-nonce | 0fe77ee6ececc8e4abcb95dcd2cf65532d6e52944591dbb2320414f723e7d343 |
| visitor-payload | eyJyZWZlcnJlciI6IiIsInJlcXVlc3RfaWQiOiI5NkRBOjY1NDc4OkM5MEJFQToxMEM5NDQ5OjZCMDBGOTc2IiwidmlzaXRvcl9pZCI6IjE3MzA2NDg4MTg3OTEyODMwNjIiLCJyZWdpb25fZWRnZSI6ImlhZCIsInJlZ2lvbl9yZW5kZXIiOiJpYWQifQ== |
| visitor-hmac | e97db10ee11ecaae9b657ce5adc43a890da6853b0eec71d1da39e25a00952758 |
| hovercard-subject-tag | issue:4437467877 |
| github-keyboard-shortcuts | repository,issues,copilot |
| google-site-verification | Apib7-x98H0j5cPqHWwSMm6dNU4GmODRoqxLiDzdx9I |
| octolytics-url | https://collector.github.com/github/collect |
| analytics-location | / |
| fb:app_id | 1401488693436528 |
| apple-itunes-app | app-id=1477376905, app-argument=https://github.com/_view_fragments/issues/show/adcontextprotocol/adcp-client-python/720/issue_layout |
| twitter:image | https://opengraph.githubassets.com/86cba4ca9d8793e6fa34f48856f748fa62a11095808e9b861cfd844e1a213e09/adcontextprotocol/adcp-client-python/issues/720 |
| twitter:card | summary_large_image |
| og:image | https://opengraph.githubassets.com/86cba4ca9d8793e6fa34f48856f748fa62a11095808e9b861cfd844e1a213e09/adcontextprotocol/adcp-client-python/issues/720 |
| og:image:alt | Summary BearerTokenAuthMiddleware is named after the spec-canonical RFC 6750 Authorization: Bearer header but ships with a single configurable header_name that defaults to "authorization" and accep... |
| og:image:width | 1200 |
| og:image:height | 600 |
| og:site_name | GitHub |
| og:type | object |
| og:author:username | bokelley |
| hostname | github.com |
| expected-hostname | github.com |
| None | e208d86428ec00a57ade75058166297440e8128a01e5287c31a53dc042bbf187 |
| turbo-cache-control | no-preview |
| go-import | github.com/adcontextprotocol/adcp-client-python git https://github.com/adcontextprotocol/adcp-client-python.git |
| octolytics-dimension-user_id | 221690821 |
| octolytics-dimension-user_login | adcontextprotocol |
| octolytics-dimension-repository_id | 1090305973 |
| octolytics-dimension-repository_nwo | adcontextprotocol/adcp-client-python |
| octolytics-dimension-repository_public | true |
| octolytics-dimension-repository_is_fork | false |
| octolytics-dimension-repository_network_root_id | 1090305973 |
| octolytics-dimension-repository_network_root_nwo | adcontextprotocol/adcp-client-python |
| turbo-body-classes | logged-out env-production page-responsive |
| disable-turbo | false |
| browser-stats-url | https://api.github.com/_private/browser/stats |
| browser-errors-url | https://api.github.com/_private/browser/errors |
| release | 7dafd017fb7809a839c443dba08622af38e63c09 |
| ui-target | full |
| theme-color | #1e2327 |
| color-scheme | light dark |
| react-app-name | issues |
Links:
Viewport: width=device-width