ADR 0005: Where MCP OAuth Tokens Are Validated¶
Status¶
Accepted
Amended 2026-10-20: the recommended networked mode below is now
implemented as the opt-in DRUPAL_OAUTH_DELEGATE
(auth/delegation.py) — proxy delegation for issuance, with local
JWKS validation or RFC 7662 introspection for presented tokens. The
default posture is unchanged: in-process, no Drupal reachable.
Amended 2026-10-21: delegate mode is walked end to end over real
sockets (tests/integration/test_oauth_delegation_roundtrip.py) —
the console script in delegate posture, a client through discovery,
DCR, the consent screen, both code exchanges, and a JWKS-validated
bearer call against a spec-conformant stub upstream; the outbound
client-credentials probe lands on the same stub. Drupal's own
simple_oauth module stays unexercised here (no site in this
environment), so its conformance remains the live gap.
Date¶
2026-10-19
Context¶
ADR 0004 introduced DrupalOAuthProvider for HTTP transport. An audit of
the OAuth surface (2026-10-19) established what actually happens:
get_mcp_oauth_provider()passesDRUPAL_OAUTH_CLIENT_ID,DRUPAL_OAUTH_CLIENT_SECRETandDRUPAL_OAUTH_TOKEN_URLinto the provider, which stores them as_drupal_client_id,_drupal_client_secretand_drupal_token_url— and never reads them again.- Authorization codes and access tokens are generated in process:
authorize()/exchange_authorization_code()self-issue, andload_access_token()validates against an in-memory dict. Nothing calls Drupal to authorize an MCP client, despite the docstrings that say "redirect to Drupal OAuth". - The same three settings do a separate, real job: the outbound
client-credentials leg (
AuthManager._fetch_oauth_tokenPOSTsgrant_type=client_credentialstoDRUPAL_OAUTH_TOKEN_URLso tool calls carry a bearer to Drupal). - Consequences of the in-process half: tokens die with the process
(a multi-worker deployment would reject its own siblings), Drupal-side
revocation and roles never reach the MCP side, and the
ROLE_SCOPEStable plusget_role_scopes()are decorative — nothing assigns a role. - The session-scope custom routes (
/mcp/scopes,/mcp/roles,/mcp/session/{id}/scopes) readmcp._oauth_provider, an attribute FastMCP never sets, so they answer 500 today. Wiring them tomcp.authinstead would activate an unauthenticated scope-mutation route, so they must not be "fixed" blindly. - Enforcement itself is real, and now tested at three layers: unit (issue / exchange / refresh / replay), ASGI integration (401 unauthenticated, 200 issued, 401 forged, 403 missing scope), and a real socket (discovery 200, unauthenticated 401 carrying the production scope challenge).
Decision¶
Serve the in-process authorization server as the default, and document the credential split honestly:
DRUPAL_OAUTH_CLIENT_IDis the HTTP-transport guard's deliberate-intent switch; the enforcement it gates is FastMCP's bearer middleware, not Drupal.DRUPAL_OAUTH_CLIENT_SECRET/DRUPAL_OAUTH_TOKEN_URLbelong to the outbound client-credentials leg.- No code path claims Drupal delegation unless the operator opts in
via
DRUPAL_OAUTH_DELEGATE, which serves the proxy pattern below; the_drupal_*attributes,ROLE_SCOPESand the_oauth_providerroutes are recorded as follow-up — remove or wire, never wire without an auth decision. - Dynamic client registration is enabled (
ClientRegistrationOptions) so spec-conformant clients can complete discovery → registration → authorize → token over the wire. A live probe on 2026-10-19 had shown/registerunmounted and the client registry unpopulatable, so no client could obtain a token at all. Registration proves the caller speaks OAuth, not who the user is.
When a multi-user networked deployment needs Drupal-side identity, pick
one of (all three are now implemented; DRUPAL_OAUTH_DELEGATE selects
delegation, DRUPAL_OAUTH_INTROSPECTION_URL switches validation):
- Introspection — validate presented tokens at Drupal's
/oauth/token/introspect(simple_oauth). Only works for tokens Drupal issued, so issuance must delegate too, and each validation is a network hop (cacheable). - Proxy delegation — FastMCP's OAuth proxy pattern: MCP clients keep standard discovery/DCR/PKCE against us, while authorize/token requests are forwarded to Drupal's simple_oauth AS. Needs the module enabled and an OAuth client registered in Drupal.
- JWT verification — Drupal signs access tokens; validate the signature via JWKS locally. No per-request hop; revocation lands at token TTL instead of immediately.
Recommended for that mode: proxy delegation for issuance plus local JWT verification, with introspection as the fallback. None of it is required for the default posture — stdio, or loopback HTTP behind the guard.
Consequences¶
Positive¶
- The served default works with no Drupal reachable and no extra modules enabled.
- Documentation and the guard's refusal message match observed behaviour; the credential split is explicit.
- Enforcement is pinned by tests at three layers, including the production scope requirement over a real socket.
- The delegated posture is pinned over real sockets against a stub upstream: the proxy machinery is proven, and the honest boundary (Drupal's simple_oauth module itself, unexercised here) is recorded.
Negative¶
- MCP tokens cannot be revoked from Drupal, and roles never influence scopes — by design until delegation is chosen.
- Multi-worker HTTP deployments are unsupported (per-process token dicts).
- Dead scaffolding (
_drupal_*,ROLE_SCOPES, session routes) remains until its follow-up lands.
Alternatives Considered¶
- Delegate to Drupal now — rejected for the default: couples startup to site reachability and the simple_oauth module, and breaks offline local use, which is the primary mode.
- A dedicated guard flag (
MCP_REQUIRE_AUTH) — rejected as a parallel knob;DRUPAL_OAUTH_CLIENT_IDalready marks the deliberate intent and is the setting operators know. - Leave the documentation vague — rejected: "OAuth is configured" implied Drupal-validated tokens that do not exist.