From 60cfb19772cbcb763bcb2fe706bcae412a9044b5 Mon Sep 17 00:00:00 2001 From: Josh Knapp Date: Mon, 27 Jul 2026 05:58:56 -0700 Subject: [PATCH] fix: advertise the audience scope so tokens actually carry `aud` MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The OAuth path to /api/mcp has never worked end to end. Every access token arrived without an `aud` claim and jwt.ts rejected it with "claim invalid: aud" (401), even though the handshake, consent and PKCE all succeeded. Only the CLI HMAC path worked, because cli-token.ts sets the audience itself — which is why this went unnoticed. Cause: Authentik evaluates a scope mapping only when the client REQUESTS that scope by name. An MCP client learns which scopes to request from `scopes_supported` in our RFC 9728 protected-resource metadata, and we only advertised openid/profile/email. So the `aud-shared-memory` mapping was attached to the provider but never evaluated. Advertise the audience scope in that metadata. Name is derived as `aud-` to match the README convention, overridable with the new optional OIDC_AUDIENCE_SCOPE for deployments that named it differently. Also documents that Claude Code's RFC 8707 `resource` parameter is ignored by Authentik 2026.5, so it cannot be relied on for audience binding. Co-Authored-By: Claude Opus 5 (1M context) --- .env.example | 6 ++++ README.md | 30 +++++++++++++++---- .../oauth-protected-resource/route.ts | 10 ++++++- apps/web/lib/env.ts | 11 +++++++ 4 files changed, 50 insertions(+), 7 deletions(-) diff --git a/.env.example b/.env.example index b149c68..97c612b 100644 --- a/.env.example +++ b/.env.example @@ -35,6 +35,12 @@ OIDC_CLIENT_ID_WEB=replace-me OIDC_CLIENT_SECRET_WEB=replace-me OIDC_CLIENT_ID_MCP=replace-me OIDC_AUDIENCE=shared-memory +# Scope whose IdP mapping emits `aud: `. Advertised in +# /.well-known/oauth-protected-resource so MCP clients request it — without +# that, Authentik never evaluates the mapping and every token 401s with +# "claim invalid: aud". Defaults to aud-; set only if you +# named the scope mapping something else. +#OIDC_AUDIENCE_SCOPE=aud-shared-memory # ----------------------------------------------------------------------------- # Database (Postgres 16 + pgvector — pgvector/pgvector:pg16 image) diff --git a/README.md b/README.md index 2d77b33..668389f 100644 --- a/README.md +++ b/README.md @@ -144,6 +144,7 @@ Copy `.env.example` and fill in the values below. | `OIDC_CLIENT_SECRET_WEB` | both | Client secret of the Web-UI client. | | `OIDC_CLIENT_ID_MCP` | both | Client ID of the MCP resource-server client in your IdP. | | `OIDC_AUDIENCE` | both | Audience string the MCP access token must carry in its `aud` claim. Recommended: `shared-memory`. | +| `OIDC_AUDIENCE_SCOPE` | optional | Name of the IdP scope whose mapping emits that `aud` claim. Advertised in `scopes_supported` so clients request it. Defaults to `aud-`. | | `POSTGRES_USER` / `POSTGRES_PASSWORD` / `POSTGRES_DB` | both | Local Postgres credentials. | | `NEXTAUTH_SECRET` | both | Session-cookie signing key. Generate with `openssl rand -base64 32`. | | `EMBEDDER_URL` | both | Phase 2 embedder sidecar. Leave empty in Phase 1. | @@ -297,16 +298,33 @@ The MCP endpoint requires the access token's `aud` claim to equal reliable pattern: 1. Create a **scope mapping** (Customisation → Property Mappings → Create → - Scope Mapping) named `aud-shared-memory` with expression: + Scope Mapping) named `aud-shared-memory`, **scope name** `aud-shared-memory`, + with expression: ```python return {"aud": "shared-memory"} ``` -2. On the MCP provider, add this scope mapping under **Scopes** and tick it - so it's emitted for the default scope. +2. On the MCP provider, add this scope mapping under **Scopes**. +3. Make sure the app advertises that scope name. It is derived automatically + as `aud-`; override with `OIDC_AUDIENCE_SCOPE` if you named + the mapping differently. -> If you skip this, the MCP route will return 401 with -> `error_description="claim invalid: aud"`. Check `docker compose logs app` -> for the exact failure. +> **Attaching the mapping is not sufficient.** Authentik evaluates a scope +> mapping only when the client explicitly *requests* that scope, and an MCP +> client only requests the scopes listed in `scopes_supported` from +> `/.well-known/oauth-protected-resource`. If the audience scope isn't +> advertised there, the mapping silently never runs, the access token carries +> no `aud`, and every MCP call fails with 401 +> `error_description="claim invalid: aud"` — even though the OAuth handshake, +> consent, and PKCE all succeeded. Verify with: +> +> ```bash +> curl -s https://memory.example.com/.well-known/oauth-protected-resource \ +> | jq .scopes_supported # must include aud- +> ``` +> +> Note also that Claude Code sends an RFC 8707 `resource` parameter on the +> authorize request; Authentik 2026.5 ignores it, so it cannot be relied on +> for audience binding. The scope mapping is what sets `aud`. Then create an **Application** for the MCP provider (same as Step A), slug e.g. `shared-memory-mcp`. diff --git a/apps/web/app/.well-known/oauth-protected-resource/route.ts b/apps/web/app/.well-known/oauth-protected-resource/route.ts index f276121..d95f9a4 100644 --- a/apps/web/app/.well-known/oauth-protected-resource/route.ts +++ b/apps/web/app/.well-known/oauth-protected-resource/route.ts @@ -12,10 +12,18 @@ export const dynamic = "force-dynamic"; */ export function GET() { const resource = env().PUBLIC_URL.replace(/\/$/, ""); + + // The audience scope MUST be advertised. Authentik only evaluates a scope + // mapping when the client requests that scope by name, and the client only + // learns scope names from this document. Omit it and every access token + // arrives without `aud`, which jwt.ts rejects as "claim invalid: aud". + const audienceScope = + env().OIDC_AUDIENCE_SCOPE ?? `aud-${env().OIDC_AUDIENCE}`; + return NextResponse.json({ resource, authorization_servers: [env().OIDC_ISSUER], - scopes_supported: ["openid", "profile", "email"], + scopes_supported: ["openid", "profile", "email", audienceScope], bearer_methods_supported: ["header"], resource_documentation: `${resource}/`, }); diff --git a/apps/web/lib/env.ts b/apps/web/lib/env.ts index b58a264..8400e1d 100644 --- a/apps/web/lib/env.ts +++ b/apps/web/lib/env.ts @@ -18,6 +18,17 @@ const envSchema = z.object({ OIDC_CLIENT_ID_MCP: z.string().min(1), OIDC_AUDIENCE: z.string().min(1), + // Name of the IdP scope whose mapping emits `aud: `. + // + // Most IdPs (Authentik included) only evaluate a scope mapping when the + // client actually requests that scope. The MCP client learns which scopes + // to request from `scopes_supported` in our protected-resource metadata, + // so this name has to be advertised there or the mapping never runs and + // every token arrives without an `aud` claim (-> 401 "claim invalid: aud"). + // + // Defaults to the `aud-` convention used in the README setup. + OIDC_AUDIENCE_SCOPE: z.string().min(1).optional(), + // Database DATABASE_URL: z.string().url(),