fix: serve RFC 9728 path-suffixed metadata, document connector redirect URIs

Two separate discovery footguns, both found while debugging an Authentik "Redirect URI Error" on a claude.ai custom connector. RFC 9728 §3.1 puts the metadata for a resource identified by `https://host/api/mcp` at `/.well-known/oauth-protected-resource/api/mcp`. Only the root form was served, so clients that derive the metadata URL from the MCP endpoint URL — rather than reading `resource_metadata` off our 401 — got Next.js's HTML 404 and failed discovery with a JSON parse error. Add a `[...path]` route serving the same document with `resource` naming the suffixed identifier (§3.3 has the client compare it as an exact string, so echoing the bare origin would be rejected). The document body moves to `lib/auth/resource-metadata.ts` so the two routes cannot drift apart on `scopes_supported` — a divergence there costs you the `aud` claim or the refresh token. Paths are allowlisted rather than wildcarded so this cannot advertise resources the app does not serve. `buildWwwAuthenticate()` still points at the root URL; this change is purely additive. Separately, the redirect URIs an MCP provider needs depend on how clients reach it: a loopback URI for the CLI, `https://claude.ai/api/mcp/auth_callback` for a claude.ai custom connector. Registering only the former is what produces the "Redirect URI Error" page, and a portless `http://localhost/callback` entry matches nothing the CLI sends. Document both, keyed on the literal error text, and note that DCR is enterprise-gated on Authentik so these are hand-registered on a FOSS instance. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
2026-09-16 16:08:06 -07:00
parent c68d72857f
commit 29f5673eac
7 changed files with 324 additions and 38 deletions
@@ -0,0 +1,86 @@
+import { afterEach, describe, expect, test, vi } from "vitest";
+
+/**
+ * RFC 9728 §3.1 puts the metadata for `https://host/api/mcp` at
+ * `https://host/.well-known/oauth-protected-resource/api/mcp`. MCP clients
+ * that derive that URL from the endpoint URL — instead of following the
+ * `resource_metadata` parameter on our 401 — used to receive the Next.js 404
+ * HTML page here, so discovery died on a JSON parse error.
+ *
+ * Two things therefore have to hold, and both are easy to break silently:
+ * the document must name the SUFFIXED resource (§3.3 has the client reject a
+ * document whose `resource` isn't the identifier it asked about), and it must
+ * stay byte-for-byte in step with the root document's scope list, because a
+ * scope missing from whichever document a given client reads is a scope that
+ * client will never request.
+ */
+
+type Metadata = { resource: string; scopes_supported: string[] };
+
+async function fetchSuffixed(
+  segments: string[],
+): Promise<{ status: number; body: Metadata }> {
+  vi.resetModules();
+  const { GET } = await import(
+    "@/app/.well-known/oauth-protected-resource/[...path]/route"
+  );
+  const res = await GET(new Request("http://localhost/ignored"), {
+    params: Promise.resolve({ path: segments }),
+  });
+  return { status: res.status, body: (await res.json()) as Metadata };
+}
+
+async function fetchRoot(): Promise<Metadata> {
+  vi.resetModules();
+  const { GET } = await import("@/app/.well-known/oauth-protected-resource/route");
+  return (await GET().json()) as Metadata;
+}
+
+afterEach(() => {
+  delete process.env.OIDC_OFFLINE_ACCESS;
+  delete process.env.OIDC_AUDIENCE_SCOPE;
+});
+
+describe("path-suffixed oauth-protected-resource metadata", () => {
+  test("serves the MCP endpoint's document with the suffixed resource identifier", async () => {
+    const { status, body } = await fetchSuffixed(["api", "mcp"]);
+
+    expect(status).toBe(200);
+    // §3.3: a strict client compares this against the identifier it asked
+    // about, so the bare origin would get the whole document rejected.
+    expect(body.resource).toBe("http://localhost:3000/api/mcp");
+  });
+
+  test("404s for a path this app does not serve, rather than advertising it", async () => {
+    // The allowlist exists so we never claim that arbitrary paths are
+    // OAuth-protected resources of this deployment.
+    const { status } = await fetchSuffixed(["api", "not-mcp"]);
+
+    expect(status).toBe(404);
+  });
+
+  test("advertises exactly the scopes the root document does", async () => {
+    // Regression guard against the two documents drifting apart: the audience
+    // scope is what makes `aud` appear on the token at all, and a client that
+    // discovered us through the suffixed URL would never request a scope that
+    // only the root document lists.
+    process.env.OIDC_OFFLINE_ACCESS = "true";
+
+    const root = await fetchRoot();
+    const { body: suffixed } = await fetchSuffixed(["api", "mcp"]);
+
+    expect(suffixed.scopes_supported).toEqual(root.scopes_supported);
+    expect(suffixed.scopes_supported).toContain("aud-test-audience");
+    expect(suffixed.scopes_supported).toContain("offline_access");
+  });
+
+  test("honours an explicit audience scope name, like the root document", async () => {
+    process.env.OIDC_AUDIENCE_SCOPE = "custom-aud-scope";
+
+    const root = await fetchRoot();
+    const { body: suffixed } = await fetchSuffixed(["api", "mcp"]);
+
+    expect(suffixed.scopes_supported).toContain("custom-aud-scope");
+    expect(suffixed.scopes_supported).toEqual(root.scopes_supported);
+  });
+});
@@ -0,0 +1,60 @@
+import { NextResponse } from "next/server";
+import { buildResourceMetadata, publicOrigin } from "@/lib/auth/resource-metadata";
+
+export const runtime = "nodejs";
+export const dynamic = "force-dynamic";
+
+/**
+ * Resource paths this deployment will publish metadata for.
+ *
+ * An allowlist rather than a wildcard, for two reasons. RFC 9728 §3.1 maps a
+ * metadata URL to one specific protected resource, so answering for arbitrary
+ * paths would advertise resources this app does not serve — a client could
+ * "discover" `https://host/anything` as an OAuth-protected resource and be
+ * told, wrongly, that tokens for it are obtainable from our IdP. And every
+ * path that answers is surface: a wildcard turns this into an open reflector
+ * that echoes attacker-chosen path segments back inside a JSON document.
+ *
+ * `api/mcp` is the only MCP endpoint here (app/api/mcp/route.ts). Add an
+ * entry when a second one ships — not before.
+ */
+const METADATA_RESOURCE_PATHS: ReadonlySet<string> = new Set(["api/mcp"]);
+
+/**
+ * RFC 9728 §3.1 — path-suffixed protected resource metadata.
+ *
+ * For a resource identified by `https://host/api/mcp`, the spec puts its
+ * metadata at `https://host/.well-known/oauth-protected-resource/api/mcp`:
+ * the resource's path is appended to the well-known path. Clients that derive
+ * the metadata URL from the MCP endpoint URL — rather than reading
+ * `resource_metadata` off our 401's `WWW-Authenticate` header — probe that URL
+ * first, and before this route existed they got Next.js's 404 HTML page, which
+ * fails discovery with a JSON parse error rather than anything diagnosable.
+ *
+ * The document is identical to the root one except for `resource`, which must
+ * name the suffixed identifier: §3.3 requires the client to check that the
+ * returned `resource` equals the identifier it asked about, so echoing the
+ * bare origin here would make a strict client reject the document outright.
+ */
+export async function GET(
+  _req: Request,
+  ctx: { params: Promise<{ path: string[] }> },
+): Promise<NextResponse> {
+  const { path } = await ctx.params;
+  // Segments arrive already percent-decoded and never empty, but join and
+  // compare on the same normalized form the allowlist is written in.
+  const resourcePath = path.join("/");
+
+  if (!METADATA_RESOURCE_PATHS.has(resourcePath)) {
+    // JSON, not the HTML 404 page, so a client that probes a wrong path gets
+    // a parseable answer instead of the failure mode this route exists to fix.
+    return NextResponse.json(
+      { error: "not_found", error_description: "no such protected resource" },
+      { status: 404 },
+    );
+  }
+
+  return NextResponse.json(
+    buildResourceMetadata(`${publicOrigin()}/${resourcePath}`),
+  );
+}